Skip to content
Back to search

maggy

SkillWorks with Claude CodeGitHub

What started as an opinionated Claude Code setup kit is now an autonomous AI engineering command center

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alinaqi-maggy/badge.svg)](/listings/alinaqi-maggy)

HTML

<a href="/listings/alinaqi-maggy"><img src="/api/listings/alinaqi-maggy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 321 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Claude Bootstrap + Maggy
  2. > **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.**
  3. Claude 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.
  4. [![Tests](https://img.shields.io/badge/tests-1100%2B%20passing-brightgreen)](maggy/tests/)
  5. [![Version](https://img.shields.io/badge/version-6.66.0-blue)](CHANGELOG.md)
  6. [![Stars](https://img.shields.io/github/stars/alinaqi/maggy)](https://github.com/alinaqi/maggy/stargazers)
  7. [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  8. **1100+ tests. 73 skills. 15 MCP tools. Used daily across production codebases.**
  9. ---
  10. ## Who This Is For
  11. - **Solo engineers** using Claude Code who want TDD enforcement, quality gates, and memory that survives context compaction — without changing their workflow
  12. - **Teams** routing work across Claude, DeepSeek, Kimi, Gemini, and Codex from a single dashboard with cost-aware model selection
  13. - **Platform engineers** building AI-assisted developer tooling who need a reference implementation with intent tracking, protocol execution, and plugin architecture
  14. ---
  15. ## Choose Your Path
  16. | | Claude Bootstrap | Maggy Harness |
  17. |---|---|---|
  18. | **What it is** | Skills, hooks, rules installed into `~/.claude/` | Local FastAPI server + web dashboard |
  19. | **Install time** | ~30 seconds | ~5 minutes (Python 3.11+, API keys) |
  20. | **Requires** | Claude Code (also works with Codex, Kimi, Gemini CLI) | Everything in Bootstrap + Python + optional Docker |
  21. | **You get** | TDD enforcement, 73 skills, quality gates, ADR reviews, iCPG, Mnemos memory | All of Bootstrap + 13-tier routing, skill protocols, Telos testing, Cortex MCP, plugins, dashboard |
  22. ### Bootstrap — 30-second install
  23. ```bash
  24. git clone https://github.com/alinaqi/maggy.git
  25. cd maggy && ./install.sh
  26. ```
  27. Your next Claude Code session picks it up automatically.
  28. ### Full Harness — zero-config
  29. ```bash
  30. pipx install maggy-harness # or: pip install maggy-harness
  31. maggy bootstrap # installs skills, hooks, ~/bin model wrappers, plugins
  32. maggy serve # auto-configures from your local repos,
  33. # then opens the dashboard at localhost:8080
  34. ```
  35. (or from source: `cd maggy && ./install.sh && maggy serve`)
  36. No API keys required to start — Maggy runs in local mode and, on first launch,
  37. discovers your local git repos and opens the dashboard pointed at them. Add
  38. `GITHUB_TOKEN` / `ANTHROPIC_API_KEY` later only if you want GitHub sync or
  39. API-model features. See [GETTING_STARTED.md](GETTING_STARTED.md) for details.
  40. ---
  41. ## What It Looks Like in Practice
  42. **Routing a task:**
  43. ```
  44. You: "review the auth middleware for timing attacks"
  45. → Blast score: 8/10 (security + architecture)
  46. → Routed to: Claude (Tier 11)
  47. → ADR gate: found docs/adr/0003-jwt-strategy.md → injected as context
  48. → Review runs with full architectural context
  49. ```
  50. **Skill Protocol execution:**
  51. ```
  52. You: "push to git"
  53. → Intent matched: git-push protocol
  54. → ✅ lint (2.1s)
  55. → ✅ typecheck (4.3s)
  56. → ✅ tests (11.2s)
  57. → ✅ stage
  58. → ✅ commit [AI-generated: "fix: resolve token refresh race condition"]
  59. → ✅ push
  60. ```
  61. **Fatigue-aware memory:**
  62. ```
  63. Session fatigue: 0.61 (PRE-SLEEP)
  64. → Mnemos: auto-checkpoint written
  65. → Micro-consolidation: 3 ResultNodes compressed
  66. → iCPG context injected: 2 ReasonNodes, 1 constraint
  67. → Context freed: ~18k tokens
  68. ```
  69. ---
  70. ## The Problem This Solves
  71. You're using Claude Code. It's impressive — but:
  72. - It picks the most expensive model for everything, including trivial tasks
  73. - Context fills up, state is lost, you re-explain yourself every session
  74. - There's no enforcement: code quality, test coverage, and ADR compliance only happen if you remember to ask
  75. - Running multiple agents on the same repo causes file conflicts
  76. - You have no visibility into what Claude is actually doing inside your codebase
  77. ---
  78. ## What Bootstrap Gives You
  79. | Layer | What it does |
  80. |-------|-------------|
  81. | **73 skills** | Python, TypeScript, React, React Native, Flutter, Supabase, Firebase, Stripe, Playwright, visual validation, security & audit, ADRs, cross-agent delegation |
  82. | **TDD enforcement** | Stop hooks — tests must pass before Claude considers a task done |
  83. | **Visual validation** | Default for web projects — `demo-video` records a captioned Playwright walkthrough (proof mp4 that doubles as a passing E2E test); `visual-validation` screenshots catch regressions. A user-facing web flow isn't "done" without it |
  84. | **Quality gates** | Max 20 lines/function, 3 params, 2 nesting levels. Enforced per file |
  85. | **iCPG** | Intent-Augmented Code Property Graph. Stores *why* code exists. 6-dimension drift detection. Prevents duplicate implementations |
  86. | **Mnemos** | Task-scoped memory with 4-dimension fatigue model. Survives context compaction with typed checkpoints |
  87. | **ADR enforcement** | Non-trivial changes require an Architectural Decision Record. Missing one? Reverse-engineered from git history |
  88. | **Agent teams** | 6 agents: Lead, Quality, Security, Review, Merger, Feature |
  89. ---
  90. ## What Maggy Adds
  91. | System | What it does |
  92. |--------|-------------|
  93. | **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) |
  94. | **Skill Protocols** | YAML-defined workflows in `maggy/skills/protocols/`. "Push to git" → lint → test → stage → commit → push. Drop a `.yaml` to add your own |
  95. | **Telos** | Testing beyond TDD. Three planes: Conformance × Validation × Integrity. A zero in any plane collapses the total score. [Details](#telos-testing-beyond-tdd) |
  96. | **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) |
  97. | **Polyphony** | Docker-isolated parallel agent execution. Second session auto-provisions a workspace. [Spec](maggy/docs/polyphony-spec.md) |
  98. | **Engram** | Cross-session memory. 7 amnesia types. Persists architectural knowledge across weeks |
  99. | **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]` |
  100. | **Plugins** | Drop-in system. Ships with: Build-in-Public (auto-posts to LinkedIn/X), Telos, GitHub/Asana/Monday providers |
  101. ---
  102. ## Model Routing
  103. Every message is scored 1–10 for complexity and classified by task type. The cheapest capable model wins.
  104. | Tier | Model | Role |
  105. |------|-------|------|
  106. | T0 | Qwen3 (local) | Classification, triage, free bulk ops |
  107. | T1 | Gemini Flash-Lite | Bulk extraction, CIG pipelines |
  108. | T2 | DeepSeek Flash | Docs, tests, scaffolding |
  109. | T3 | Gemini Flash | Multimodal, vision, audio |
  110. | T4 | DeepSeek Pro | Complex coding, multi-file refactors |
  111. | T5 | Gemini CLI | Multi-file agentic coding |
  112. | T6 | AGY | End-to-end implementation (git + code + test) |
  113. | T7 | Kimi | Long-context analysis, routing alt |
  114. | T8 | Gemini Pro Search | Deep research, Google grounding, 2M context |
  115. | T9 | Grok | Competitor intel, deep reasoning |
  116. | T10 | Codex | Bulk generation, security-sensitive tasks |
  117. | T11 | Claude Sonnet | Quality-critical code, complex debugging |
  118. | T12 | Claude Opus | Architecture, security review, ADR decisions |
  119. Routing is semantic (Qwen3 as local classifier), fatigue-aware, budget-capped, and cascading.
  120. ### Gateway routing with srooter — [www.srooter.ai](https://www.srooter.ai)
  121. We'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.
  122. **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:
  123. ```bash
  124. # Claude Code (or Codex) → srooter
  125. export ANTHROPIC_BASE_URL="https://www.srooter.ai/anthropic" # or your local gateway
  126. export ANTHROPIC_API_KEY="<your-srooter-key>"
  127. claude # now routed through srooter
  128. ```
  129. Pick 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).
  130. ### Context shunt — cheap reads, small context
  131. Gateway routing picks the model for a *turn*. The **context shunt** trims what a
  132. single *tool call* pulls in when the turn is legitimately on your main model: a
  133. PreToolUse hook (`context-shunt-gate`) catches reads of large files — code *or*
  134. logs/generated output — and steers them to `bulk-read`, which hands the files to
  135. a cheap worker (default `deepseek --flash`) and returns a compact summary. The
  136. raw bytes never enter context. For code symbols it points at the graph
  137. (`get_code_snippet`) instead. Inspired by Spotify's "shunt" plugin.
  138. Fully configurable in `~/.claude/shunt.conf` (or env): `SHUNT=on|off`,
  139. `SHUNT_MIN_LINES` (default 350), `SHUNT_MODE=suggest|block|off` (default
  140. `suggest` — nudges, never blocks), `SHUNT_MODEL`. See the `context-shunt` skill.
  141. ```bash
  142. bulk-read "how does token refresh work?" src/auth/session.ts src/auth/refresh.ts
  143. ```
  144. ---
  145. ## Parallel Development (Polyphony)
  146. Run 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.
  147. - **Auto-isolation** — a second Claude Code session in the same project automatically provisions its own workspace (via the `polyphony-auto-isolate` hook). No setup.
  148. - **`/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.
  149. ```bash
  150. polyphony init # one-time: create ~/.polyphony/ config
  151. polyphony spawn "add auth" # create + route a task to an agent
  152. polyphony status # running agents / task states
  153. polyphony cleanup # remove completed workspaces
  154. ```
  155. From Claude Code: `/polyphony-init`, `/polyphony-spawn`, `/polyphony-status`. Requires Docker or OrbStack. Full design: [Polyphony spec](maggy/docs/polyphony-spec.md).
  156. ---
  157. ## Telos: Testing Beyond TDD
  158. Standard TDD tells you if your code passes tests. Telos tells you if your code fulfills its *intent*.
  159. ```
  160. IFS (Intent Fidelity Scale) = F1 × F2 × F3
  161. F1 — Conformance: passed / total tests (pytest / vitest)
  162. F2 — Validation: drift severity (Cortex drift_events)
  163. F3 — Integrity: IF-3 orphan symbols (no reason edges)
  164. IF-4 empty contracts (no pre/post/invariants)
  165. IF-6 stale reasons (proposed >7d, never fulfilled)
  166. IF-7 scope sprawl (reason scopes >10 files)
  167. ```
  168. A 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).
  169. ---
  170. ## Repo Structure
  171. ```
  172. .claude/
  173. skills/ # 73 skills — Python, TS, React, security, mobile, databases
  174. hooks/ # TDD enforcement, quality gates, Mnemos lifecycle
  175. rules/ # Conditional rules by file glob
  176. templates/ # settings.json, CLAUDE.md, ADR template, PR template
  177. maggy/
  178. maggy/
  179. pipeline/ # Unified ChatPipeline orchestrator
  180. skills/ # Skill injection + YAML protocol engine
  181. api/ # REST API (chat, routing, plugins, pipeline logs)
  182. static/ # Web dashboard (vanilla JS, no build step)
  183. services/ # Routing, memory, execution, Mnemos
  184. cortex-mcp/ # Code intelligence MCP server
  185. src/cortex/
  186. structure/ # AST extraction, edge types, complexity
  187. storage/ # SQLite graph store, FTS5 index
  188. plugins/ # Drop-in plugins (build-in-public, telos, providers)
  189. ```
  190. ---
  191. ## Tests
  192. ```bash
  193. cd maggy && python3 -m pytest tests/ -x -q # 900+ tests
  194. cd cortex-mcp && python3 -m pytest tests/ -q # 207 tests
  195. ```
  196. ---
  197. ## What's New in v6.65
  198. - **Security audit — a default part of the harness** — `skills/security-audit/` runs a structured, adversarial, multi-phase audit (recon → coverage-led hunting → **finder≠validator** validation → machine-readable `findings.json` → target-neutral report). It's copied into **every** project at init (like the preventive `security` skill), reuses `council-review` (adversarial validation), `cpg-analysis` (static taint), and `agent-teams`/`polyphony` (isolated parallel hunters), and ships a JSON schema + a zero-dependency integrity validator.
  199. ## What's New in v6.64
  200. - **Visual validation is a default for web projects** — the `demo-video` skill (captioned Playwright walkthrough → proof mp4 that doubles as a passing E2E test) now ships with the harness and is copied into every web project (React, Full Stack, PWA) at init. A user-facing web flow isn't "done" without it — it's part of the Definition of Done in `base`, alongside `visual-validation` (screenshot-regression) and `playwright-testing` (behavior).
  201. ## What's New in v6.63
  202. - **DataForSEO skill** — `skills/dataforseo/` for keyword/SERP research (search volume, competition, CPC) to ground naming/SEO decisions in real data. Env-only auth.
  203. ## What's New in v6.62
  204. - **Codex dual auth** — Codex now works via your **ChatGPT subscription** (`codex login`, for `codex exec` delegation) *or* a real **OpenAI API key** (to run Codex as a Claude Code model through srooter). `codex-status` shows what's detected; `set-codex-auth auto|subscription|api_key` pins it. (Subscription can't back a Claude Code model — OpenAI has no Anthropic endpoint — so that path is delegation-only.)
  205. - **Direct-provider launchers** — `/model-config deepseek --direct` (or `glm` / `kimi`) writes `~/bin/claude-deepseek` / `claude-glm` / `claude-kimi`, each pointing Claude Code straight at the provider's native Anthropic endpoint — **no srooter hop**. Run `claude-deepseek` instead of `claude` and that session runs directly on DeepSeek Pro. Plain `claude` is untouched, so you pick per terminal. (Codex isn't direct-capable — OpenAI has no Anthropic API — so it stays routed through srooter.)
  206. - **Switch Claude Code's backend from inside Claude Code** — `/model-config deepseek` (or `kimi`, `glm`, `codex`) moves your real coding work onto DeepSeek Pro, Kimi K3, GLM 5.3, or Codex, routed through srooter. Restart srooter, start a fresh session, and coding runs on the chosen model while trivial asks stay on the fast local classifier.
  207. - **Both coding routes follow the switch** — `apply` now rewrites `long_context` *and* `substantive` in `srooter.yaml`, so substantive traffic follows the chosen backend (not just long-context).
  208. See [CHANGELOG.md](CHANGELOG.md) for full history.
  209. ---
  210. ## Docs
  211. | | |
  212. |---|---|
  213. | [Getting Started](GETTING_STARTED.md) | Installation, prerequisites, first session walkthrough |
  214. | [Architecture v5](maggy/docs/architecture-v5.md) | System design, routing, dashboard |
  215. | [CLI Reference](maggy/docs/maggy-reference.md) | REPL commands, slash commands, routing |
  216. | [Telos RFC](https://github.com/alinaqi/alinaqi/blob/main/docs/Telos_RFC_v1.1.md) | Intent-grounded testing spec |
  217. | [Cortex docs](cortex-mcp/docs/) | Code intelligence, edge types, MCP tools |
  218. | [Cortex benchmarks](cortex-mcp/docs/cortex-vs-codebase-memory.md) | Performance vs codebase-memory-mcp |
  219. | [Changelog](CHANGELOG.md) | Version history (current: v6.66.0) |
  220. ---
  221. ## Contributing
  222. Skill PRs welcome. All skills run through the linter before merge:
  223. ```bash
  224. PYTHONPATH=scripts python3 -m skill_lint --fail-on error skills/your-skill/
  225. ```
  226. See [CONTRIBUTING.md](CONTRIBUTING.md) for the quality gate checklist.
  227. ---
  228. ## License
  229. MIT — See [LICENSE](LICENSE)
  230. ---
  231. *Need help scaling AI engineering in your org? [LeanAI Ventures — Claude Code & MCP specialists](https://leanai.ventures/aiops/claude)*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.