# 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.