Maggy and Claude Bootstrap: a Claude Code config pack that grew a FastAPI control plane

Two products in one repository, and only one of them is a 30-second install

The README is explicit that this repo contains two layers. Claude Bootstrap is an installable config pack of skills, hooks, rules and templates that lands in ~/.claude/. Maggy is a local FastAPI server plus a web dashboard that adds multi-model routing, intent-driven protocols and plugin orchestration. The README's own comparison table gives install times of roughly 30 seconds for Bootstrap and roughly 5 minutes for the harness, with the harness requiring Python 3.11+ and API keys.

That framing matters because the two halves have different failure modes. Bootstrap is configuration. If a hook misfires you delete a file from a dotfile directory and your next Claude Code session behaves as it did before. Maggy is a running service with a database, a dashboard on localhost:8080, and on first launch a discovery pass over your local git repositories. The blast radius of a bad install is not the same.

The stated audience is three groups: solo engineers who want TDD enforcement and memory that survives context compaction without altering their workflow, teams routing work across Claude, DeepSeek, Kimi, Gemini and Codex from one dashboard, and platform engineers who want a reference implementation of intent tracking and plugin architecture. The third group is the one the README undersells. If you are building AI-assisted developer tooling, the interesting artifact here is the shape of the harness, not the skills.

What the enforcement layers actually do when a task ends

The mechanism the README describes most concretely is the stop hook. Bootstrap installs hooks such that tests must pass before Claude considers a task done. That is a different posture from a linter you run manually: the agent cannot declare completion while the gate is red. Alongside it sit quality gates stated as hard numbers, a maximum of 20 lines per function, 3 parameters, and 2 nesting levels, enforced per file.

Those numbers are opinionated and the README calls the kit opinionated in its own opening line. Whether a 3-parameter ceiling is reasonable depends entirely on what your codebase already looks like. A codebase with wide constructors or configuration objects passed around will fight this. The gates are described as enforced per file, which suggests they run as file-level checks rather than whole-program analysis, but the material does not spell out the failure behaviour when a file cannot satisfy them.

Two other layers are named. iCPG, Intent-Augmented Code Property Graph, is described as storing why code exists with six-dimension drift detection and preventing duplicate implementations. Mnemos is task-scoped memory with a four-dimension fatigue model that survives context compaction through typed checkpoints. The README's worked example shows a session fatigue value of 0.61 labelled PRE-SLEEP, an auto-checkpoint, three ResultNodes compressed, two ReasonNodes and one constraint injected, and roughly 18k tokens freed. Treat that as an illustration of the intended output format rather than a measured figure; nothing in the repository summary confirms it was produced by a benchmark.

The ADR layer is the most consequential of the group. Non-trivial changes require an Architectural Decision Record, and the README says a missing one is reverse-engineered from git history. The routing example shows an ADR gate finding docs/adr/0003-jwt-strategy.md and injecting it as context before a security review runs. That is a genuinely useful pattern: the review prompt carries the decision that constrained the code.

Routing by blast score, and why the tier table is only as good as your API keys

Every message is scored 1 to 10 for complexity and classified by task type, and the cheapest capable model wins. The README's example has a request to review auth middleware for timing attacks scoring 8 out of 10 for security and architecture, routing to Claude at Tier 11, and pulling in the JWT ADR before the review runs.

The tier list runs from T0 Qwen3 local for classification and triage, through T1 Gemini Flash-Lite and T2 DeepSeek Flash, up to Claude at the top. The README claims DeepSeek handles roughly 80 percent of tasks, that routing is budget-capped with auto-demotion, and that the top of the ladder includes Kimi, Gemini, Grok, Codex and Claude. It also states Maggy runs in local mode with no API keys required to start, discovering local git repos on first launch, with GITHUB_TOKEN and ANTHROPIC_API_KEY needed only for GitHub sync or API-model features.

Read those two claims together and the practical picture is narrower than the 13-tier table suggests. Without keys, the API tiers are unavailable; what remains is the local classifier and the dashboard over your repositories. The routing value proposition is real but conditional on how many providers you are willing to pay for and configure. A solo engineer with one Claude subscription gets classification and triage, not a cost-aware ladder.

