| Pokey Rule | d74572d | 2025-05-09 13:50:04 +0100 | [diff] [blame] | 1 | # DEAR_LLM.md for Sketch Repository |
| 2 | |
| 3 | ## Repository Architecture |
| 4 | |
| 5 | Sketch is an agentic coding tool with a multi-layer architecture: |
| 6 | |
| 7 | 1. **Outer Sketch**: The CLI command (`sketch`) running on the user's machine |
| 8 | 2. **Inner Sketch**: The binary running inside Docker containers |
| 9 | 3. **Container System**: Docker containers isolate work environments |
| 10 | |
| 11 | ## Key Components |
| 12 | |
| 13 | ### Outer Sketch (Host) |
| 14 | |
| 15 | - **cmd/sketch/main.go**: Entry point and CLI definitions |
| 16 | - **dockerimg/**: Container management (building, configuration, orchestration) |
| 17 | |
| 18 | ### Inner Sketch (Container) |
| 19 | |
| 20 | - **loop/agent.go**: Core agent logic and tool implementations |
| 21 | - **loop/server/**: Server implementation inside containers |
| 22 | |
| 23 | ### Shared Components |
| 24 | |
| 25 | - **webui/**: Web-based user interface components |
| 26 | - **llm/**: Language model interaction |
| 27 | |
| 28 | ## Development Workflows |
| 29 | |
| 30 | ### Development Modes |
| 31 | |
| 32 | 1. **Container Mode** (Default): `go run ./cmd/sketch -C /path/to/codebase` |
| 33 | |
| 34 | - Creates Docker container for code analysis |
| 35 | - Safe and isolated environment |
| 36 | |
| 37 | 2. **Unsafe Mode**: `go run ./cmd/sketch -unsafe -C /path/to/codebase` |
| 38 | - Runs directly on host OS without containerization |
| 39 | - Useful for quick testing during development |
| 40 | |
| 41 | ### Source/Container Relationship |
| 42 | |
| 43 | - Target codebase: Copied into container via `COPY . /app` |
| 44 | - Sketch itself: Binary built specifically for containers (`GOOS=linux`) |
| 45 | - Container configuration: Generated based on target codebase detection |
| 46 | |
| 47 | ## Common Gotchas |
| 48 | |
| 49 | 1. **Container Caching**: Docker image caching may require `-force-rebuild-container` when the target codebase changes |
| 50 | |
| 51 | 2. **Two Git Contexts**: |
| 52 | |
| 53 | - Sketch's own repository (where outer and inner Sketch code lives) |
| 54 | - The target repository being analyzed by Sketch |
| 55 | - Keep these separate in your mental model |
| 56 | |
| 57 | 3. **Inner/Outer Code Changes**: |
| 58 | - Changes to inner Sketch (loop/agent.go) are built into the Linux binary for containers |
| 59 | - Changes to outer Sketch (dockerimg/) affect how containers are created |
| 60 | |
| 61 | ## Flags and Settings |
| 62 | |
| 63 | - `-unsafe`: Run without containerization |
| 64 | - `-force-rebuild-container`: Force Docker image rebuilding |
| 65 | - `-verbose`: Show detailed output and logs |
| 66 | - `-C /path/to/repo`: Specify target codebase path |
| 67 | |
| 68 | See CONTRIBUTING.md for additional development guidance. |