Repo Seatbelt

🔒 repo-seatbelt

A safety layer for AI coding agents. Before they touch your repo.

[](https://www.npmjs.com/package/repo-seatbelt) [](https://www.npmjs.com/package/repo-seatbelt) [](LICENSE) [](package.json) [](#mcp-server--runtime-guardrails) [](https://glama.ai/mcp/servers/berkcangumusisik/repo-seatbelt) [](README.tr.md)

AI coding agents are powerful. Maybe too powerful.

repo-seatbelt scans your project, detects risky areas, generates safety rules for 7 AI tools, exposes a runtime MCP guardrail server, ships a pre-commit hook + GitHub Action, and gives your repo an AI Safety Score out of 100 — in your language.

> Before AI touches your repo, buckle up.

[Quick Start](#quick-start) · [Commands](#commands) · [MCP Server](#mcp-server--runtime-guardrails) · [Presets](#presets) · [CI / Hooks](#cicd--git-hooks) · [Score System](#ai-safety-score) · [Türkçe](README.tr.md)

---

Table of Contents

1. [Why this exists](#why-this-exists)
2. [Quick Start](#quick-start)
3. [What you get](#what-you-get)
4. [Supported AI Tools](#supported-ai-tools)
5. [Commands](#commands)
6. [Presets](#presets)
7. [MCP Server — Runtime Guardrails](#mcp-server--runtime-guardrails)
8. [CI/CD & Git Hooks](#cicd--git-hooks)
9. [Watch Mode](#watch-mode)
10. [Audit Mode](#audit-mode)
11. [AI Safety Score](#ai-safety-score)
12. [Dashboard & Reports](#dashboard--reports)
13. [Configuration Reference](#configuration-reference)
14. [JSON Output](#json-output)
15. [Architecture](#architecture)
16. [FAQ](#faq)
17. [Roadmap](#roadmap)
18. [Contributing](#contributing)
19. [Star History](#star-history)
20. [License](#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](#mcp-server--runtime-guardrails) 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.

…

Source & license

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

• Author: berkcangumusisik
• Source: berkcangumusisik/repo-seatbelt
• License: MIT
• Homepage: https://www.npmjs.com/package/repo-seatbelt

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