grokkit/CLAUDE.md

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

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:

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:

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.