88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
Grokkit is a Go CLI that integrates the xAI Grok API with git workflows. It provides AI-assisted chat, file editing, commit message generation, multi-language linting, test generation, documentation, and automated todo workflows. The core philosophy is "The Developer Is The Agent" — the LLM enhances rather than replaces developer judgment.
|
||
|
|
|
||
|
|
## Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
make build # Build optimized binary to build/grokkit (with ldflags: version, commit, builddate)
|
||
|
|
make install # Build + install to ~/.local/bin
|
||
|
|
make test # Run all tests with -v -race
|
||
|
|
make test-cover # Generate HTML coverage report at build/coverage.html
|
||
|
|
make test-agent # Run only agent tests
|
||
|
|
make lint # Run golangci-lint (matches CI)
|
||
|
|
make clean # Remove build/ directory
|
||
|
|
```
|
||
|
|
|
||
|
|
To run a single test:
|
||
|
|
```bash
|
||
|
|
go test -run TestFunctionName ./cmd/...
|
||
|
|
go test -run TestFunctionName ./internal/grok/...
|
||
|
|
```
|
||
|
|
|
||
|
|
Required env var: `XAI_API_KEY=sk-...`
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
main.go → cmd.Execute()
|
||
|
|
cmd/ Cobra subcommands (~40 files). Each command: parse flags → load config → call internal packages → stream output
|
||
|
|
config/ Viper config from ~/.config/grokkit/config.toml; resolves model aliases; CLI flags > env > file > defaults
|
||
|
|
internal/
|
||
|
|
grok/ HTTP client with SSE streaming; AIClient interface for testability
|
||
|
|
git/ os/exec wrapper around git commands; GitRunner interface
|
||
|
|
linter/ Detects language by extension, runs available linters, supports 9 languages
|
||
|
|
errors/ Domain-specific error types (GitError, APIError, etc.)
|
||
|
|
prompts/ AI prompt construction
|
||
|
|
recipe/ Loads and executes transactional markdown workflow recipes
|
||
|
|
todo/ Task tracking
|
||
|
|
workon/ Automated branch+plan+execute workflow
|
||
|
|
logger/ slog facade; JSON to ~/.config/grokkit/grokkit.log
|
||
|
|
```
|
||
|
|
|
||
|
|
Key interfaces in `internal/grok/interface.go` (`AIClient`) and `internal/git/interface.go` (`GitRunner`) enable dependency injection for tests.
|
||
|
|
|
||
|
|
The typical command flow: CLI flags parsed → `config.Load()` → build prompt → `grok.Client.Stream()` (SSE) → display streamed output.
|
||
|
|
|
||
|
|
## Code Conventions
|
||
|
|
|
||
|
|
- Go 1.24.2
|
||
|
|
- Use `errors.Is`/`errors.Join`, `slices`, `maps` packages (modern Go)
|
||
|
|
- Table-driven tests with `t.Parallel()` and `t.Run()`
|
||
|
|
- Interface-based design for external dependencies (API, git)
|
||
|
|
- Structured logging via `internal/logger` (not fmt.Println for errors)
|
||
|
|
- Coverage target: >70% for internal packages
|
||
|
|
|
||
|
|
## Testing Notes
|
||
|
|
|
||
|
|
These are not unit-tested (require integration or E2E):
|
||
|
|
- Cobra command execution paths
|
||
|
|
- Terminal input (Scanln)
|
||
|
|
- API SSE streaming (would need mock HTTP server)
|
||
|
|
- `os.Exit()` paths
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
`~/.config/grokkit/config.toml`:
|
||
|
|
```toml
|
||
|
|
default_model = "grok-4"
|
||
|
|
temperature = 0.7
|
||
|
|
timeout = 60
|
||
|
|
|
||
|
|
[aliases]
|
||
|
|
fast = "grok-4-1-fast-non-reasoning"
|
||
|
|
|
||
|
|
[commands.lint.model]
|
||
|
|
"model" = "grok-4-1-fast-non-reasoning"
|
||
|
|
```
|
||
|
|
|
||
|
|
Model resolution: `--model` flag → config alias expansion → literal model name.
|
||
|
|
|
||
|
|
## CI
|
||
|
|
|
||
|
|
Gitea CI (`.gitea/workflows/ci.yml`): test → lint → build. golangci-lint v2.1.6. Release workflow builds multi-platform binaries with SHA256 checksums.
|