Squidbrake

<!-- mcp-name: io.github.batrapulkit/squidbrake -->

Brakes for your AI agents. Every action an agent takes (running a command, editing a file, sending an email, issuing a refund, changing a database) goes through Squidbrake first. It is checked against your rules, held for a person when it's risky, recorded in a tamper-evident audit trail, and can be stopped instantly.

Free and open source (Apache 2.0). Runs on your laptop or your own server; your data never leaves it.

• Rules, not vibes: rules.yaml says what runs by itself, what's blocked, and what waits for a person. No LLM in the decision path.
• Human approval: risky actions wait in the dashboard, on your phone (one-tap links, push via ntfy) or in Slack. The approver sees what led to it, e.g. the email the agent just read.
• Reads what a command really does: ls && rm -rf ~/, bash -c "...", rmdir /s /q d:\ or curl ... | sh are split and read before they run. Wiping a disk or home folder is blocked; git push --force, terraform destroy, kubectl delete or cloud deletes wait for a person; commands that only look (ls, git status) run without asking.
• Catches prompt injection without a model: if an agent sends data to an address that only a web page, email or issue mentioned (not you, not your own systems), it's held and the approver is told where the address came from.
• Judges by history: blocks a retry of something a person rejected, catches look-alike domains (acrne-corp.com pretending to be acme.com), flags duplicate refunds, and lets you write sequence rules ("deleting a database right after its backups were turned off") that say which earlier step caused them.
• Works with real agents: squidbrake connect all connects Claude Code, Cursor, Codex, Gemini CLI, VS Code Copilot and Antigravity (their commands, reads and edits, via hooks) and the MCP servers they already use; any MCP app (Stripe, GitHub, Slack, databases, internal tools) can be wrapped too.
• For teams: a key per person and per agent, roles (only finance approves wires), an emergency stop (all agents, one agent, or one conversation, which also ends Claude Code's turn), reports, CSV export, and evidence anyone can verify offline (python verify.py).
• Fails closed: if Squidbrake is down, guarded tools don't run.

See SHOWCASE.md for a 5-minute demo with a sandbox company, and incidents/ for 8 real AI-agent incidents replayed against the shipped rules (Replit, the Railway volume deletion, GitHub MCP, Supabase MCP, Claude Code and Antigravity deletes...): 11 of 11 harmful actions stopped, checked in CI.

<table><tr> <td width="62%"><img src="https://raw.githubusercontent.com/batrapulkit/squidbrake/main/docs/blocked-scam.png" alt="A $24,800 wire blocked because it follows an email from a look-alike domain"><br> _{An agent read an "urgent CEO" email from <code>acrne-corp.com</code> and tried to wire $24,800. Blocked, with the story of what led to it.}</td> <td width="38%"><img src="https://raw.githubusercontent.com/batrapulkit/squidbrake/main/docs/phone-approval.png" alt="One-tap approval on a phone"><br> _{Approve or reject from your phone with one tap.}</td> </tr></table>

See it live, nothing to install

Click the button and the live demo starts in your browser (free with a GitHub account): a sandbox company's AI support agent works its inbox while you watch. A scam wire is blocked, refunds wait for a person, and a demo manager approves or rejects them. If the editor asks whether to allow tasks that run automatically, click Allow: that's the demo starting. On your own machine: pip install -r requirements.txt then python demo/live_demo.py.

Try it in 30 seconds

pipx install squidbrake           # or: pip install squidbrake
squidbrake connect all            # every AI agent on this computer now goes through it
squidbrake                        # start it: opens the dashboard

connect all finds the agents you have (Claude Code, Cursor, Codex, Gemini CLI, VS Code Copilot, Antigravity) and the MCP servers they already use, and routes them all through Squidbrake. It prints your dashboard key the first time, backs up every config it changes, and squidbrake connect all --remove undoes it. Restart the agents, then ask one to run rm -rf ~/ and watch it get blocked. squidbrake connect status shows which agents are covered, and catches the one step people miss (Codex runs a new hook only after you approve it in /hooks).

Your rules, keys and data live in ~/.squidbrake; edit ~/.squidbrake/rules.yaml and changes apply at once.

Only Claude Code? It's also a plugin, installed from inside Claude Code (see plugin/): /plugin marketplace add batrapulkit/squidbrake, then /plugin install squidbrake@squidbrake.

From a clone instead: git clone https://github.com/batrapulkit/squidbrake && cd squidbrake, then ./start.sh (Windows: start.bat) and ./connect.sh claude-code (Windows: connect.bat claude-code).

Or with Docker: docker run -d -p 8080:8080 -v squidbrake-data:/app/data --name squidbrake ghcr.io/batrapulkit/squidbrake (keys: docker logs squidbrake).

1. Start it

| Where | Command | |---|---| | Windows | double-click start.bat | | macOS / Linux | ./start.sh | | A Linux server, 24/7 | ./install.sh (or ./install.sh gateway.yourdomain.com for HTTPS) |

The first start installs everything, prints an admin key (for the dashboard) and an agent key (shown once, so save them), and opens http://localhost:8080/dashboard. No configuration needed; every setting in .env.example is optional.

Keys: python server.py add-key NAME [--approver], python server.py remove-key NAME, python server.py keys. Changes apply immediately, no restart needed. (Inside Docker, prefix with docker compose exec gateway.)

2. Connect real agents

With the gateway running, one command per agent (installed with pip, type squidbrake connect ... instead; from a clone, use the .venv Python that start.bat / start.sh created):

.venv/Scripts/python connect.py all                  # every agent at once (Windows; macOS/Linux: .venv/bin/python)
.venv/Scripts/python connect.py claude-code          # or one at a time
.venv/Scripts/python connect.py mcp --name antigravity   # also: claude-desktop, cursor

| Agent | What's checked | One at a time | |---|---|---| | Claude Code | every tool call (Bash, PowerShell, edits, reads, web, MCP) | connect claude-code | | Cursor | terminal commands and file reads, plus its MCP servers | connect agents --agent cursor, connect guard --agent cursor | | Codex | shell commands and edits. Approve the hook once in Codex with /hooks: until then Codex skips it | connect agents --agent codex | | Gemini CLI | shell commands, reads, writes and edits, plus its MCP servers | connect agents --agent gemini-cli | | VS Code Copilot | agent-mode commands, reads and edits, plus its MCP servers | connect agents --agent vscode | | Antigravity | terminal commands, reads and writes, plus its MCP servers | connect agents --agent antigravity | | Windsurf, Kiro, Claude Desktop | their MCP servers | connect guard --agent windsurf |

• Claude Code: a hook sends every tool call (Bash, PowerShell, Edit, Write, Read, WebFetch, MCP tools) through the gateway before it runs. Blocked calls are refused with the reason, and calls held for approval wait until you decide in the dashboard. It also adds the database tools below. Add --project DIR to limit it to one project; --remove undoes it. If the gateway is down, Claude Code's tool calls are blocked (fail closed) and it says why.
• Antigravity, Claude Desktop, Cursor, any MCP client: prints the config block to paste in. The agent gets list_tables, describe_table, query and execute tools on a SQLite database (data/shop.db, created with sample customers / products / orders; set DB_PATH to use your own). Reads run immediately, UPDATE/DELETE/INSERT/ALTER wait for your approval, and DROP/TRUNCATE are blocked.

Wrapping a GitHub or Stripe MCP server? Start with the commented example policies in examples/rules/ and adjust their tool-name patterns to the server's tool list.

Things to ask the agent, then watch the dashboard:

• "Show me the top 5 customers by revenue" (runs)
• "Give every customer on the team plan a 15% discount" (waits for you to approve)
• "Delete all failed orders" (approve or reject it; a rejection note is passed back to the agent)
• "Drop the orders table" (blocked)
• In Claude Code: "commit and push this" (the git push waits for approval)

3. Show it to someone

• Right now, from your PC: cloudflared tunnel --url http://localhost:8080 prints a public https://….trycloudflare.com link. Give viewers their own key: python server.py add-key guest. Afterwards, press Ctrl+C and run python server.py remove-key guest.
• Permanently: ./install.sh gateway.yourdomain.com on a small cloud server.

4. Other computers (a friend, a teammate, a server)

Make a clean copy (no keys, no history): python pack.py -> dist/squidbrake.zip.

• Their own gateway: unzip, double-click start.bat (Windows) or run ./start.sh. It makes its own keys.
• Their agents on YOUR gateway: in your dashboard's Team tab add them (a person, to watch/approve) and add their agent (type AI agent); send them that agent key. They unzip and run, for example: connect.bat wrap --sandbox --agent claude-code --url https://your-gateway --key gw_... (or connect.bat claude-code --url ... --key ... to route every Claude Code action through your gateway).
• A cloud server, 24/7: unzip there and run bash install.sh (HTTPS included, no domain needed).

Other ways to send calls through it

Any MCP server - put Squidbrake in front of it, in any MCP client. The agent sees the app's normal tools, and each call is checked first (with GATEWAY_URL and GATEWAY_API_KEY set in the client's MCP config):

squidbrake proxy --app linear --url https://mcp.linear.app/mcp          # a remote MCP server
squidbrake proxy --app stripe -- npx -y @stripe/mcp --tools=all          # one started by a command

squidbrake connect guard does this for the servers your agents already use.

Python - wrap your tools:

from client import Gateway, Denied
gw = Gateway("https://gateway.