Skip to content

CLAUDE.md

Latest commit

 

History

History
154 lines (114 loc) · 6.11 KB

CLAUDE.md

File metadata and controls

154 lines (114 loc) · 6.11 KB

CLAUDE.md

Pythinker is an AI Agent system that runs tools (browser, terminal, files, search) in isolated Docker sandbox environments. FastAPI backend with Domain-Driven Design, Vue 3 frontend, Docker containers for task isolation.

Read instructions.md first — it defines the core behavioral contract (assumptions, simplicity, surgical changes, goal-driven execution).

Project Principles

These extend instructions.md with project-specific constraints:

  1. Reuse First: Search existing codebase before creating anything new — never duplicate logic, constants, or structure
  2. Self-Hosted First: Prioritize self-hosted, zero-cost, open-source solutions with no external dependencies
  3. Dependency Rule: Domain → Application → Infrastructure → Interfaces (inward only)
  4. Type Safety: Full type hints (Python) / strict mode (TypeScript); no any
  5. Context7 Validation: Validate new implementations against fetched Context7 MCP documentation before deployment

Development Commands

Full Stack

./dev.sh watch              # Start stack with live file watch (recommended)
./dev.sh up -d              # Start without watch
./dev.sh down -v            # Stop and remove volumes
./dev.sh logs -f backend    # Follow logs

Backend

cd backend && conda activate pythinker
ruff check . && ruff format --check .                # Lint
ruff check --fix . && ruff format .                  # Auto-fix
pytest tests/path/to/test_file.py                    # Targeted tests (ALWAYS prefer this)
pytest -p no:cov -o addopts= tests/test_file.py     # Single test without coverage
# NEVER run `pytest tests/` (full suite) unless explicitly asked

Frontend

cd frontend
bun run dev          # Dev server (5173)
bun run lint         # ESLint fix
bun run type-check   # TypeScript check
bun run test:run     # Single test run

Before Committing

# Backend
cd backend && ruff check . && ruff format --check . && pytest tests/<relevant-dir-or-file>
# Frontend
cd frontend && bun run lint && bun run type-check

Commit Strategy (Mandatory)

  • Split into multiple atomic commits grouped by logical concern
  • Each commit must be independently revertable — one concern, one commit
  • Format: fix(scope) / feat(scope) / refactor(scope) / chore(scope) / docs(scope) / test(scope)
  • Stage files selectively with git add <specific-files> — never git add . for multi-concern changesets

Architecture

Backend DDD Structure (backend/app/)

  • domain/: Core business logic, models, services, abstract repositories
  • application/: Use case orchestration, DTOs
  • infrastructure/: MongoDB/Redis implementations, external adapters (LLM, browser, search)
  • interfaces/api/: REST routes, request/response schemas
  • core/: Config, sandbox manager, workflow manager

Frontend Structure (frontend/src/)

  • pages/: Route components (ChatPage, HomePage)
  • components/: UI components (ChatMessage, SandboxViewer, ToolPanel)
  • composables/: Shared logic (useChat, useSession, useAgentEvents)
  • api/: HTTP client with SSE support

Key Patterns

  • Event Sourcing: Session events in MongoDB
  • SSE Streaming: Real-time events to frontend
  • Sandbox Isolation: Docker containers with CDP screencast

Hard Constraints

  • HTTPClientPool: Always use HTTPClientPool for HTTP communication. Never create httpx.AsyncClient directly.
  • APIKeyPool: Always use APIKeyPool for external API providers. Never create direct API clients without key pool integration.
  • Pydantic v2: @field_validator methods must be @classmethod
  • Python environment: Always conda activate pythinker before running backend tests
  • Full implementations only: Never use placeholders (// ... rest of code). If complex, output as much as possible and wait for "Continue".
  • Pre-existing errors: Never skip or work around pre-existing lint/type/test failures. Report and fix them, or flag to the user.
  • Plan execution: Complete all phases — priority indicates order, not optionality.
  • Skill activation: When hooks display a skill activation banner, invoke the recommended skill immediately.

Environment Notes

Docker Compose Watch

Development uses Compose Watch for file sync + HMR. It syncs via Docker API (tar + cp), bypassing OrbStack's TCC bind-mount restriction. No polling required.

Port Mapping

Service Port
Frontend 5174
Backend 8000
Sandbox API 8083
MongoDB 27017
Redis 6379
Qdrant 6333/6334

Code Style

  • Python: 4-space indent, snake_case functions, PascalCase classes
  • Vue/TS: 2-space indent, PascalCase components, useX composables
  • Linting: Ruff (backend), ESLint (frontend)

Deeper Reference

Architecture and subsystem docs (read on demand, not upfront):

Configuration

  • Copy .env.example to .env for local runs
  • MCP integration via mcp.json.example
  • Docker socket mount: -v /var/run/docker.sock:/var/run/docker.sock

Quality Gates

Hooks in ~/.claude/settings.json enforce quality automatically (lint on edit, type-check on save, --no-verify blocking). Commands: /verify, /verify quick, /verify pre-pr, /de-sloppify, /learn, /evolve.