ai-setup

Make your AI coding agent ask before git push, rm -rf or reading your SSH keys, and stop burning tokens without noticing. One folder configures Claude Code, OpenCode and Codex the same way, on every machine.

Without ai-setup:  agent runs `git push --force origin main`  → done, no questions
With ai-setup:     agent runs `git push --force origin main`  → 🔴 "needs your explicit OK"

See it work

The guard (a small script that checks every shell command the agent wants to run) on real commands:

$ echo '{"tool":"bash","command":"git push origin main"}' | python3 core/guard/guard.py
{"decision": "ask", "reason": "🔴 high risk: 'git push origin main' needs your explicit OK (policy: git push *)"}
$ echo '{"tool":"bash","command":"git status"}' | python3 core/guard/guard.py
{"decision": "allow", "reason": ""}

How the guard decides

 agent runs a command
        │
        ▼
   guard.py (reads policy.json, composed into build/policy.json)
        ├─► allow ─► runs, no prompt          git status, ls, grep
        ├─► ask   ─► you approve, then runs   git push, git reset --hard, git clean
        └─► deny  ─► blocked                  .env.local, SSH and cloud credentials
        │
        ▼
   OS sandbox (Claude only): the wall if the guard misses something

The rules are plain JSON in core/policy.json (shortened here):

{
  "ask_commands":   ["git push *", "git reset --hard*", "git clean *"],
  "allow_commands": ["git status", "git diff *", "ls *"],
  "deny_files":     [".env.local", "*.env.local"],
  "deny_home_dirs": ["~/.ssh", "~/.aws"]
}

A layer can add rules, never weaken core/. More in Reference.

Install

macOS with Homebrew and python3, or Linux with python3.

git clone https://github.com/sebabottero/ai-setup.git ~/Dev/ai-setup   # clone into the final path: the links point to it
cd ~/Dev/ai-setup
./bootstrap.py --dry-run     # shows what it would install, changes nothing
./bootstrap.py               # tools, then ./install.sh (runs the tests, backs up whatever it replaces)

What you get

🛡 Asks before anything hard to undo	One policy.json and one guard decide allow / ask / deny for every shell command. Secrets are a hard deny. Claude also gets an OS sandbox from the same policy.
💸 Spends fewer tokens	coach picks model and effort before you start, and flags big PDFs/docs to convert first. A hook warns when the context passes 100k. usage_report.py audits your own sessions, locally.
🔀 Same rules in every tool	Write rules, skills and agents once. They install into Claude Code, OpenCode and Codex. Your private bits live in layers (extra folders that add rules on top), not in a fork.
🧱 Repos that keep their rules	repo-guardrails prepares any repo with a short AGENTS.md, a one-line CLAUDE.md, architecture tests that fail the build and a minimal CI. Only the file-scan test is verified; other languages are marked untested.
🔁 A full cycle, not just tools	From ticket to merge, each of 6 steps has a skill or a gate behind it (one writer per ticket, independent review, you decide). See The cycle.

The cycle

The guard is one piece. Around it, the whole loop of working with an AI agent, from ticket to merge:

 1 Decide ─► 2 Guardrails ─► 3 Build ─► 4 Independent ─► 5 Human ─► 6 Learn
                                          review          gate        │
   ▲                                                                  │
   └──────────────── a repeated mistake becomes a rule ◄──────────────┘

#	Step	Covered by
1	Decide	grillme interviews you and writes criteria.md: goal, out of scope, done criteria, and ## Slices when it should be several small PRs; ticket-flow Gate 1 shows a single-PR or split verdict
2	Guardrails	repo-guardrails: AGENTS.md templates (rules marked E: or with an expiry date), risk tiers, CI
3	Build	ticket-flow orchestrates, sub-builder writes, sub-tester writes one test per criterion
4	Independent review	sub-review checks the diff against criteria.md; the merge gate requires its report; ticket-flow re-reviews the committed PR against criteria.md and posts it as a PR comment only with your OK
5	Human gate	ticket-flow Gate 2 plus the guard's ask on commit, push and merge: you decide
6	Learn	meta-setup turns a repeated mistake into a rule; ai-audit is the periodic check

Details per step in the cheatsheet.

Measure it

Example output: the author's own month of use (python3 -I adapters/claude/usage_report.py 30; reads only your local transcripts, sends nothing):

Sessions: 149  |  over 150k: 35 (23%)  |  over 300k: 9  |  peak: 772k
Turns by model: claude-sonnet-5-5 60%, claude-opus-5-5 39%
Guard: 1233 allowed, 352 asked, 4 denied. Rules that fire most: outside-sandbox 123, git push * 80

/coach before a task (example): model and effort, plus your request rewritten as goal · done when · out of scope · start from. Every ~30 days tune-setup (Claude only) re-tunes it from your own /insights data, and edits only after you approve.

This is the beginning of the README. Read the rest at the original. Read the full README ↗