Compass

🧭 compass

Guardrails and a hard budget cap for your AI coding agent.

budget gate · guardrails 100/100 · ~61% cheaper routing · signed releases · 100% local · no telemetry · you always merge

[](https://github.com/dshakes/compass/actions/workflows/ci.yml) [](https://github.com/dshakes/compass/releases) [](LICENSE) [](docs/05-plugin.md) [](docs/05-plugin.md) [](docs/05-plugin.md) [](#safety-honesty--status)

Real session, no edits: the cost climbs to $0.35, then the next action is HALTED at the $0.05 cap — before it spends more.

compass is a local-first config layer for Claude Code, Codex & Gemini that stops your agent from doing three things it shouldn't — burning your budget, running unsafe commands, and merging unverified code. Set COMPASS_MAX_USD=5 and the session hard-stops at the cap; catastrophic commands are blocked before they run, and the guardrail policy is scored 100/100 in CI — not asserted. You install it once, and you always merge.

# no curl|sh, fully reversible — then just open any repo in your agent
git clone https://github.com/dshakes/compass ~/compass && cd ~/compass && ./quickstart.sh
# or, inside Claude Code:   /plugin marketplace add dshakes/compass

▶ See it work  ·  Why it's different  ·  The self-fixing PR loop  ·  Install  ·  What's in the box  ·  📚 Docs

---

⭐ The part people screenshot: it fixes its own PRs.

Open a PR and compass reviews it, security-checks it, runs the tests, cross-audits it with a second model — then pushes its own fixes until it's green. You merge. ☝ That's a real PR — every event above is inspectable.

The idea in one line: the loop is the unit of work. A one-shot agent stops at its first wrong answer. compass loops — generate → test → critique → fix → repeat against a gate — so quality comes from iteration, not one lucky prompt. The same closed loop drives a single PR, or your whole fleet of repos overnight. → [how the loop works](docs/09-sdlc.md) · [the thesis](docs/loop-engineering.md)

---

Why it's different — measured, not vibes

Every AI-agent config claims "safe" and "cheap." compass is the one that hands you the number — and lets a skeptic reproduce it in 30 seconds. Everyone has the same models; the edge is configuration you can trust, not another feature list. Four claims, four commands:

🛡 Guardrails with a score. Catastrophic commands and secret writes are blocked before they run — and the policy is eval-gated, not asserted. (In human terms: it won't let the agent delete your machine or leak your keys, and it can prove how well.)

compass bench     # → guardrail 100% precision/recall (61-case corpus), router 96.9% — in CI
# then ask the agent to `rm -rf /` or write a .env → denied; `rm -rf ./build` → allowed

📉 Cost routing that's measured. Cheap work goes to cheap models — scored against an eval set, ~61% cheaper than all-Opus at ~98% quality on a fair mix. (In human terms: it stops paying Opus prices to fix a typo.)

compass route "redesign the auth model"   # → opus
compass route "fix a typo"                 # → haiku

💸 A budget ceiling that actually stops it. Usage trackers report spend; compass enforces it — set a dollar cap and the session is halted before the next tool call once it's reached, live. (In human terms: an agent can't quietly run up a $40 bill while you're away — it stops at your number.)

export COMPASS_MAX_USD=5     # this session hard-stops at $5 — the agent is blocked, not just warned
compass spend --max-usd 5    # the same ceiling on the ledger, for scheduled / fleet runs

🔏 Supply chain you can verify. Releases carry keyless SLSA provenance, so a tampered or look-alike download is rejected. (In human terms: you can prove the code you installed is the code I shipped.)

compass verify v0.17.2     # → ✓ provenance verified

🧪 Red-team resistance, measured. Prompt-injection (direct/indirect/paste), CLAUDE.md poisoning, local safety-override, malware & insecure-code — scored against a labeled corpus that gates in CI, with optional escalation to a managed guardrails service (webhook · Bedrock · Azure). (In human terms: a poisoned repo or web page can't quietly turn your agent against you.)

compass redteam   # → injection corpus 100% P/R, then scans THIS repo's CLAUDE.md/MCP/settings

No service, no telemetry, no --dangerously-skip-permissions; git pull to update. The work it can't safely own, it hands back — you keep the merge.

---

See it work

Smallest leap of faith first — the governance moment, then feel it, then see the proof, then see how it works.

0 · The budget ceiling, annotated — the same hard-stop as the hero clip, as a clean walkthrough ($1.80 ✓ → $4.10 ✓ → $5.00 HALTED). Usage trackers report spend; compass enforces it:

1 · The day-to-day feel — guardrails, the cost-aware status line, the loop, and the crew, in ~25 seconds:

2 · The headline, on a real PR — the loop recording at the top is a real session; open the actual PR and inspect every event yourself: Blocking review → agent:needs-fix → Builder fix commit on the branch → re-review clean → agent:reviewed-clean. No human touched it; the merge stayed theirs.

3 · How that loop works — review · security · tests · Codex cross-audit run in parallel; Blocking findings get auto-fixed and re-reviewed (round-capped) until green, then it stops at you:

Run it locally in 30s with ~/compass/sdlc/orchestrate.sh "<task>" (no tokens), or wire the GitHub loop for every PR. → how it works · reproduce it

And the everyday status line quietly keeps score, so you watch it earn its keep:

Opus 4.8 · myrepo · main* · 45k ctx · $1.23 · 🧭 🛡1 🧹2 💡1 📉~$1.65

session spend, then today's compass activity: 🛡 footguns blocked · 🧹 files formatted · 💡 policy nudges · 📉~$ estimated saved vs all-Opus. Each piece shows only when there's something to report; nothing leaves your machine.

---

Loops all the way up

Autonomy here isn't one big magic button — it's the same closed loop applied at four scales. Each runs until a gate says "done," then stops at a human. That's the whole trick: iteration under a gate beats a single confident guess.

| | Loop | What it drives | Where it stops | |---|---|---|---| | 🔁 | The task loop | generate → test → critique → fix → repeat — one change driven to green | when tests + review pass | | 🔎 | The review loop | review → auto-fix the Blocking findings → re-review, round-capped (×3) | hands off to a human if still red | | 🛰️ | The fleet loop | the whole pipeline, scheduled across every repo you own, overnight, test-gated | a PR per repo, approve from your phone | | 👥 | The workflow loops | parallel agents that fan out, fact-check each other, and converge | one synthesized answer |

Every loop ends the same way — you merge. That gate never moves.

---

The five moves of a loop — and the four costs it hides

A loop that runs while you sleep is five moves on a timer: discovery → handoff → verification → persistence → scheduling. compass ships a primitive for each — so you assemble a loop, not a one-off script you forget to re-run.

The danger was never the loop — it's the four costs it runs up silently, where no alarm sounds while it's running. Most autonomous-agent demos guard none of them. compass guards all four:

| Silent cost | What it is | The compass guard | |---|---|---| | Verification debt | unverified output piles up between "runs" and "right" | an independent evaluator that assumes broken and runs it — not self-review | | Comprehension rot | code you didn't write outpaces your understanding | compass digest — samples merged changes and makes you explain each | | Cognitive surrender | you stop having an opinion, take whatever it hands back | the permanent human merge gate — the loop executes, you decide | | Token blowout | a bug spins all night into a surprise bill | per-day + live session budget caps that halt the spend before it runs away |

The whole playbook, each move mapped to the primitive that builds it → docs/20-loops.md · the thesis

---

Prerequisites — what you need (and what you don't)

| You want… | You need | Tokens? | |---|---|---| | The config, guardrails, CLI, subagents (local) | Claude Code (or Codex/Gemini) + git | None | | The autonomous PR loop (GitHub Actions) | A repo with Actions + gh, model auth (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY), and SDLC_BOT_TOKEN (fine-grained PAT) so the loop can chain | Yes | | Keyless loop (self-hosted runner) | A runner labeled compass + SDLC_BOT_TOKEN | PAT only | | The fleet (every repo) | FLEET_TOKEN + FLEET_MAINTAINER | Yes |

One command wires the GitHub loop: ~/compass/sdlc/setup.sh --all (labels + workflows + CODEOWNERS + secrets + branch protection). Without SDLC_BOT_TOKEN the loop still runs — it just won't auto-re-fire after a fix. → [full SDLC setup](docs/09-sdlc.md)

---

Install

Pick the door that fits — all reversible, version-pinnable, no curl | sh. You need an AI assistant (Claude Code; Codex/Gemini optional) + git. No API keys to get the manual, guardrails, crew, and CLI.

🍺 Homebrew — managed & versioned

brew tap dshakes/compass https://github.com/dshakes/compass
brew install dshakes/compass/compass     # latest release · --HEAD to track main
compass quickstart                       # previews, asks, then wires it into ~/.claude

📦 Git clone — own & edit your config (recommended)

git clone https://github.com/dshakes/compass ~/compass && cd ~/compass
git checkout v0.17.2     # optional: pin to a release instead of main
./quickstart.sh          # previews every change, asks first, fully reversible

🧩 Claude Code plugin — no terminal (ideal for a team)

/plugin marketplace add dshakes/compass
/plugin install core@compass

🛠️ By hand: make dry-run (preview) → make install → make doctor. Symlink install means git pull/brew upgrade updates everything; make uninstall removes only what it added. → [Team rollout](docs/05-plugin.md)

One config, every agent — native installs

For every kind of user: a one-line marketplace/extension install (no terminal), or make install if you'd rather own the files. Same operating manual + MCP servers, the way each tool expects them:

| Agent | Native install (no terminal) | or own the files | |---|---|---| | Claude Code | /plugin marketplace add dshakes/compass → /plugin install core@compass | make install | | Codex | codex plugin marketplace add dshakes/compass → /plugin install | make install (~/.codex/AGENTS.md + config.toml) | | Gemini CLI | gemini extensions install https://github.com/dshakes/compass | ./install.sh --gemini (~/.gemini/GEMINI.md) | | Cursor · Copilot · OpenCode · Windsurf | read the repo's AGENTS.md (AGENTS.md standard) | clone + make install |

CLAUDE.md · AGENTS.md · GEMINI.md are one file (symlinks), and the Claude/Codex plugin manifests + Gemini extension are generated from one source and CI-checked (scripts/check-vendor.sh) — so a git pull updates every agent at once and a manifest can't drift.

> The marketplace/extension manifests match each vendor's documented schema and are structure-validated in CI. The live install is manually verified — gemini extensions install (gemini 0.26.0) and codex plugin marketplace add (codex 0.130.0) both succeed against this repo — but isn't run in our CI (those CLIs aren't in the runner).

✅ Verify → your first run

compass doctor      # validate the install — expect "0 error"
compass status      # is compass active here, and what's loaded?

Then just open Claude Code as usual — the manual, guardrails, subagents, commands, and status line are already loaded. Feel it in a minute: ask for a dangerous command (blocked), run /review on your diff, or compass route "" to see the tier it picks. No tokens, no signup for any of it.

---

What's in the box

Everything below is on after one install or a single opt-in — the autonomous loops above sit on top of this. The README sells; the docs explain — each row links to the detail.

| | Capability | One line | Deep dive | |---|---|---|---| | 🔁 | Autonomous SDLC | the review → security → tests → Codex audit → auto-fix → re-review loop; you merge | [09-sdlc](docs/09-sdlc.md) | | 🔄 | Loop engineering | the five moves wired up: morning-triage discovery · an acting/skeptic evaluator · compass digest (comprehension guard) · per-day budget cap | [20-loops](docs/20-loops.md) | | 🛰️ | The fleet | the loop, scheduled across all your repos through a test gate; approve from your phone | [14-fleet](docs/14-fleet.md) | | 👥 | The crew + workflows | 10 cost-tiered subagents · 12 slash-commands · 3 dynamic workflows that fact-check each other | [12](docs/12-every-agent.md) · [13](docs/13-workflows.md) | | 🛡 | Guardrails & scanning | 4 hooks block disasters, catch secrets (write-hook + compass scan), auto-format, keep a JSONL audit log | [16-hardening](docs/16-hardening-and-frontier.md) | | 🧪 | Red-team hardening | eval-gated defense vs prompt-injection (direct/indirect/paste), CLAUDE.md poisoning, local safety-override, malware & insecure code; optional webhook/Bedrock/Azure backend | [17-red-team](docs/17-red-team.md) | | 🧭 | Cost-tier router | a standalone, reusable module — keyword heuristic → optional classifier → Haiku judge cascade; eval-gated | [router/](router/) | | 🧰 | The compass CLI | onboard · impact · drift · scan · redteam · sandbox · verify · audit-log · spend · dashboard | [11-using](docs/11-using-compass.md) | | 🔌 | MCP + LSP | curated, version-pinned MCP servers (context7 · fetch · git) + opt-in language-server intelligence | [04](docs/04-mcp.md) · [06](docs/06-lsp.md) | | 🪪 | Every agent, one source | Claude Code · Codex · Gemini — plus Cursor/Windsurf/Copilot via the AGENTS.md standard | [12-every-agent](docs/12-every-agent.md) | | 💸 | Live budget ceiling | a hard spend cap that halts the session before the next tool call (COMPASS_MAX_USD) — plus a per-day cap (COMPASS_MAX_USD_DAY) for unattended loops — enforced, not just reported | [02-cost](docs/02-cost-and-models.md) | | 💰 | Cost discipline | routing scored & CI-gated, per-step budget caps, compass spend/impact to see the $ | [02-cost](docs/02-cost-and-models.md) |

---

Safety, honesty & status

Built to be trusted before it's run — and honest about its limits.

• You own the irreversible. Agents prepare; humans push, merge, deploy. Required checks + a code-owner approval enforce it — there's no "merge to prod" button.
• Readable & reversible. No curl | sh. The installer backs up what it replaces, is idempotent, and make uninstall removes only what it added. Pin a tag, not main.
• Guardrails reduce footguns; they are not a security boundary. Keep least-privilege credentials and review your diffs. (For untrusted code, compass sandbox is a real boundary.)
• Red-team hardening is defense-in-depth, not immunity. It warns on prompt-injection (direct/indirect/paste), CLAUDE.md poisoning, and local safety-override, and refuses to grant project-level safety exceptions — but the cardinal rule (external content is data, not instructions) and the human gate are what actually hold. compass redteam measures it; see [docs/17-red-team.md](docs/17-red-team.md).
• **Wh

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dshakes
• Source: dshakes/compass
• License: MIT
• Homepage: https://github.com/dshakes/compass#readme

Install and usage instructions live in the source repository linked above.