DEAR_LLM.md

# DEAR_LLM.md for Sketch Repository

## Repository Architecture

Sketch is an agentic coding tool with a multi-layer architecture:

1. **Outer Sketch**: The CLI command (`sketch`) running on the user's machine
2. **Inner Sketch**: The binary running inside Docker containers
3. **Container System**: Docker containers isolate work environments

## Key Components

### Outer Sketch (Host)

- **cmd/sketch/main.go**: Entry point and CLI definitions
- **dockerimg/**: Container management (building, configuration, orchestration)

### Inner Sketch (Container)

- **loop/agent.go**: Core agent logic and tool implementations
- **loop/server/**: Server implementation inside containers

### Shared Components

- **webui/**: Web-based user interface components
- **llm/**: Language model interaction

## Development Workflows

### Development Modes

1. **Container Mode** (Default): `go run ./cmd/sketch -C /path/to/codebase`

   - Creates Docker container for code analysis
   - Safe and isolated environment

2. **Unsafe Mode**: `go run ./cmd/sketch -unsafe -C /path/to/codebase`
   - Runs directly on host OS without containerization
   - Useful for quick testing during development

### Source/Container Relationship

- Target codebase: Copied into container via `COPY . /app`
- Sketch itself: Binary built specifically for containers (`GOOS=linux`)
- Container configuration: Generated based on target codebase detection

## Common Gotchas

1. **Container Caching**: Docker image caching may require `-force-rebuild-container` when the target codebase changes

2. **Two Git Contexts**:

   - Sketch's own repository (where outer and inner Sketch code lives)
   - The target repository being analyzed by Sketch
   - Keep these separate in your mental model

3. **Inner/Outer Code Changes**:
   - Changes to inner Sketch (loop/agent.go) are built into the Linux binary for containers
   - Changes to outer Sketch (dockerimg/) affect how containers are created

## Flags and Settings

- `-unsafe`: Run without containerization
- `-force-rebuild-container`: Force Docker image rebuilding
- `-verbose`: Show detailed output and logs
- `-C /path/to/repo`: Specify target codebase path

See CONTRIBUTING.md for additional development guidance.