alinaqi/claude-bootstrap: Multi-Agent TDD Engineering for Claude Code

alinaqi/claude-bootstrap: Multi-Agent TDD Engineering for Claude Code

Meta description: alinaqi/claude-bootstrap turns Claude Code into a self-reviewing, test-enforced engineering system with 67 skills, multi-model routing, and persistent memory.

Introduction

If you're using Claude Code daily, you've hit the same friction: context evaporates between sessions, trivial tasks burn expensive tokens, and code quality depends entirely on whether you remembered to ask for tests. There's no enforcement—no gate that stops a deployment when ADR compliance slips or coverage drops. And when you try to run multiple agents on the same repository, file conflicts and branch collisions kill productivity.

alinaqi/claude-bootstrap addresses these gaps directly. What began as an opinionated configuration pack for Claude Code has evolved into an autonomous AI engineering command center—701 GitHub stars, 54 forks, 1100+ passing tests, and a 6.37.0 release as of July 2026. It installs in roughly 30 seconds, requires no API keys to start, and layers on multi-model routing, Docker^{↗ Bright Coding Blog}-isolated parallel agents, and intent-grounded testing when you're ready.

This article breaks down what the system actually does, how it works under the hood, and whether it fits your workflow.

What is alinaqi/claude-bootstrap?

alinaqi/claude-bootstrap is an open-source MIT-licensed project maintained by Ali Naqi. It consists of two integrated components living in a single repository: Claude Bootstrap (the config pack) and Maggy (the optional harness server).

Claude Bootstrap installs skills, hooks, rules, and templates into ~/.claude/. It works with Claude Code and also supports Codex, Kimi, and Gemini CLI. The 67 skills cover Python^{↗ Bright Coding Blog}, TypeScript, React^{↗ Bright Coding Blog}, React Native, Flutter, Supabase, Firebase, Stripe, Playwright, security practices, and cross-agent delegation. Hooks enforce TDD—tests must pass before Claude considers a task complete—and impose quality gates (20 lines maximum per function, 3 parameters maximum, 2 nesting levels maximum).

Maggy is a local FastAPI server with a web dashboard. It adds 13-tier model routing, YAML-defined skill protocols, the Telos testing framework, Cortex MCP code intelligence, Polyphony for parallel agent execution, and a plugin architecture. Maggy requires Python 3.11+ and takes roughly 5 minutes to set up.

The project sits at the intersection of AI-assisted development tooling and engineering process automation. With 701 stars and active commits through mid-2026, it has traction among solo engineers and platform teams who need reproducible, observable AI engineering workflows.

Key Features

TDD Enforcement & Quality Gates Stop hooks prevent task completion until tests pass. Quality gates enforce structural constraints per file—function length, parameter count, nesting depth. These aren't suggestions; they're hard stops in the execution pipeline.

67 Skills with Protocol Engine Skills range from language-specific scaffolding (Python, TypeScript, React) to infrastructure (Supabase, Firebase, Stripe) to process (security reviews, ADR authoring, cross-agent delegation). Maggy's YAML protocol engine turns intents like "push to git" into multi-step workflows: lint → typecheck → test → stage → commit → push.

Mnemos & Engram Memory Systems Mnemos provides task-scoped memory with a 4-dimension fatigue model. It auto-checkpoints when session fatigue exceeds thresholds and compresses context through micro-consolidation. Engram persists architectural knowledge across sessions with 7 amnesia type classifications, addressing the context-loss problem that plagues long-running Claude Code projects.

iCPG (Intent-Augmented Code Property Graph) Stores why code exists, not just what it does. Six-dimension drift detection prevents duplicate implementations by tracking intent across the codebase.

13-Tier Model Routing Every message gets a semantic blast score (1–10). A local Qwen3 classifier handles triage and bulk operations for free. Complex coding routes to DeepSeek Pro or Kimi. Architecture and security reviews hit Claude Sonnet or Opus. Budget caps with auto-demotion prevent runaway costs.

Cortex MCP Code intelligence with 10 edge types, cyclomatic complexity analysis, FTS5 search, and bidirectional graph traversal. Fifteen MCP tools expose this through a single SQLite database.