The README does not explain how the blast score is calibrated, what happens when the classifier misjudges a task as trivial, or whether a low tier can escalate mid-task. Auto-demotion is mentioned for budget caps but the reverse direction is not described. That asymmetry is worth probing before you trust routing on anything security-sensitive.

Protocols, plugins and the parallel-agent story

Skill Protocols are YAML-defined workflows stored in maggy/skills/protocols/. The README's example maps the phrase push to git onto a sequence: lint, typecheck, tests, stage, commit, push, with an AI-generated commit message. Adding your own is described as dropping a .yaml file into the directory. This is the least exotic part of the project and probably the most immediately useful, because it turns a repeated conversational instruction into a fixed pipeline with visible per-step timings.

Polyphony handles Docker-isolated parallel agent execution, and the README says a second session auto-provisions a workspace. The problem statement lists file conflicts from running multiple agents on the same repo as a motivating pain, so isolation is the answer. The material does not describe what happens to uncommitted changes when a workspace is provisioned, or how results from parallel sessions reconcile.

Plugins are a drop-in system. The repository ships Build-in-Public, which the README says auto-posts to LinkedIn and X, plus Telos and GitHub, Asana and Monday providers. Telos is described as testing beyond TDD across three planes, Conformance, Validation and Integrity, where a zero in any plane collapses the total score. That collapse rule is the design decision worth noting: it is a veto, not a weighted average, so a passing conformance suite cannot compensate for an integrity failure.

Council PR Review is the newest-looking surface: multiple models review a GitHub PR from the dashboard, with deterministic chunking for large PRs, a static gate using tsc or ruff as ground truth, and an adversarial refute pass intended to kill false positives. It installs separately via pip install maggy-harness[review] and lists per-language skills for Python, TypeScript, Go, Rust, Java, C#, Ruby and PHP. The refute pass is the interesting claim. Multi-model review without a false-positive filter tends to produce noise, and using a compiler or linter as ground truth is a sound way to anchor the models.

Getting it running, and the one command that touches your filesystem

Bootstrap is two commands. git clone https://github.com/alinaqi/maggy.git, then cd maggy && ./install.sh. The README states your next Claude Code session picks it up automatically. It also notes the pack works with Codex, Kimi and Gemini CLI, not only Claude Code.

The full harness has a zero-config path: pipx install maggy-harness (or pip install maggy-harness), then maggy bootstrap to install skills, hooks, model wrappers into ~/bin and plugins, then maggy serve, which the README says auto-configures from your local repos and opens the dashboard at localhost:8080. From source the sequence is cd maggy && ./install.sh && maggy serve.

Two details deserve attention before you type any of this. First, maggy bootstrap writes model wrappers into ~/bin. If that directory is on your PATH ahead of other tooling, you are changing which binaries resolve. Second, maggy serve performs repository discovery on first launch. The README frames this as convenience, and it is, but it means the server enumerates your local git repositories without you naming them. If you work across client repositories on one machine, decide whether that is acceptable before the first run rather than after.

The README points to GETTING_STARTED.md for configuration details beyond the environment variables it names. It does not document a config file format, a port override, or an authentication story for the dashboard in the material available here. On a single-user laptop the absence of dashboard auth is unremarkable. On a shared or remote machine it is the first thing you would need to resolve, and the README does not tell you how.

Where this is the wrong tool

The clearest limitation is the one the README's own problem statement implies. This is a harness for people who have already committed to agentic coding in Claude Code and want it disciplined. If your team has not standardised on Claude Code, or if you use several editors and assistants interchangeably, installing hooks into ~/.claude/ buys you enforcement only in the sessions that read that directory. The pack's cross-tool support for Codex, Kimi and Gemini CLI is stated but the enforcement layers are described in Claude Code terms, so the guarantees are weaker elsewhere.

The second limitation is maintenance. The README advertises 67 skills and 15 MCP tools and a version number of 6.37.0. That is a large surface to keep aligned with upstream model APIs, editor behaviour and language toolchains. The repository summary shows no retrieved releases, so the changelog is the only versioning signal available. Every skill and hook is code you now own the upgrade path for, and nothing in the material describes a migration procedure between versions.

