---

Table of Contents

1. Why this exists
2. Quick Start
3. What you get
4. Supported AI Tools
5. Commands
6. Presets
7. MCP Server — Runtime Guardrails
8. CI/CD & Git Hooks
9. Watch Mode
10. Audit Mode
11. AI Safety Score
12. Dashboard & Reports
13. Configuration Reference
14. JSON Output
15. Architecture
16. FAQ
17. Roadmap
18. Contributing
19. Star History
20. License

---

Why this exists

AI coding tools like Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Aider, Cline, and Zed are
genuinely useful. But they don't know what's sacred in your repo. Without guardrails, an agent might:

• 🔥 Overwrite your .env with test values
• 🔥 Delete database migration files that can't come back
• 🔥 Rewrite your auth middleware "to clean it up"
• 🔥 Run prisma migrate reset on a production database
• 🔥 Add 12 new dependencies to fix one bug
• 🔥 Refactor 30 files when you asked to change one string

repo-seatbelt solves this with a four-layer defense:

Layer	What it does	Where it runs
1. Static rules	Generates CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, CONVENTIONS.md, .clinerules, .rules so agents read your boundaries on session start.	npx repo-seatbelt rules
2. Runtime MCP guardrail	A live MCP server agents call at decision-time: check_file_access, check_command, list_protections.	npx repo-seatbelt mcp
3. Pre-commit hook	Blocks high-risk commits locally before they leave the developer's machine.	npx repo-seatbelt install-hooks
4. CI gate	GitHub Action posts a PR comment with the safety score and fails on high-risk diffs.	npx repo-seatbelt ci

---

Quick Start

# Zero install
npx repo-seatbelt init                          # interactive setup
npx repo-seatbelt init --preset nextjs-stripe   # or apply a preset

# Day-to-day
npx repo-seatbelt scan                          # AI Safety Score + risks
npx repo-seatbelt diff                          # review AI changes pre-commit
npx repo-seatbelt doctor                        # prioritized action plan

# Lock it down
npx repo-seatbelt install-hooks                 # block high-risk commits
npx repo-seatbelt ci                            # add a GitHub Action
npx repo-seatbelt mcp --print                   # configure runtime MCP

---

What you get

.repo-seatbelt.json     ← machine-readable config (the source of truth)
CLAUDE.md               ← rules for Claude Code
AGENTS.md               ← rules for any AGENTS.md-aware tool (Codex, Aider, Gemini)
CONVENTIONS.md          ← rules for Aider
.cursorrules            ← rules for Cursor
.windsurfrules          ← rules for Windsurf
.clinerules             ← rules for Cline
.rules                  ← rules for Zed AI assistant
.git/hooks/pre-commit   ← (optional) blocks high-risk commits
.github/workflows/      ← (optional) CI gate with PR comments
docs/repo-seatbelt-report.md       ← markdown safety report
docs/repo-seatbelt-dashboard.html  ← interactive HTML dashboard

Plus a runtime MCP server any agent can call mid-session.

---

Supported AI Tools

Tool	Rule file	Generator	Runtime MCP
Claude Code / Claude Desktop	CLAUDE.md	✅	✅
Cursor	.cursorrules	✅	—
Codex / ChatGPT	AGENTS.md	✅	—
Gemini CLI	AGENTS.md	✅	—
Windsurf	.windsurfrules	✅	—
Aider	CONVENTIONS.md	✅	—
Cline	.clinerules	✅	—
Zed AI	.rules	✅	—

Any MCP-capable host (Claude Desktop, Claude Code, Continue.dev, etc.) can talk to the
repo-seatbelt MCP server for live, decision-time enforcement.

---

Commands

init — bootstrap the project

repo-seatbelt init                              # interactive
repo-seatbelt init --yes                        # non-interactive defaults
repo-seatbelt init --preset nextjs-stripe       # apply a preset
repo-seatbelt init --lang tr                    # Turkish output

Writes .repo-seatbelt.json, CLAUDE.md, AGENTS.md (and .cursorrules if you select Cursor).

scan — AI Safety Score + risk list

repo-seatbelt scan
repo-seatbelt scan --json            # machine-readable
repo-seatbelt scan --verbose         # full details
repo-seatbelt scan --no-color        # plain output for logs

Detects framework, package manager, databases, auth & payment providers, env hygiene,
production config, and AI rule files. Outputs a 0–100 score and a categorized risk list.

doctor — prioritized action plan

repo-seatbelt doctor
repo-seatbelt doctor --json

Same data as scan, but rendered as a prioritized to-do list. Best for first-time setup.

diff — review AI changes before committing

repo-seatbelt diff                   # human-readable
repo-seatbelt diff --json            # used by the pre-commit hook

