{
  "markdown": "# Claude Bootstrap + Maggy\n\n> **Turn Claude Code into a self-reviewing, test-enforced engineering system that remembers context across sessions — then route work across 13 models from a single dashboard.**\n\nClaude Bootstrap is an installable config pack (skills, hooks, rules, templates) for Claude Code. Maggy is the optional local server that adds multi-model routing, a web dashboard, intent-driven protocols, and plugin orchestration. Both live in this repo. Start with Bootstrap; add Maggy when you need the harness.\n\n[![Tests](https://img.shields.io/badge/tests-1100%2B%20passing-brightgreen)](maggy/tests/)\n[![Version](https://img.shields.io/badge/version-6.37.0-blue)](CHANGELOG.md)\n[![Stars](https://img.shields.io/github/stars/alinaqi/maggy)](https://github.com/alinaqi/maggy/stargazers)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n**1100+ tests. 67 skills. 15 MCP tools. Used daily across production codebases.**\n\n---\n\n## Who This Is For\n\n- **Solo engineers** using Claude Code who want TDD enforcement, quality gates, and memory that survives context compaction — without changing their workflow\n- **Teams** routing work across Claude, DeepSeek, Kimi, Gemini, and Codex from a single dashboard with cost-aware model selection\n- **Platform engineers** building AI-assisted developer tooling who need a reference implementation with intent tracking, protocol execution, and plugin architecture\n\n---\n\n## Choose Your Path\n\n| | Claude Bootstrap | Maggy Harness |\n|---|---|---|\n| **What it is** | Skills, hooks, rules installed into `~/.claude/` | Local FastAPI server + web dashboard |\n| **Install time** | ~30 seconds | ~5 minutes (Python 3.11+, API keys) |\n| **Requires** | Claude Code (also works with Codex, Kimi, Gemini CLI) | Everything in Bootstrap + Python + optional Docker |\n| **You get** | TDD enforcement, 67 skills, quality gates, ADR reviews, iCPG, Mnemos memory | All of Bootstrap + 13-tier routing, skill protocols, Telos testing, Cortex MCP, plugins, dashboard |\n\n### Bootstrap — 30-second install\n\n```bash\ngit clone https://github.com/alinaqi/maggy.git\ncd maggy && ./install.sh\n```\n\nYour next Claude Code session picks it up automatically.\n\n### Full Harness — zero-config\n\n```bash\npipx install maggy-harness   # or: pip install maggy-harness\nmaggy bootstrap              # installs skills, hooks, ~/bin model wrappers, plugins\nmaggy serve                  # auto-configures from your local repos,\n                             # then opens the dashboard at localhost:8080\n```\n\n(or from source: `cd maggy && ./install.sh && maggy serve`)\n\nNo API keys required to start — Maggy runs in local mode and, on first launch,\ndiscovers your local git repos and opens the dashboard pointed at them. Add\n`GITHUB_TOKEN` / `ANTHROPIC_API_KEY` later only if you want GitHub sync or\nAPI-model features. See [GETTING_STARTED.md](GETTING_STARTED.md) for details.\n\n---\n\n## What It Looks Like in Practice\n\n**Routing a task:**\n```\nYou: \"review the auth middleware for timing attacks\"\n→ Blast score: 8/10 (security + architecture)\n→ Routed to: Claude (Tier 11)\n→ ADR gate: found docs/adr/0003-jwt-strategy.md → injected as context\n→ Review runs with full architectural context\n```\n\n**Skill Protocol execution:**\n```\nYou: \"push to git\"\n→ Intent matched: git-push protocol\n→ ✅ lint       (2.1s)\n→ ✅ typecheck   (4.3s)\n→ ✅ tests       (11.2s)\n→ ✅ stage\n→ ✅ commit      [AI-generated: \"fix: resolve token refresh race condition\"]\n→ ✅ push\n```\n\n**Fatigue-aware memory:**\n```\nSession fatigue: 0.61 (PRE-SLEEP)\n→ Mnemos: auto-checkpoint written\n→ Micro-consolidation: 3 ResultNodes compressed\n→ iCPG context injected: 2 ReasonNodes, 1 constraint\n→ Context freed: ~18k tokens\n```\n\n---\n\n## The Problem This Solves\n\nYou're using Claude Code. It's impressive — but:\n\n- It picks the most expensive model for everything, including trivial tasks\n- Context fills up, state is lost, you re-explain yourself every session\n- There's no enforcement: code quality, test coverage, and ADR compliance only happen if you remember to ask\n- Running multiple agents on the same repo causes file conflicts\n- You have no visibility into what Claude is actually doing inside your codebase\n\n---\n\n## What Bootstrap Gives You\n\n| Layer | What it does |\n|-------|-------------|\n| **67 skills** | Python, TypeScript, React, React Native, Flutter, Supabase, Firebase, Stripe, Playwright, security, ADRs, cross-agent delegation |\n| **TDD enforcement** | Stop hooks — tests must pass before Claude considers a task done |\n| **Quality gates** | Max 20 lines/function, 3 params, 2 nesting levels. Enforced per file |\n| **iCPG** | Intent-Augmented Code Property Graph. Stores *why* code exists. 6-dimension drift detection. Prevents duplicate implementations |\n| **Mnemos** | Task-scoped memory with 4-dimension fatigue model. Survives context compaction with typed checkpoints |\n| **ADR enforcement** | Non-trivial changes require an Architectural Decision Record. Missing one? Reverse-engineered from git history |\n| **Agent teams** | 6 agents: Lead, Quality, Security, Review, Merger, Feature |\n\n---\n\n## What Maggy Adds\n\n| System | What it does |\n|--------|-------------|\n| **13-Tier Routing** | Semantic blast score (1–10) routes to cheapest capable model. Local Qwen3 classifier → DeepSeek (~80% of tasks) → Kimi → Gemini → Grok → Codex → Claude. Budget-capped with auto-demotion. [Routing details](#model-routing) |\n| **Skill Protocols** | YAML-defined workflows in `maggy/skills/protocols/`. \"Push to git\" → lint → test → stage → commit → push. Drop a `.yaml` to add your own |\n| **Telos** | Testing beyond TDD. Three planes: Conformance × Validation × Integrity. A zero in any plane collapses the total score. [Details](#telos-testing-beyond-tdd) |\n| **Cortex MCP** | Code intelligence: 10 edge types, cyclomatic complexity, FTS5 search, bidirectional traversal. 15 tools, single SQLite DB. [Benchmarks](cortex-mcp/docs/cortex-vs-codebase-memory.md) |\n| **Polyphony** | Docker-isolated parallel agent execution. Second session auto-provisions a workspace. [Spec](maggy/docs/polyphony-spec.md) |\n| **Engram** | Cross-session memory. 7 amnesia types. Persists architectural knowledge across weeks |\n| **Council PR Review** | Multi-model council reviews a GitHub PR from the dashboard — deterministic mega-PR chunking, a static gate (tsc/ruff) as ground truth, and an adversarial refute pass that kills false positives. Extensible per-language skills (Python/TS/Go/Rust/Java/C#/Ruby/PHP + drop-in more). `pip install maggy-harness[review]` |\n| **Plugins** | Drop-in system. Ships with: Build-in-Public (auto-posts to LinkedIn/X), Telos, GitHub/Asana/Monday providers |\n\n---\n\n## Model Routing\n\nEvery message is scored 1–10 for complexity and classified by task type. The cheapest capable model wins.\n\n| Tier | Model | Role |\n|------|-------|------|\n| T0 | Qwen3 (local) | Classification, triage, free bulk ops |\n| T1 | Gemini Flash-Lite | Bulk extraction, CIG pipelines |\n| T2 | DeepSeek Flash | Docs, tests, scaffolding |\n| T3 | Gemini Flash | Multimodal, vision, audio |\n| T4 | DeepSeek Pro | Complex coding, multi-file refactors |\n| T5 | Gemini CLI | Multi-file agentic coding |\n| T6 | AGY | End-to-end implementation (git + code + test) |\n| T7 | Kimi | Long-context analysis, routing alt |\n| T8 | Gemini Pro Search | Deep research, Google grounding, 2M context |\n| T9 | Grok | Competitor intel, deep reasoning |\n| T10 | Codex | Bulk generation, security-sensitive tasks |\n| T11 | Claude Sonnet | Quality-critical code, complex debugging |\n| T12 | Claude Opus | Architecture, security review, ADR decisions |\n\nRouting is semantic (Qwen3 as local classifier), fatigue-aware, budget-capped, and cascading.\n\n### Gateway routing with srooter — [www.srooter.ai](https://www.srooter.ai)\n\nWe've added first-class support for **[srooter](https://www.srooter.ai)**, an Anthropic/OpenAI-compatible LLM gateway that routes your requests across models (Claude, MiniMax, DeepSeek, Kimi, Gemini, Grok, local Qwen) transparently — intent-based routing, budget caps, fallbacks, and a usage dashboard, without changing your tools.\n\n**Recommended with Maggy, Claude Code, or Codex.** Point any of them at the gateway and your traffic is routed for you — no per-tool config:\n\n```bash\n# Claude Code (or Codex) → srooter\nexport ANTHROPIC_BASE_URL=\"https://www.srooter.ai/anthropic\"   # or your local gateway\nexport ANTHROPIC_API_KEY=\"<your-srooter-key>\"\nclaude        # now routed through srooter\n```\n\nPick the model you \"follow\" once with `/model-config` — Maggy, the route-task hooks, and srooter all honor the same choice. Trivial asks stay on the cheap/local tier; real coding goes to your primary model (e.g. MiniMax-M2.5).\n\n---\n\n## Parallel Development (Polyphony)\n\nRun several agents at once — each in its own Docker/OrbStack container with a full git clone on its own branch, so concurrent work never collides on files or branches.\n\n- **Auto-isolation** — a second Claude Code session in the same project automatically provisions its own workspace (via the `polyphony-auto-isolate` hook). No setup.\n- **`/spawn-team`** — spawns a coordinated TDD agent team; container-isolated by default when Docker + the `polyphony` CLI are present, with a graceful fallback to native parallel agents.\n\n```bash\npolyphony init                 # one-time: create ~/.polyphony/ config\npolyphony spawn \"add auth\"     # create + route a task to an agent\npolyphony status               # running agents / task states\npolyphony cleanup              # remove completed workspaces\n```\n\nFrom Claude Code: `/polyphony-init`, `/polyphony-spawn`, `/polyphony-status`. Requires Docker or OrbStack. Full design: [Polyphony spec](maggy/docs/polyphony-spec.md).\n\n---\n\n## Telos: Testing Beyond TDD\n\nStandard TDD tells you if your code passes tests. Telos tells you if your code fulfills its *intent*.\n\n```\nIFS (Intent Fidelity Scale) = F1 × F2 × F3\n\nF1 — Conformance:  passed / total tests            (pytest / vitest)\nF2 — Validation:   drift severity                  (Cortex drift_events)\nF3 — Integrity:    IF-3 orphan symbols              (no reason edges)\n                   IF-4 empty contracts             (no pre/post/invariants)\n                   IF-6 stale reasons               (proposed >7d, never fulfilled)\n                   IF-7 scope sprawl                (reason scopes >10 files)\n```\n\nA zero in any plane collapses IFS to zero. 100% test pass rate with severe architectural drift = score of 0. This is intentional. See the [Telos RFC](https://github.com/alinaqi/alinaqi/blob/main/docs/Telos_RFC_v1.1.md).\n\n---\n\n## Repo Structure\n\n```\n.claude/\n  skills/       # 67 skills — Python, TS, React, security, mobile, databases\n  hooks/        # TDD enforcement, quality gates, Mnemos lifecycle\n  rules/        # Conditional rules by file glob\n  templates/    # settings.json, CLAUDE.md, ADR template, PR template\n\nmaggy/\n  maggy/\n    pipeline/   # Unified ChatPipeline orchestrator\n    skills/     # Skill injection + YAML protocol engine\n    api/        # REST API (chat, routing, plugins, pipeline logs)\n    static/     # Web dashboard (vanilla JS, no build step)\n    services/   # Routing, memory, execution, Mnemos\n\ncortex-mcp/     # Code intelligence MCP server\n  src/cortex/\n    structure/  # AST extraction, edge types, complexity\n    storage/    # SQLite graph store, FTS5 index\n\nplugins/        # Drop-in plugins (build-in-public, telos, providers)\n```\n\n---\n\n## Tests\n\n```bash\ncd maggy && python3 -m pytest tests/ -x -q        # 900+ tests\ncd cortex-mcp && python3 -m pytest tests/ -q       # 207 tests\n```\n\n---\n\n## What's New in v6.37\n\n- **Skill Protocols** — YAML intent-driven workflows. \"Push to git\" runs lint → test → commit → push automatically\n- **Unified Pipeline** — single ChatPipeline orchestrator with real-time streaming, fallback, per-request logging\n- **Telos** — intent-grounded testing with IFS scoring on every project open\n- **Cortex MCP** — modular edge extraction (Python AST, TypeScript, Git co-change). Elixir support\n- **13-Tier Routing** — AGY, Gemini CLI, and Grok added to the routing ladder\n\nSee [CHANGELOG.md](CHANGELOG.md) for full history.\n\n---\n\n## Docs\n\n| | |\n|---|---|\n| [Getting Started](GETTING_STARTED.md) | Installation, prerequisites, first session walkthrough |\n| [Architecture v5](maggy/docs/architecture-v5.md) | System design, routing, dashboard |\n| [CLI Reference](maggy/docs/maggy-reference.md) | REPL commands, slash commands, routing |\n| [Telos RFC](https://github.com/alinaqi/alinaqi/blob/main/docs/Telos_RFC_v1.1.md) | Intent-grounded testing spec |\n| [Cortex docs](cortex-mcp/docs/) | Code intelligence, edge types, MCP tools |\n| [Cortex benchmarks](cortex-mcp/docs/cortex-vs-codebase-memory.md) | Performance vs codebase-memory-mcp |\n| [Changelog](CHANGELOG.md) | Version history (current: v6.37.0) |\n\n---\n\n## Contributing\n\nSkill PRs welcome. All skills run through the linter before merge:\n\n```bash\nPYTHONPATH=scripts python3 -m skill_lint --fail-on error skills/your-skill/\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the quality gate checklist.\n\n---\n\n## License\n\nMIT — See [LICENSE](LICENSE)\n\n---\n\n*Need help scaling AI engineering in your org? [LeanAI Ventures — Claude Code & MCP specialists](https://leanai.ventures/aiops/claude)*\n",
  "bytes": 13270,
  "sha": "5c2dc6d55972b191daa55d92dbbd4ecb27972d82b1d3907cd0465aba09c1d235",
  "repo_slug": "alinaqi/maggy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_alinaqi_maggy_ui_mobile_1533827f/readme"
}