Recipe Book¶

Copy-paste commands for common tasks. Replace paths with your project.

Want the why behind each recipe?

Use Cases explains the pain, command, and benefit for each scenario — start there if you are piloting the agent on your team.

0. Fluid CLI — help + tab completion¶

code-agent -h                          # rich help + examples
code-agent run -h
code-agent experts run -h

code-agent --install-completion        # once per machine
# new terminal:
code-agent experts run <TAB>           # bug-fix, test-intel, …
code-agent run "…" --verify-cmd <TAB>  # pytest -q, go test ./..., …

More: Commands → Help & tab completion.

A. Fix Python unit tests¶

cd ~/karm/ai-code-agent
source .venv/bin/activate

# See failures first
pytest -q

# Option 1: direct run
code-agent run \
  "Fix all failing unit tests in tests/. Run pytest -q after each change until every test passes. Only change test and source code needed for failures — no refactors." \
  --verify-cmd "pytest -q" \
  -w .

# Option 2: bug-fix expert from log
pytest -q 2>&1 | tee /tmp/pytest.log
code-agent experts run bug-fix \
  --log /tmp/pytest.log \
  --verify-cmd "pytest -q" \
  -w .

B. Fix Go tests (external repo)¶

# See failures
cd /path/to/your-go-project && go test -v ./...

# Option 1: direct run
code-agent run \
  "Fix all failing Go unit tests. Run 'go test -v ./...' after each change until every test passes." \
  --verify-cmd "go test -v ./..." \
  -w /path/to/your-go-project

# Option 2: bug-fix expert
cd /path/to/your-go-project
go test -v ./... 2>&1 | tee /tmp/go-test.log

code-agent experts run bug-fix \
  --log /tmp/go-test.log \
  --verify-cmd "go test -v ./..." \
  -w /path/to/your-go-project

Common mistakes

Do not use pytest for Go projects
Use one -w pointing at the Go repo root

C. Raise code coverage (Python)¶

pytest -q --cov=code_agent --cov-report=term-missing --cov-fail-under=80 \
  2>&1 | tee /tmp/coverage-fail.log

code-agent experts run bug-fix \
  --log /tmp/coverage-fail.log \
  --verify-cmd "pytest -q --cov=code_agent --cov-report=term-missing --cov-fail-under=80"

See Coverage for the full runbook.

D. Run only impacted tests (PR CI)¶

code-agent experts run test-intel --base-branch main
# Run the printed verify_cmd in CI

E. Babysit a PR until CI green¶

code-agent experts watch --pr 42 --verify-cmd "pytest -q"

F. Fix from GitHub Actions run¶

code-agent experts run bug-fix \
  --run-id 123456789 \
  --verify-cmd "pytest -q" \
  --publish

Requires gh authenticated and repo access.

G. SRE alert → fix¶

code-agent experts run sre-expert \
  --log /path/to/alert.json \
  --verify-cmd "curl -sf http://localhost:8080/health" \
  --dry-run

H. Monitoring audit¶

code-agent experts run monitoring-expert --dry-run

I. Dry run (no writes)¶

code-agent run "Refactor error handling" --dry-run -w .
code-agent experts run bug-fix --log /tmp/ci.log --dry-run

J. Interactive chat on a project¶

code-agent chat -w /path/to/project
# type tasks; exit with: exit

code-agent chat --resume SESSION_ID -w /path/to/project

Prompt templates¶

Minimal fix:

Fix the failing tests. Run VERIFY_CMD after each change. Minimal diff only.

Add feature + test:

Add FEATURE. Add a test. Match existing code style. Run VERIFY_CMD until green.

Coverage:

Raise line coverage to THRESHOLD%. Add unit tests under tests/ for uncovered lines.
Do not delete production code. Do not edit .github/workflows.