Inspects current git changes. Flags .env mods, auth/payment touches, migration changes,
new dependencies, large refactors, and missing test coverage. Returns an overallRisk of
info | low | medium | high.

rules — generate AI rule files

repo-seatbelt rules                                    # interactive picker
repo-seatbelt rules --all                              # all 7 tools
repo-seatbelt rules --tool claude,cursor,windsurf      # comma-separated
repo-seatbelt rules --tool aider                       # single
repo-seatbelt rules --json                             # all + JSON manifest

Existing files are backed up to *.bak before overwrite.

protect — manage protected paths

repo-seatbelt protect                          # list current protections
repo-seatbelt protect "config/secrets/**"      # add a glob
repo-seatbelt protect --json                   # JSON output

check-command — validate a shell command

repo-seatbelt check-command "rm -rf node_modules"
repo-seatbelt check-command "git push --force" --json

Returns safe | dangerous with reasons. Combines built-in patterns with your
configured blockedCommands.

install-hooks — pre-commit guardrail

repo-seatbelt install-hooks                   # install git pre-commit hook
repo-seatbelt install-hooks --force           # overwrite existing hook (.bak saved)
repo-seatbelt install-hooks --uninstall       # remove the hook

The installed hook runs repo-seatbelt diff --json and blocks the commit when
overallRisk === "high". Bypassable with git commit --no-verify if needed.

ci — GitHub Actions workflow

repo-seatbelt ci                              # writes .github/workflows/seatbelt.yml
repo-seatbelt ci --force                      # overwrite
repo-seatbelt ci --output ./custom.yml        # custom path

The generated workflow:

• runs scan on every push and PR
• runs diff on PRs and posts a sticky comment with the safety score and findings
• fails CI when the diff is overallRisk === "high"

watch — auto-update rules as the repo evolves

repo-seatbelt watch                           # default 500ms debounce
repo-seatbelt watch --debounce 1500

Detects new sensitive folders (auth/, payment/, stripe/, …) and .env* files
appearing in the repo, updates .repo-seatbelt.json, and regenerates every rule file
that already exists. Zero extra dependencies — uses Node's built-in fs.watch.

audit — git history forensics

repo-seatbelt audit                                 # last 500 commits
repo-seatbelt audit --since "1 month ago"
repo-seatbelt audit --limit 1000 --json

Scans git history for:

• .env files committed
• protected files touched
• traces of blockedCommands in commit subjects
• "large refactor" commits (≥25 files)

Excellent for adopting repo-seatbelt on an existing repo to see what AI (or humans) did
before you locked things down.

update — regenerate rule files with diff preview

repo-seatbelt update                          # show diffs, ask for confirmation
repo-seatbelt update --yes                    # apply without prompting
repo-seatbelt update --diff-only              # show diffs, don't write
repo-seatbelt update --json                   # machine output

Recomputes every rule file from .repo-seatbelt.json and prints +N -M summaries with
sample lines. Existing files are backed up to *.bak.

mcp — runtime MCP server

repo-seatbelt mcp                             # run the stdio MCP server
repo-seatbelt mcp --print                     # print client-config snippet
repo-seatbelt mcp --print --json              # JSON snippet

See MCP Server for full details.

badge · report · dashboard

repo-seatbelt badge                           # README badge from latest scan
repo-seatbelt badge --score 92 --json
repo-seatbelt report                          # docs/repo-seatbelt-report.md
repo-seatbelt dashboard                       # docs/repo-seatbelt-dashboard.html

---

Presets

Skip the busywork. Apply a preset that knows what's sensitive in your stack.