Polyphony Docker-isolated parallel agent execution. A second Claude Code session in the same project auto-provisions its own workspace with a full git clone on a separate branch.

Use Cases

Solo Engineers Seeking TDD Discipline You use Claude Code but forget to request tests, or you accept refactors that break existing coverage. Bootstrap's stop hooks make test passage mandatory. The Mnemos fatigue model auto-checkpoints before context compaction destroys your working memory. You get enforcement without workflow changes.

Teams Routing Work Across Multiple Models Your organization has API keys for Claude, DeepSeek, Kimi, Gemini, and Grok but no systematic way to choose between them. Maggy's 13-tier routing sends bulk documentation to Gemini Flash-Lite, complex refactors to DeepSeek Pro, and security reviews to Claude Opus—automatically, with budget caps and fallback chains.

Platform Engineers Building AI Tooling You need a reference implementation for intent tracking, protocol execution, and plugin architecture. The unified ChatPipeline orchestrator, YAML skill protocols, and drop-in plugin system (Build-in-Public, Telos, GitHub/Asana/Monday providers) provide concrete patterns to adapt or extend.

Multi-Agent Development Without Collisions Two engineers (or two agent sessions) working the same repository. Polyphony's auto-isolation puts each on its own branch in a Docker container with a full clone. No file locks, no merge conflicts from simultaneous edits.

ADR-Compliant Codebases Non-trivial changes require an Architectural Decision Record. Bootstrap enforces this: missing ADRs trigger reverse-engineering from git history. iCPG stores the intent behind decisions, preventing architectural drift that tests alone won't catch.

Installation & Setup

Bootstrap Only — 30 Seconds

git clone https://github.com/alinaqi/maggy.git
cd maggy && ./install.sh

Your next Claude Code session picks up the skills, hooks, and rules automatically. No further configuration required.

Full Maggy Harness — Zero-Config Start

pipx install maggy-harness   # or: pip install maggy-harness
maggy bootstrap              # installs skills, hooks, ~/bin model wrappers, plugins
maggy serve                  # auto-configures from your local repos,
                             # then opens the dashboard at localhost:8080

Or from source:

cd maggy && ./install.sh && maggy serve

What happens on first launch: Maggy discovers your local git repositories and opens the dashboard pointed at them. No API keys are required for local mode. Add GITHUB_TOKEN and ANTHROPIC_API_KEY later only if you want GitHub sync or API-model features.

Polyphony one-time setup:

polyphony init                 # create ~/.polyphony/ config

Then from Claude Code: /polyphony-init, /polyphony-spawn, /polyphony-status. Requires Docker or OrbStack.

Real Code Examples

Example 1: Routing a Security Review Task

The README documents this interaction pattern:

You: "review the auth middleware for timing attacks"
→ Blast score: 8/10 (security + architecture)
→ Routed to: Claude (Tier 11)
→ ADR gate: found docs/adr/0003-jwt-strategy.md → injected as context
→ Review runs with full architectural context

This demonstrates the full pipeline: intent classification, model selection, context retrieval from the iCPG/ADR system, and execution with enriched background. The blast score prevents a Tier 0 model from attempting security analysis; the ADR gate ensures the review references actual architectural decisions rather than hallucinating constraints.

Example 2: Skill Protocol Execution — Git Push

You: "push to git"
→ Intent matched: git-push protocol
→ ✅ lint       (2.1s)
→ ✅ typecheck   (4.3s)
→ ✅ tests       (11.2s)
→ ✅ stage
→ ✅ commit      [AI-generated: "fix: resolve token refresh race condition"]
→ ✅ push

This YAML-defined protocol lives in maggy/skills/protocols/. You can drop a .yaml file to add custom protocols. The protocol engine handles intent matching, sequential execution, timing, and AI-generated commit messages. Failure at any step halts the chain.

Example 3: Fatigue-Aware Memory Checkpoint

Session fatigue: 0.61 (PRE-SLEEP)
→ Mnemos: auto-checkpoint written
→ Micro-consolidation: 3 ResultNodes compressed
→ iCPG context injected: 2 ReasonNodes, 1 constraint
→ Context freed: ~18k tokens

