Compass – guardrails and a hard budget cap for AI coding agents

Notifications You must be signed in to change notification settings

Fork 0

Star 9

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

186 Commits

186 Commits

.agents/plugins

.agents/plugins

.claude-plugin

.claude-plugin

.github

.github

Formula

Formula

assets

assets

bin

bin

claude

claude

codex

codex

demo

demo

docs

docs

mcp

mcp

plugins

plugins

router

router

scripts

scripts

sdlc

sdlc

templates

templates

.gitignore

.gitignore

.gitleaks.toml

.gitleaks.toml

CHANGELOG.md

CHANGELOG.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

GEMINI.md

GEMINI.md

LICENSE

LICENSE

Makefile

Makefile

PRIVACY.md

PRIVACY.md

README.md

README.md

SECURITY.md

SECURITY.md

gemini-extension.json

gemini-extension.json

install.sh

install.sh

quickstart.sh

quickstart.sh

Repository files navigation

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

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 pull request 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 just merge.

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 runs a single PR, or your whole fleet of repos overnight. (Try it locally in 30s, no tokens — watch it ↓.)

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 — a Blocking bug and red tests, and it pushes its own fix until the PR is green (then waits for you):

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 "" (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.

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

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

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

🛰️ The fleet the loop, scheduled across all your repos through a test gate; approve from your phone 14-fleet

👥 The crew + workflows 10 cost-tiered subagents · 12 slash-commands · 3 dynamic workflows that fact-check each other 12 · 13

🛡 Guardrails & scanning 4 hooks block disasters, catch secrets (write-hook + compass scan), auto-format, keep a JSONL audit log 16-hardening

🧪 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

🧭 Cost-tier router a standalone, reusable module — keyword heuristic → optional classifier → Haiku judge cascade; eval-gated router/

🧰 The compass CLI onboard · impact · drift · scan · redteam · sandbox · verify · audit-log · spend · das

[truncated for AI cost control]