Preset	What it adds
nextjs-stripe	Protects prisma/schema.prisma, .env.local, .env.production. Approval-gates Stripe webhook handlers, app/api/auth/**, next.config.*. Blocks stripe trigger against prod.
django	Protects **/migrations/**, settings/production.py. Approval-gates auth/, payments/, manage.py. Blocks manage.py flush and reset_db.
rails	Protects db/migrate/**, db/schema.rb, config/credentials.yml.enc, config/master.key. Blocks rails db:drop/db:reset.
expo	Protects app.json, eas.json, google-services.json, GoogleService-Info.plist. Blocks eas build --profile production, expo publish.
monorepo	Adds workspace-aware protection for turbo.json, nx.json, pnpm-workspace.yaml, packages/*/.env*.
fastapi	Protects alembic/versions/**, .env. Blocks alembic downgrade base.

npx repo-seatbelt init --preset nextjs-stripe

Presets are additive — they merge into your config rather than replacing it.

---

MCP Server — Runtime Guardrails

Static rule files only help if the agent reads them. The MCP server is a live JSON-RPC
service that AI agents (Claude Desktop, Claude Code, Continue.dev, any MCP host) can call
at decision-time to ask:

"Is it safe for me to edit this file?"
"Is this shell command allowed in this repo?"

Available tools

Tool	Purpose
check_file_access(path, operation)	Returns allow | ask | block. Call before any edit.
check_command(command)	Returns safe | warn | block with reasons. Call before any shell run.
list_protections()	Lists protected files, approval-required globs, blocked commands, and active mode.
scan_repo()	Runs the full safety scan and returns the score + risks.

Wire it into Claude Desktop

npx repo-seatbelt mcp --print

Add the printed snippet to ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "repo-seatbelt": {
      "command": "npx",
      "args": ["-y", "repo-seatbelt-mcp"]
    }
  }
}

Wire it into Claude Code

claude mcp add repo-seatbelt -- npx -y repo-seatbelt-mcp

Smoke-test it manually

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_command","arguments":{"command":"rm -rf /"}}}' \
  | npx repo-seatbelt mcp

You'll get back something like:

{ "decision": "block", "reasons": ["Recursive force delete", "Matches blocked command: \"rm -rf\""] }

The MCP server is dependency-free — minimal JSON-RPC over stdio, no SDK weight.

---

CI/CD & Git Hooks

Pre-commit hook (local, before push)

npx repo-seatbelt install-hooks

Now every git commit runs repo-seatbelt diff --json. If overallRisk === "high",
the commit is blocked with a clear message. To bypass intentionally:

git commit --no-verify -m "intentional high-risk commit"

GitHub Action (remote, on every PR)

npx repo-seatbelt ci
git add .github/workflows/seatbelt.yml
git commit -m "chore: add repo-seatbelt CI"

The workflow:

1. Runs scan on every push/PR
2. Runs diff on PRs and posts a sticky comment with the score + top high-risk findings
3. Fails the check if the diff is high-risk

Example PR comment:

## 🛡️ repo-seatbelt report

**Score:** 71/100 — 4 risk(s) found

### High-risk findings
- .env file modified (`.env.production`)
- Auth files were modified (`src/auth/middleware.ts`)

**Diff risk:** high
- .env files were modified
- Auth files were modified

---

Watch Mode

npx repo-seatbelt watch

Keeps your rule files in sync as the repo grows. Runs forever, debounces filesystem
events, and auto-regenerates CLAUDE.md, AGENTS.md, .cursorrules, etc. when:

• a new auth/, payment/, stripe/, billing/ folder appears under repo root or src/, app/, lib/
• a new .env* file is created in the repo root

Output:

  [14:23:01] Updated config + 5 rule file(s)
     +approval: src/payment/**
     +protected: .env.staging

---

Audit Mode

npx repo-seatbelt audit --since "3 months ago"

Scans git history for risky patterns. Useful when:

• adopting repo-seatbelt on an existing repo and you want to see past damage
• doing a security review on a contractor's branch
• generating evidence for a postmortem

Sample output:

  🔴  env-committed (2)
     2024-09-12 a3f81de alice: .env.local
     2024-11-01 9c1d2bb bob:   .env.production

  🟠  protected-touched (5)
     2025-02-04 4d8e7a1 ai-bot: prisma/migrations/20240204_drop_users/migration.sql
     ...

  🟡  large-refactor (1)
     2025-03-18 8b22f9c claude: 47 files changed

---

AI Safety Score

repo-seatbelt rates your repo against a checklist that signals "AI-friendly":

Range	Verdict	Meaning
80 – 100	🟢 AI Safe	Solid guardrails. Most agents will behave responsibly.
60 – 79	🟡 Needs attention	A few risk areas — review and patch before a long AI session.
40 – 59	🟠 Risky	Significant gaps. Run doctor and follow the action plan.
0 – 39	🔴 Not AI Ready	Don't let agents loose without init first.

The score is computed from weighted checkpoints (env hygiene, AI rule files, dangerous
scripts, framework risk, monorepo structure, …). Run scan --verbose to see the
breakdown.

Add a badge

npx repo-seatbelt badge

Copy-paste the markdown into your README.

---

Dashboard & Reports

npx repo-seatbelt report     # docs/repo-seatbelt-report.md
npx repo-seatbelt dashboard  # docs/repo-seatbelt-dashboard.html

The HTML dashboard is fully static (no build step, no JS framework) and shows your score,
risk breakdown, project info, and configured protections at a glance. Drop it into your
internal docs or open it locally with any browser.

---

Configuration Reference

.repo-seatbelt.json:

{
  "version": "1",
  "mode": "strict",                   // "solo" | "team" | "strict"
  "language": "en",                   // "en" | "tr"
  "projectType": "nextjs",
  "selectedTools": ["claude", "cursor"],

  "protectedFiles": [                 // never read/edit/delete without approval
    ".env", ".env.*",
    "prisma/migrations/**",
    "config/credentials.yml.enc"
  ],

  "approvalRequired": [               // edits require explicit human approval
    "auth/**", "lib/auth/**",
    "payment/**", "stripe/**",
    "middleware.ts"
  ],

  "blockedCommands": [                // shell commands the AI must refuse
    "rm -rf",
    "DROP TABLE",
    "prisma migrate reset",
    "git push --force"
  ],

  "ignoredPaths": [],                 // glob patterns the scanner skips
  "riskThresholds": {                 // score → verdict mapping
    "low": 60, "medium": 40, "high": 0
  },
  "presets": ["nextjs-stripe"]
}

Edit by hand or via repo-seatbelt protect / repo-seatbelt init.

---

JSON Output

Every command supports --json for scripting and CI:

repo-seatbelt scan --json | jq '.score'
repo-seatbelt diff --json | jq '.overallRisk'
repo-seatbelt audit --json --since "1 week ago" | jq '.findings | length'
repo-seatbelt rules --json | jq '.written[] | .file'
repo-seatbelt badge --score 92 --json

This is what powers the pre-commit hook and the GitHub Action.

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                  .repo-seatbelt.json                         │
│           (single source of truth — your contract)           │
└──────────────────────────────────────────────────────────────┘
            │
            ├─────────────► Static generators (init / rules / update)
            │                  ├─ CLAUDE.md
            │                  ├─ AGENTS.md
            │                  ├─ .cursorrules / .windsurfrules
            │                  ├─ CONVENTIONS.md / .clinerules / .rules
            │
            ├─────────────► Scanners (scan / doctor / diff / audit)
            │                  ├─ env hygiene
            │                  ├─ auth / payment / db detection
            │                  ├─ production config detection
            │                  └─ AI-rules presence + git history
            │
            ├─────────────► Enforcement layer
            │                  ├─ pre-commit hook (install-hooks)
            │                  ├─ GitHub Action (ci)
            │                  └─ watch (auto-regen)
            │
            └─────────────► MCP server (mcp)
                               ├─ check_file_access
                               ├─ check_command
                               ├─ list_protections
                               └─ scan_repo

---

FAQ

Does this slow my agent down?

The static rule files are read once at session start — zero runtime cost. The MCP server
adds a few milliseconds per check_file_access call, which is negligible compared to a
single LLM token.

Can the AI bypass these rules?

The static rules are advisory — well-behaved agents respect them. For hard enforcement,
combine the MCP server (decision-time) with the pre-commit hook (machine-time). The
hook is bypassable with --no-verify, but that's a deliberate human action you can audit.

Why not just write CLAUDE.md by hand?

You can. But repo-seatbelt keeps 7 different rule files in sync from one config,
ships an MCP server, gates CI, and audits history. That's hours of work per project,
saved.

What about non-JS projects?

The CLI is Node-based, but the rules it generates are language-agnostic markdown. Every
preset (django, rails, fastapi, expo, …) is for non-Node stacks.

How do I uninstall everything?

npx repo-seatbelt install-hooks --uninstall
rm .repo-seatbelt.json CLAUDE.md AGENTS.md .cursorrules .windsurfrules \
   CONVENTIONS.md .clinerules .rules
rm -rf .github/workflows/seatbelt.yml

---

Roadmap

• Static rule generators (Claude, Cursor, AGENTS.md)
• Generators for Windsurf, Aider, Cline, Zed
• Pre-commit hook installer
• GitHub Action generator with PR comments
• Watch mode (auto-regen on filesystem changes)
• Git-history audit
• Update command with diff preview
• Project presets (Next.js + Stripe, Django, Rails, Expo, FastAPI, Monorepo)
• MCP runtime guardrail server
• JSON output for every command
• VS Code extension (in-editor warnings + dashboard)
• Telemetry opt-in (anonymous "guardrails caught X" stats)
• Custom rule plugins
• More languages (German, French, Spanish)
• GitLab CI / Bitbucket Pipelines templates

---

Contributing

Issues and PRs are welcome. Please open an issue before submitting large changes.

git clone https://github.com/berkcangumusisik/repo-seatbelt.git
cd repo-seatbelt
npm install
npm run build
node dist/cli.js scan

See CONTRIBUTING.md for the full guide.

---

Share

If repo-seatbelt saved your repo from a bad AI session:

Just ran npx repo-seatbelt scan before letting Claude Code loose on my codebase.
Found 3 high-risk areas I had no idea about. Then wired up the MCP server and the
pre-commit hook so my agent literally can't touch .env or run prisma migrate reset.
This should be mandatory before any AI coding session.

github.com/berkcangumusisik/repo-seatbelt

---

Star History

---

License

MIT — use it, fork it, build on it.