This shows Mnemos operating at a quantified fatigue threshold. The system writes a typed checkpoint, compresses redundant result nodes, and injects distilled iCPG context—freeing approximately 18,000 tokens for continued work. This addresses the core problem of context window exhaustion in long Claude Code sessions.

Example 4: srooter Gateway Configuration

# Claude Code (or Codex) → srooter
export ANTHROPIC_BASE_URL="https://www.srooter.ai/anthropic"   # or your local gateway
export ANTHROPIC_API_KEY="<your-srooter-key>"
claude        # now routed through srooter

srooter is an Anthropic/OpenAI-compatible LLM gateway with first-class support in the project. Pointing Claude Code at this endpoint enables transparent model routing, budget caps, and fallbacks without per-tool configuration. The /model-config command synchronizes your preferred model across Maggy, route-task hooks, and srooter.

Advanced Usage & Best Practices

Start with Bootstrap, add Maggy when routing matters. The 30-second Bootstrap install gives you immediate TDD enforcement and quality gates. Layer on Maggy only when you need multi-model routing, the dashboard, or parallel execution. This prevents premature complexity.

Use local mode to evaluate before committing API spend. Maggy runs fully without API keys. Test the dashboard, explore your repo structure in Cortex, and validate skill protocols locally. Add keys incrementally.

Monitor Telos IFS scores on project open. The Intent Fidelity Scale multiplies three planes: Conformance (test passage), Validation (architectural drift from Cortex), and Integrity (orphan symbols, empty contracts, stale reasons, scope sprawl). A zero in any plane zeroes the total score—this is intentional and forces attention to structural health, not just test greenness.

Leverage auto-isolation before manual branch management. Polyphony's polyphony-auto-isolate hook triggers on second sessions automatically. Don't fight it—let containers handle isolation until you explicitly need shared state.

Extend via skills, not forks. The skill linting system (PYTHONPATH=scripts python3 -m skill_lint --fail-on error skills/your-skill/) validates contributions before merge. This keeps the ecosystem consistent.

Comparison with Alternatives

Custom Claude Code configurations require significant ongoing maintenance and lack the memory, routing, and testing infrastructure. Generic AI coding agents (Cursor, GitHub Copilot Chat, etc.) optimize for individual developer speed but don't provide team-visible routing dashboards, ADR enforcement, or parallel agent isolation. Bootstrap occupies a specific niche: engineers who want AI assistance with engineering discipline, not despite it.

FAQ

Does this work without Claude Code? Yes. Bootstrap supports Codex, Kimi, and Gemini CLI. Maggy's routing extends to 13 models.

What's the actual cost to run? Local mode costs nothing. API-model features require your own keys; routing includes budget caps and auto-demotion to cheaper tiers.

How mature is the test suite? 1100+ tests pass: 900+ in maggy, 207 in cortex-mcp. The project enforces linting on all skill contributions.

Can I use this in a commercial project? MIT License permits commercial use. No attribution requirements beyond the license text.

What Python version does Maggy require? Python 3.11 or higher. Docker is optional but required for Polyphony.

How does this compare to standard MCP servers? Cortex MCP is included and specialized: 10 edge types, complexity analysis, FTS5 search, bidirectional traversal in SQLite. It's code intelligence, not just tool exposure.

Is there a hosted version? No. Maggy runs locally. The srooter gateway is a separate service for model routing if you prefer not to manage API keys per-tool.

Conclusion

alinaqi/claude-bootstrap solves concrete problems for developers already invested in Claude Code: runaway token costs, lost context, missing quality enforcement, and agent collision. The 30-second Bootstrap install delivers immediate discipline through TDD hooks and quality gates. Maggy adds sophisticated routing, memory, and parallel execution when your workflow demands it.

This tool fits solo engineers who want their AI assistant to remember and enforce standards; teams managing multiple models and cost centers; and platform engineers needing a reference implementation for intent-driven AI tooling. The 1100+ tests, active development through mid-2026, and MIT license provide credible foundations for production adoption.

Explore the repository, run the local setup without API keys, and evaluate whether the enforcement layer matches your engineering standards: https://github.com/alinaqi/claude-bootstrap

For organizations scaling AI engineering practices, [INTERNAL_LINK: AI-assisted developer tooling] may provide additional architectural patterns to consider alongside this implementation.