Anthropic · Claude Code

ChooChoo for Claude Code.

Context engineering for the most capable coding agent.

Claude Code reads CLAUDE.md at session start — your team's standards, architecture, and guardrails loaded before the first keystroke. ChooChoo generates, maintains, and governs those files across every repo.

Book an Intro Call Get ChooChoo free

Configuration

One settings file. Full agent governance.

ChooChoo generates .claude/settings.json — the single file that controls what Claude Code can and can't do. Permissions whitelist safe commands and blacklist dangerous ones. Hooks run deterministically at every stage of the agent lifecycle. Checked into git, enforced on every developer's machine.

Allow-list safe commands: test runners, linters, git read operations
Deny-list destructive operations: force push, rm -rf, curl, DROP TABLE
PreToolUse hooks block dangerous commands before they execute
PostToolUse hooks lint after every edit; Stop hooks verify before finishing
Project settings shared via git; personal overrides in settings.local.json

.claude/settings.json

{
  "permissions": {
    "allow": [
      "Bash(mise run test*)",
      "Bash(mise run lint*)",
      "Bash(mise run fmt*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git branch*)",
      "Bash(uv run pytest*)",
      "Read",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(git checkout -- *)",
      "Bash(curl*)",
      "Bash(wget*)",
      "Bash(docker rm*)",
      "Bash(DROP TABLE*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "choochoo guard check-command"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "choochoo guard lint-changed"
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "choochoo guard verify-done"
        }]
      }
    ]
  },
  "env": {
    "CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD": "1"
  }
}

Context Files

CLAUDE.md — the file Claude reads first.

Claude Code loads CLAUDE.md from the project root at every session start. It's the single source of truth for how the agent should behave in your repo — commands, code standards, guardrails, and architecture decisions.

Loaded automatically from project root, .claude/, parent dirs, and subdirectories
Subdirectory CLAUDE.md files load on-demand as Claude navigates your repo
User-level ~/.claude/CLAUDE.md applies your personal defaults across all projects
ChooChoo generates and keeps them current — no manual maintenance

# CLAUDE.md
# Generated by ChooChoo — do not edit by hand.
# Run: choochoo context generate

## What this is
payments-api: a FastAPI service handling financial
transactions. Provides Claude Code with structured
startup context for this repository.

## Commands
mise run dev     Start dev server (hot-reload on)
mise run test    Full test suite (pytest -v)
mise run lint    Ruff lint check
mise run fix     Auto-fix lint + format

## Code Standards
- Python 3.12 with strict mypy — no untyped Any
- Ruff formatting (line-length = 100)
- Pydantic models for all API inputs/outputs
- Tests required for all new business logic

## Guardrails
- Never log secrets, payment tokens, or card data
- SQL through SQLAlchemy ORM — no raw strings
- All external inputs validated at the API boundary

## Architecture
ADR-001  JWT (RS256) — keys in secrets manager
ADR-007  API versioned under /v1/, /v2/ namespaces

# SKILLS.md
# Generated by ChooChoo — do not edit by hand.

## auth
JWT token lifecycle: creation, validation, refresh.
  Entry: src/auth/service.py
  Tests: tests/auth/

## payments
Stripe integration: charges, subscriptions, webhooks.
  Entry: src/payments/processor.py
  Note:  Never log STRIPE_KEY or card numbers

## database
SQLAlchemy sessions and query patterns.
  Entry: src/db/session.py
  Rule:  Always use get_db() dependency injection

## notifications
Email (SendGrid) and SMS (Twilio) dispatch.
  Entry: src/notifications/dispatch.py

# PLAN.md
# Generated by ChooChoo — do not edit by hand.

## Goal
Refactor the authentication service to support
multi-factor authentication (MFA) via TOTP.

## Steps
1. [ ] Add TOTP secret column to users table
       migration: src/db/migrations/0023_add_totp.py
2. [ ] Implement TOTP validation in auth service
       src/auth/service.py → verify_totp()
3. [ ] Add /auth/mfa/setup and /auth/mfa/verify routes
       src/api/auth.py
4. [ ] Write unit tests for new MFA paths
       tests/auth/test_mfa.py (≥ 90% coverage)
5. [ ] Update AGENTS.md with new ADR-012

## Constraints
- Do not break existing JWT flow (ADR-001)
- TOTP secrets encrypted at rest (AES-256)
- Rate-limit /auth/mfa/verify to 5 attempts / 15 min

# ARCHITECTURE.md
# Generated by ChooChoo — do not edit by hand.

## System Overview
payments-api is a stateless FastAPI service.
All state lives in PostgreSQL (primary data) and
Redis (sessions, rate limiting, event streams).

## Request Flow
Client → API Gateway → FastAPI → Service Layer
                                → Repository Layer
                                → PostgreSQL / Redis

