Guardrails for Coding Agents

Paws before you push.

Most coding agents read a local file for project-specific guidance—but most teams leave it empty. Drop in these guardrails to catch dangerous patterns that cause outages, security vulnerabilities, and secret leaks.

Built by Catpilot.ai—born from a real incident where an agent wiped production environment variables with a partial YAML update. MIT licensed. Dogfooded daily. PRs welcome.

Quick Start

git submodule add https://github.com/catpilotai/catpilot-ai-guardrails.git .github/catpilot-ai-guardrails
./.github/catpilot-ai-guardrails/setup.sh
git add .gitmodules .github/
git commit -m "Add AI guardrails"

That's it. Your coding agent now follows the safety rules.

🧩 Framework Detection (Automatic)

The setup script auto-detects your framework and adds relevant security patterns:

Detected File	Framework
package.json with "next"	Next.js
manage.py or requirements.txt with django	Django (+Core Python)
Gemfile with rails	Rails
requirements.txt with fastapi	FastAPI (+Core Python)
pom.xml/build.gradle with spring	Spring Boot
package.json with "express"	Express
tsconfig.json (without Next.js)	TypeScript
*.py or requirements.txt	Python (Core/Scripts)
Dockerfile	Docker
openclaw.mjs, .openclaw/, or AGENTS.md with openclaw refs	OpenClaw
requirements.txt/pyproject.toml with langchain, crewai, autogpt, langgraph	Agentic AI

# Auto-detect (recommended)
./.github/catpilot-ai-guardrails/setup.sh

# Override detection
./.github/catpilot-ai-guardrails/setup.sh --framework django

# Skip framework patterns
./.github/catpilot-ai-guardrails/setup.sh --no-framework

# Verify installed version matches source
./.github/catpilot-ai-guardrails/setup.sh --verify

Each framework adds ~600-800 bytes of security patterns specific to that stack.

📁 For Organizations (Fork-based workflow)

For teams that want to customize rules or control updates:

Step 1: Fork This Repo

Fork catpilotai/catpilot-ai-guardrails to your organization (e.g., YOUR_ORG/catpilot-ai-guardrails).

Step 2: Add Submodule to Your Repos

git submodule add git@github.com:YOUR_ORG/catpilot-ai-guardrails.git .github/catpilot-ai-guardrails

Step 3: Run Setup & Commit

./.github/catpilot-ai-guardrails/setup.sh
git add .gitmodules .github/
git commit -m "Add AI guardrails"

Customizing Rules

Add company-specific rules by editing the "🎯 Project-Specific Rules" section at the bottom of copilot-instructions.md in your fork.

Staying Up to Date

cd your-fork-of-ai-guardrails
git fetch upstream    # git remote add upstream https://github.com/catpilotai/catpilot-ai-guardrails.git
git merge upstream/main
git push

Then in each repo:

git submodule update --remote .github/catpilot-ai-guardrails
./.github/catpilot-ai-guardrails/setup.sh --force
git add .github/
git commit -m "Update AI guardrails"

Tool Support

Tool	Instruction File	Auto-configured
VS Code + GitHub Copilot	.github/copilot-instructions.md	✅
Cursor	.cursorrules	✅ (symlink)
Windsurf	.windsurf/rules/	✅ (symlink)
JetBrains + AI Assistant	.github/copilot-instructions.md	✅
Claude Code	CLAUDE.md	✅ (symlink)
Cline	.clinerules	✅ (symlink)
Aider	.aider.conf.yml	✅ (config entry)
OpenClaw	AGENTS.md	✅ (symlink)
Codex CLI	Manual	⚠️ See below

Codex CLI usage

Codex CLI doesn't auto-read project files. Pass guardrails via the --instructions flag:

# One-off command
codex --instructions "$(cat .github/copilot-instructions.md)" "fix the auth bug"

# Or create a shell alias in ~/.zshrc or ~/.bashrc
alias codex-safe='codex --instructions "$(cat .github/copilot-instructions.md)"'

# Then use normally
codex-safe "fix the auth bug"

What It Catches

• ☁️ Cloud CLI safety (Azure, AWS, GCP) — query before modify, confirm before execute
• 🔑 Secret detection — 40+ patterns (Stripe, AWS, GitHub tokens, etc.)
• 🗄️ Database safety — transactions, previews, no DELETE without WHERE
• 🏗️ Terraform/IaC — plan before apply, no -auto-approve
• ☸️ Kubernetes/Helm — dry-run and diff before applying
• 📦 Git safety — no force-push to protected branches
• 🛡️ Secure coding — OWASP Top 10, input validation, output encoding
• � AI agent safety — prompt injection defense, credential isolation, gateway binding
• 📦 Supply chain — skill/plugin vetting, typosquatting detection, red flag patterns
• 🔐 File permissions — credential directories, SSH keys, agent config
• 🚨 Incident response — secret rotation, git history purging, blast radius assessment
• 🔄 CI/CD safety — pin actions to SHA, minimal permissions, no secrets in logs
• 🧩 Framework patterns — Next.js, Django, Rails, FastAPI, Spring Boot, Express, TypeScript, Python, Docker, OpenClaw, Agentic AI

Example: Cloud CLI protection

Without guardrails:

# AI runs this — looks fine, right?
az containerapp update --yaml partial-config.yaml
# 💥 Result: CPU reset to 0.5, memory to 1GB, all env vars deleted

With guardrails:

# AI queries current state first
az containerapp show --name myapp --query "properties.template"
# Shows you the full command and asks for confirmation before executing
# Prepares rollback command in case something goes wrong

More examples

Command Injection prevention

Without guardrails:

# AI generates this — user controls filename
os.system(f"convert {filename} output.png")
# 💥 Attacker passes: "image.png; rm -rf /"

With guardrails:

# AI uses subprocess with list (no shell interpretation)
subprocess.run(["convert", filename, "output.png"], check=True)

SQL Injection prevention

Without guardrails:

# AI generates this
query = f"SELECT * FROM users WHERE id = {user_id}"
cursor.execute(query)

With guardrails:

# AI uses parameterized queries
query = "SELECT * FROM users WHERE id = %s"
cursor.execute(query, (user_id,))

Secret detection

Without guardrails:

# AI hardcodes credentials
API_KEY = "sk_live_abc123..."
stripe.api_key = API_KEY

With guardrails:

# AI uses environment variables
import os
stripe.api_key = os.environ["STRIPE_API_KEY"]

Files

File	Purpose
copilot-instructions.md	Condensed rules (~7KB) — auto-loaded by IDE
FULL_GUARDRAILS.md	Complete reference (~35KB) — detailed examples, loaded on-demand
frameworks/	Framework-specific patterns (auto-detected: Next.js, Django, Rails, FastAPI, Spring Boot, Express, TypeScript, Python, Docker, OpenClaw, Agentic AI)

How the two files work together

The condensed copilot-instructions.md is automatically injected into every AI request by your IDE. The complete FULL_GUARDRAILS.md is NOT auto-loaded (too large), but the AI can read it when encountering edge cases or when you ask explicitly.

This approach optimizes for minimal context window usage while keeping complete documentation available.

Cloning Repos With This Submodule

git clone --recurse-submodules <repo-url>

# Or if already cloned:
git submodule update --init --recursive

Changelog

See CHANGELOG.md for version history and what's new.

Contributing

See CONTRIBUTING.md for guidelines on adding patterns and submitting PRs.

License

MIT — See LICENSE for details.