Global Claude Code Settings

General Preferences

• Concise responses preferred
• Use TypeScript over JavaScript when possible
• Prefer functional programming patterns
• Write tests for new functionality

Code Style

• 2 spaces for indentation (JS/TS)
• 4 spaces for Python
• Single quotes for strings (JS/TS)
• No trailing commas
• Meaningful variable names

Git Workflow

• Write clear, concise commit messages
• One logical change per commit
• Run tests before committing
• Update CHANGELOG.md in the same commit — every behaviour/config/docs/deps change ships a changelog entry (see rules/changelog.md). No commit without one.

Tools & Frameworks

• Package manager: npm (Node.js), pip (Python)
• Testing: Jest/Vitest (JS), pytest (Python)
• Linting: ESLint (JS), ruff/black (Python)

Engineering Policy

TDD — Non-Negotiable

ALWAYS write tests before implementation. No exceptions.

1. Read the requirement
2. Write failing tests that describe the expected behaviour
3. Run tests — confirm they fail for the right reason
4. Write the minimum implementation to pass
5. Refactor, keep tests green
6. Never write a function, class, or API endpoint without a corresponding test

If asked to add a feature without tests, write the tests first then ask to proceed. If a PR diff shows untested code paths, flag them before continuing.

Model Routing — Token Economy (13-Tier)

Use Gemini Flash-Lite (Tier 1) for:

• Bulk extraction and classification pipelines
• Cheap summarization, CIG data processing
• Non-code batch tasks (cheapest model at $0.10/M)

Invoke: gemini --flash-lite ""

Use DeepSeek Flash (Tier 2) for:

• Simple code tasks, boilerplate, CRUD, config changes
• Single-file additions, small bug fixes

Invoke: deepseek --flash ""

Use DeepSeek Pro (Tier 4) for:

• Multi-file features and refactors
• Debugging, API endpoints, test suites
• Documentation writing — main coding workhorse

Invoke: deepseek --pro ""

Use Gemini Flash (Tier 5) for:

• Multimodal tasks (image screenshots, brand assets)
• Video content processing and analysis
• Audio transcription review

Invoke: gemini --flash ""

Use Gemini CLI (Tier 5) for:

• Agentic coding tasks with file read/write
• Multi-file implementation within Google ecosystem
• Alternative coding agent for medium-complexity work

Invoke: gemini-cli --pro ""

Use AGY / Antigravity (Tier 6) for:

• End-to-end implementation (git operations, file edits, testing)
• Terminal coding agent tasks (Google's coding agent)
• Multi-step implementation with autonomous execution

Invoke: agy-delegate --print "" Invoke (headless): agy-delegate --headless ""

Use kimi (Tier 7) for:

• Commit messages, changelogs, diff summaries
• Research questions needing reasoning
• Quick single-model analysis

Invoke: kimi ""

Multi-Model Review

For architecture/code reviews, run DeepSeek + Kimi + Codex in parallel instead of single-model:

~/bin/review --all "review this implementation"
~/bin/review --deepseek --kimi "architecture review of auth module"

• Agree/disagree analysis across all three reviewers
• Estimated cost: ~$0.02 per review (vs $3-5 for Claude solo)
• Review log: ~/.claude/review-log.jsonl

Use Gemini Pro Search (Tier 7) for:

• Deep research with native Google Search grounding
• Competitor intelligence and market research
• 2M context document analysis

Invoke: gemini --pro-search ""

Use Grok (Tier 9) for:

• Competitor intelligence and CKG building
• Deep reasoning and market analysis
• Truthful, insightful research

Invoke: grok ""

Use Codex (Tier 10) for:

• Large-scale boilerplate or test generation
• Mechanical changes across many files
• Code review (codex-review)

Use Claude (Tier 11) for:

• Architecture and system design
• Security-critical code
• Complex debugging, multi-service refactors
• Customer-facing quality-critical code

Autonomous Plan → Validate → Execute

When a task requires planning (CLAUDE tier), the full cycle is automated:

Goal detected → Enter plan mode → Write plan to ~/.claude/plans/
    ↓
~/bin/validate-plan --threshold 2 <plan-file>
    ↓ (DeepSeek Pro + Codex + Gemini Pro vote in parallel)
2+ APPROVED → Auto-approve → Execute immediately
1 APPROVED → Surface to user with reviewer feedback
0 APPROVED → Revise plan, re-validate

Goal detection: The route-task-hook classifies tasks. CLAUDE tier (architecture, security, complex system design) → PLAN FIRST. DEEPSEEK_PRO/GEMINI_CLI (features, refactors) → EXECUTE DIRECTLY.

Multi-model validation: After writing a plan, run ~/bin/validate-plan which sends the plan to DeepSeek Pro, Codex, and Gemini Pro in parallel. Each evaluates approach completeness, edge cases, scope, and safety. Need 2+ approvals to auto-execute.

Approval thresholds:

• 3/3 approved → execute silently
• 2/3 approved → execute with minority feedback noted
• 1/3 approved → surface to user, show reviewer critiques
• 0/3 approved → revise plan, re-validate

PR Workflow — Required Steps

Before any PR is considered done:

1. All tests pass locally
2. Run: pr-review [base-branch]
3. Fix all issues flagged by CodeRabbit and Codex review
4. Confirm test coverage includes the new code paths
5. Write a clear PR description: what, why, how

Routing heuristic:

• Lookup / one-liner → handle directly (no delegation)
• Bulk extraction / classification → Gemini Flash-Lite
• Simple code / boilerplate → DeepSeek Flash
• Multimodal / video / images → Gemini Flash
• Features / refactors / debugging → DeepSeek Pro
• Agentic coding / multi-file impl → Gemini CLI
• End-to-end impl / git+code+test → AGY (Antigravity)
• Review / reasoning → kimi
• Deep research / Google grounding → Gemini Pro Search
• Competitor intel / deep reasoning → Grok
• Bulk generation → Codex
• Architecture / security / quality-critical → Claude
• Before PR → pr-review script

DeepSeek handles ~80% of coding work. Gemini CLI and AGY handle agentic implementation. Gemini fills multimodal, research, and bulk extraction gaps. Reserve Claude for quality-critical tasks.

Tool Fallback Protocol

When built-in tools (WebSearch, WebFetch) return errors or empty results, retry with external backends:

Research Tool (~/bin/research)

Multi-backend research with auto-evaluation:

• Tries deepseek-flash → deepseek-pro in sequence
• Scores results on 0-10 scale (content quality, structure, length)
• Auto-adjusts preferred backend based on evaluation scores
• When WebSearch fails: run ~/bin/research "your search query"
• Evaluation stats: ~/bin/research --eval
• Score log: ~/.claude/research-eval.jsonl

Followed Model & Pre-Analysis (hook signals)

The route-task hook injects two signals into every prompt — act on them:

• FOLLOWED MODEL: <name> — the user's chosen primary model (/model-config). For substantial coding, prefer delegating to it.
• MINIMAX PRE-ANALYSIS: ... — a terse INTENT / SCOPE / RISKS / APPROACH brief. Use it to execute directly instead of re-deriving the task.

The choice lives in ~/.claude/model-config.json (primary, classifier, mode, analyze) and is shared by the hooks, Maggy, and srooter. See GETTING_STARTED.md for setup.