## Key Modules
src/auth/        JWT issuance + TOTP (ADR-001, ADR-012)
src/payments/    Stripe integration (charges, webhooks)
src/db/          SQLAlchemy sessions + migration runner
src/api/         Route definitions (v1 + v2 namespaces)

## ADR Index
ADR-001  RS256 JWT for authentication
ADR-004  Redis Streams for webhook event bus
ADR-007  URL versioning (/v1/, /v2/)
ADR-012  TOTP-based MFA (in progress)

## Deployment
Docker → ECS Fargate  (app)
RDS PostgreSQL 15      (primary)
ElastiCache Redis 7    (cache + streams)

# GOAL.md
# Generated by ChooChoo — do not edit by hand.

## Current Sprint Goal
Implement MFA support without breaking existing
single-factor authentication flows.

## Success Criteria
- All existing auth tests continue to pass
- New /auth/mfa/* endpoints return correct responses
- TOTP validation rejects tokens older than 30 s
- Coverage for src/auth/ stays above 90%

## Out of Scope
- SMS-based MFA (deferred to ADR-013)
- Admin UI for MFA management (separate ticket)
- Recovery codes (phase 2)

## Definition of Done
- PR reviewed and approved
- CI green (lint + test + coverage)
- AGENTS.md updated with ADR-012 summary
- Deployed to staging and smoke-tested

{
  "version": "0.1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-23T14:30:00Z",
  "vcs": {
    "type": "git",
    "revision": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  },
  "tool": { "name": "cursor", "version": "2.4.0" },
  "files": [
    {
      "path": "src/utils/parser.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "anthropic/claude-opus-4-5-20251101"
          },
          "ranges": [
            {
              "start_line": 42,
              "end_line": 67,
              "content_hash": "murmur3:9f2e8a1b"
            }
          ],
          "related": [
            {
              "type": "session",
              "url": "https://api.cursor.com/v1/sessions/67890"
            }
          ]
        }
      ]
    },
    {
      "path": "src/utils/helpers.ts",
      "conversations": [
        {
          "url": "https://api.cursor.com/v1/conversations/12345",
          "contributor": {
            "type": "ai",
            "model_id": "openai/gpt-4o"
          },
          "ranges": [
            { "start_line": 10, "end_line": 25 }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "confidence": 0.95,
    "dev.cursor": { "workspace_id": "ws-abc123" }
  }
}

Topic Rules

.claude/rules/ — modular context by topic.

Break your instructions into focused rule files instead of one massive CLAUDE.md. Claude Code discovers and loads all .md files in .claude/rules/ automatically — security rules, testing conventions, service patterns, each in its own file.

One file per concern: security.md, testing.md, services.md
Checked into git so every team member gets the same rules
ChooChoo generates rules from your actual linting config, ADRs, and CI setup
Staleness detection alerts you when rules drift from your codebase

# Security Rules

## Secrets Management
- Never paste real API keys or tokens into prompts
- Virtual keys belong in .claude/settings.local.json
- .env files are deny-listed in permissions

## Database Safety
- Never manually delete system tables
- Use parameterized queries with asyncpg
- Don't run DROP TABLE without confirmation

## Gateway
- Virtual keys are per-user credentials
- Changes to gateway config affect all users

# Testing Rules

## Running Tests
mise run test     Full test suite (pytest -v)
mise run lint     Ruff lint check

## Philosophy
- Integration tests use real infrastructure
- Mocking is a last resort
- Tests must be deterministic

## When Tests Fail
1. Read the full traceback
2. Determine if test bug or app bug
3. Fix the root cause, not the symptom
4. Re-run the specific failing test
5. Run the full suite before committing

Why use ChooChoo with Claude Code?

Claude Code is the most configurable coding agent available. ChooChoo makes sure that configurability works for your team, not against it.

Context That Stays Current

CLAUDE.md and .claude/rules/ generated from your actual codebase — not a snapshot from six months ago. Auto-updated when standards change.

Deterministic Guardrails

Hooks block dangerous operations before they execute. Permission settings deny force-push, rm -rf, and other destructive commands.

Team-Wide Consistency

Project settings checked into git mean every developer's Claude Code follows the same rules. No per-machine configuration drift.

Full Session Visibility

ChooChoo's local app indexes every Claude Code session — full-text search, cost tracking, and quality scores across your team.

Eval-Driven Improvement

Agent readiness scoring tells you how well Claude Code performs in your repo. Context files improve automatically based on eval results.

Works With Your Stack

ChooChoo reads your linting config, ADRs, CI pipelines, and test conventions — then compiles context files that reflect your actual engineering standards.

Get the most out of Claude Code.

Context files, hooks, settings, and permissions — generated and maintained by ChooChoo.

Book a Demo Get ChooChoo free