@@ -1,39 +1,130 @@
1# Crush Development Guide
1# Crush Development Guide
5+Crush is a terminal-based AI coding assistant built in Go by
6+[Charm](https://charm.land). It connects to LLMs and gives them tools to read,
7+write, and execute code. It supports multiple providers (Anthropic, OpenAI,
8+Gemini, Bedrock, Copilot, Hyper, MiniMax, Vercel, and more), integrates with
9+LSPs for code intelligence, and supports extensibility via MCP servers and
12+The module path is `github.com/charmbracelet/crush`.
17+main.go CLI entry point (cobra via internal/cmd)
19+ app/app.go Top-level wiring: DB, config, agents, LSP, MCP, events
20+ cmd/ CLI commands (root, run, login, models, stats, sessions)
22+ config.go Config struct, context file paths, agent definitions
23+ load.go crush.json loading and validation
24+ provider.go Provider configuration and model resolution
26+ agent.go SessionAgent: runs LLM conversations per session
27+ coordinator.go Coordinator: manages named agents ("coder", "task")
28+ prompts.go Loads Go-template system prompts
29+ templates/ System prompt templates (coder.md.tpl, task.md.tpl, etc.)
30+ tools/ All built-in tools (bash, edit, view, grep, glob, etc.)
31+ mcp/ MCP client integration
32+ session/session.go Session CRUD backed by SQLite
33+ message/ Message model and content types
34+ db/ SQLite via sqlc, with migrations
35+ sql/ Raw SQL queries (consumed by sqlc)
36+ migrations/ Schema migrations
37+ lsp/ LSP client manager, auto-discovery, on-demand startup
38+ ui/ Bubble Tea v2 TUI (see internal/ui/AGENTS.md)
39+ permission/ Tool permission checking and allow-lists
40+ skills/ Skill file discovery and loading
41+ shell/ Bash command execution with background job support
42+ event/ Telemetry (PostHog)
43+ pubsub/ Internal pub/sub for cross-component messaging
44+ filetracker/ Tracks files touched per session
45+ history/ Prompt history
48+### Key Dependency Roles
50+- **`charm.land/fantasy`**: LLM provider abstraction layer. Handles protocol
51+ differences between Anthropic, OpenAI, Gemini, etc. Used in `internal/app`
52+ and `internal/agent`.
53+- **`charm.land/bubbletea/v2`**: TUI framework powering the interactive UI.
54+- **`charm.land/lipgloss/v2`**: Terminal styling.
55+- **`charm.land/glamour/v2`**: Markdown rendering in the terminal.
56+- **`charm.land/catwalk`**: Snapshot/golden-file testing for TUI components.
57+- **`sqlc`**: Generates Go code from SQL queries in `internal/db/sql/`.
61+- **Config is a Service**: accessed via `config.Service`, not global state.
62+- **Tools are self-documenting**: each tool has a `.go` implementation and a
63+ `.md` description file in `internal/agent/tools/`.
64+- **System prompts are Go templates**: `internal/agent/templates/*.md.tpl`
65+ with runtime data injected.
66+- **Context files**: Crush reads AGENTS.md, CRUSH.md, CLAUDE.md, GEMINI.md
67+ (and `.local` variants) from the working directory for project-specific
69+- **Persistence**: SQLite + sqlc. All queries live in `internal/db/sql/`,
70+ generated code in `internal/db/`. Migrations in `internal/db/migrations/`.
71+- **Pub/sub**: `internal/pubsub` for decoupled communication between agent,
73+- **CGO disabled**: builds with `CGO_ENABLED=0` and
74+ `GOEXPERIMENT=greenteagc`.
3## Build/Test/Lint Commands
76## Build/Test/Lint Commands
5- **Build**: `go build .` or `go run .`
78- **Build**: `go build .` or `go run .`
79+- **Test**: `task test` or `go test ./...` (run single test:
6−- **Test**: `task test` or `go test ./...` (run single test: `go test ./internal/llm/prompt -run TestGetContextFromPaths`)
80+ `go test ./internal/llm/prompt -run TestGetContextFromPaths`)
7−- **Update Golden Files**: `go test ./... -update` (regenerates .golden files when test output changes)
81+- **Update Golden Files**: `go test ./... -update` (regenerates `.golden`
82+ files when test output changes)
83+ - Update specific package:
8− - Update specific package: `go test ./internal/tui/components/core -update` (in this case, we're updating "core")
84+ `go test ./internal/tui/components/core -update` (in this case,
85+ we're updating "core")
9- **Lint**: `task lint:fix`
86- **Lint**: `task lint:fix`
10- **Format**: `task fmt` (`gofumpt -w .`)
87- **Format**: `task fmt` (`gofumpt -w .`)
11−- **Modernize**: `task modernize` (runs `modernize` which make code simplifications)
88+- **Modernize**: `task modernize` (runs `modernize` which makes code
12- **Dev**: `task dev` (runs with profiling enabled)
90- **Dev**: `task dev` (runs with profiling enabled)
14## Code Style Guidelines
92## Code Style Guidelines
16−- **Imports**: Use `goimports` formatting, group stdlib, external, internal packages
94+- **Imports**: Use `goimports` formatting, group stdlib, external, internal
17−- **Formatting**: Use gofumpt (stricter than gofmt), enabled in golangci-lint
96+- **Formatting**: Use gofumpt (stricter than gofmt), enabled in
18−- **Naming**: Standard Go conventions - PascalCase for exported, camelCase for unexported
98+- **Naming**: Standard Go conventions — PascalCase for exported, camelCase
19−- **Types**: Prefer explicit types, use type aliases for clarity (e.g., `type AgentName string`)
100+- **Types**: Prefer explicit types, use type aliases for clarity (e.g.,
101+ `type AgentName string`).
20−- **Error handling**: Return errors explicitly, use `fmt.Errorf` for wrapping
102+- **Error handling**: Return errors explicitly, use `fmt.Errorf` for
21−- **Context**: Always pass `context.Context` as first parameter for operations
104+- **Context**: Always pass `context.Context` as first parameter for
22−- **Interfaces**: Define interfaces in consuming packages, keep them small and focused
106+- **Interfaces**: Define interfaces in consuming packages, keep them small
23−- **Structs**: Use struct embedding for composition, group related fields
108+- **Structs**: Use struct embedding for composition, group related fields.
24−- **Constants**: Use typed constants with iota for enums, group in const blocks
109+- **Constants**: Use typed constants with iota for enums, group in const
25−- **Testing**: Use testify's `require` package, parallel tests with `t.Parallel()`,
111+- **Testing**: Use testify's `require` package, parallel tests with
26− `t.SetEnv()` to set environment variables. Always use `t.Tempdir()` when in
112+ `t.Parallel()`, `t.SetEnv()` to set environment variables. Always use
27− need of a temporary directory. This directory does not need to be removed.
113+ `t.Tempdir()` when in need of a temporary directory. This directory does
114+ not need to be removed.
28−- **JSON tags**: Use snake_case for JSON field names
115+- **JSON tags**: Use snake_case for JSON field names.
29−- **File permissions**: Use octal notation (0o755, 0o644) for file permissions
116+- **File permissions**: Use octal notation (0o755, 0o644) for file
30−- **Log messages**: Log messages must start with a capital letter (e.g., "Failed to save session" not "failed to save session")
118+- **Log messages**: Log messages must start with a capital letter (e.g.,
119+ "Failed to save session" not "failed to save session").
31− - This is enforced by `task lint:log` which runs as part of `task lint`
120+ - This is enforced by `task lint:log` which runs as part of `task lint`.
32−- **Comments**: End comments in periods unless comments are at the end of the line.
121+- **Comments**: End comments in periods unless comments are at the end of the
34## Testing with Mock Providers
124## Testing with Mock Providers
36−When writing tests that involve provider configurations, use the mock providers to avoid API calls:
126+When writing tests that involve provider configurations, use the mock
127+providers to avoid API calls:
39func TestYourFunction(t *testing.T) {
130func TestYourFunction(t *testing.T) {
@@ -70,9 +161,12 @@ func TestYourFunction(t *testing.T) {
71## Committing
162## Committing
73−- ALWAYS use semantic commits (`fix:`, `feat:`, `chore:`, `refactor:`, `docs:`, `sec:`, etc).
164+- ALWAYS use semantic commits (`fix:`, `feat:`, `chore:`, `refactor:`,
165+ `docs:`, `sec:`, etc).
74- Try to keep commits to one line, not including your attribution. Only use
166- Try to keep commits to one line, not including your attribution. Only use
75 multi-line commits when additional context is truly necessary.
167 multi-line commits when additional context is truly necessary.
77## Working on the TUI (UI)
169## Working on the TUI (UI)
78−Anytime you need to work on the tui before starting work read the internal/ui/AGENTS.md file
171+Anytime you need to work on the TUI, read `internal/ui/AGENTS.md` before