The third is the opinionated gates themselves. A 20-line function limit and a 3-parameter limit are house style encoded as enforcement. On a legacy codebase those gates will fail constantly and the practical response is to disable them, at which point you are running the memory and routing layers without the quality story. The README does not describe per-directory exemptions or a baseline mode.

Finally, the fatigue model. Mnemos writes checkpoints based on a four-dimension fatigue score, and the example shows a threshold labelled PRE-SLEEP. Automatic checkpointing is helpful when it fires correctly and noisy when it fires early. The material gives no guidance on tuning that threshold, which is the kind of parameter you will end up adjusting by feel.

How this differs from a plain CLAUDE.md plus a linter

The obvious alternative is not another AI coding harness. It is the combination most teams already have: a CLAUDE.md file of project instructions, a pre-commit hook running your existing linter and test suite, and manual model selection. That stack is boring and it works. It also has no memory across sessions, no routing, and no ADR injection.

The difference in approach is where enforcement lives. A pre-commit hook enforces at the moment you commit. Maggy's stop hook enforces at the moment the agent believes it is done, which is earlier in the loop and catches problems before they reach a commit at all. That is a real distinction, not a marketing one: the agent gets the failure and can act on it. The cost is that a misconfigured stop hook can prevent a session from completing, and your recovery path is editing files under ~/.claude/.

The second difference is the context injection. A CLAUDE.md is static. The ADR gate described in the README selects a specific decision record based on the task and injects it, and iCPG is described as storing why code exists to prevent duplicate implementations. That is closer to a retrieval layer than a prompt file. Whether it earns its complexity depends on whether your repository has ADRs and intent documentation to retrieve. In a repo with neither, the gate has nothing to find.

The third difference is cost routing, and here the honest comparison is to simply picking a cheaper model yourself. Maggy's claim is that a local classifier can make that choice per message with roughly 80 percent of tasks landing on DeepSeek. If you are already deliberate about model choice, the classifier adds automation and removes a decision. If you are not, it may not be worth the tier configuration.

Licence, upgrades and what to check before you install

The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive and low-friction for internal tooling. It also means no warranty and no obligation on the maintainer to fix anything. If you build internal tooling on the plugin system or the Cortex MCP schema, you are relying on a single maintainer's release cadence. This is not legal advice; read the LICENSE file in the repository for the terms that actually bind you.

Upgrade cost is the practical question the material does not answer. The README pins a version badge at 6.37.0 and links a CHANGELOG.md, and the repository summary shows no retrieved releases, so there is no release-note trail here to inspect. What you can check before adopting is whether the changelog documents breaking changes to the hook and skill layout, because those are the files installed into your home directory. A skill rename is trivial. A change to how stop hooks are registered is not, since a broken hook can block task completion.

Three things are worth verifying on a scratch clone before you run ./install.sh on a machine you depend on. Read install.sh and confirm exactly which paths under ~/.claude/ and ~/bin it writes. Run maggy serve once and inspect the repository discovery output to see which local repos it picks up. And check whether the quality gates in their default configuration pass on one representative file from your codebase, since that tells you in a minute whether you will be tuning or disabling them. The README's own example output, the routing trace and the protocol timings, is the best available description of expected behaviour.

Editorial conclusion

Adopt Claude Bootstrap if you already use Claude Code and want stop-hook TDD enforcement and quality gates without changing how you work; the install is a git clone plus ./install.sh and nothing else is required. Skip the full harness if you cannot run a local Python 3.11+ service, if you object to a web dashboard that discovers your local git repositories on first launch, or if your team has no appetite for maintaining hooks that can block a session from finishing. Before committing to Maggy, verify three things yourself: that the 20-line-per-function and 3-parameter gates match your codebase's existing style, that the ADR gate does not stall work in repositories with no docs/adr/ directory, and that the routing tiers you actually have API keys for cover the task types you care about. The 13-tier table is only useful to the extent your keys exist.

Official sources

1. alinaqi/maggy on GitHub
2. Issues
3. License: MIT
4. Project website
5. README