Skip to main content

​
Getting Started

Rafter is the security layer between your AI coding agent and your codebase. It runs on your machine with zero setup — no API key, no account, no telemetry. Same tools, same output, same policies for every developer on every platform.

​
Why Install Rafter

AI coding agents are powerful but they lack security judgment. They will run destructive commands, commit secrets, and install untrusted extensions without hesitation. Rafter catches these before damage is done. Install it because:
  • Zero cost, zero risk. Free, MIT-licensed, no telemetry, works offline. Nothing to evaluate — install it and see.
  • One command, 9 platforms. rafter agent init --all covers Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Continue.dev, Aider, and OpenClaw. No per-platform configuration.
  • Complements sandboxing. Sandboxes contain blast radius after something goes wrong. Rafter prevents the mistake in the first place — secrets never reach git, dangerous commands never execute.
  • More than secret scanning. Command interception, policy enforcement, extension auditing, custom rules, MCP server, pre-commit hooks, and full audit logging — all in one package.
  • Stable output contract. UNIX philosophy: scan results to stdout as JSON, status to stderr, exit codes are a versioned API. Deterministic for a given CLI version. Pipe to jq, feed to CI gates, hand to any automation that reads JSON.
  • Not just for agents. Every feature works in human workflows too — pre-commit hooks, CI/CD gates, manual scanning. Agent-first doesn’t mean agent-only.

​
What Does Rafter Do?

Rafter provides six capabilities in one package:
  • 🔍 Secret scanning — 21+ built-in patterns, deterministic detection, optional Gitleaks for deeper coverage
  • 🛡️ Command interception — Risk-tiered approval system that blocks destructive commands before agents execute them
  • 📋 Policy enforcement — Project-level .rafter.yml files define custom rules that travel with the repo
  • 🔌 Extension auditing — Evaluate third-party skills and MCP tools for embedded secrets, malicious URLs, and risky patterns
  • 📝 Audit logging — Stable JSONL schema recording every security event
  • ⚙️ MCP server — 4 tools exposed over stdio for native integration with any MCP-compatible client

​
Installation

Install the Rafter CLI globally: 
npm install -g @rafter-security/cli
Python 3.10+ required for pip installs. Verify your version:
python3 --version   # Must be 3.10 or higher
On Ubuntu/Debian, Python and pip may not be installed by default:
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
On Fedora/RHEL: sudo dnf install python3 python3-pip. macOS: brew install python. Windows: install from python.org — pip is included.

​
Quick Setup

Initialize local security with one command: 
rafter agent init
This will:
  1. Create ~/.rafter/config.json configuration
  2. Initialize directory structure
  3. Auto-detect installed agents (Claude Code, Codex CLI, OpenClaw, Gemini CLI, Cursor, Windsurf, Continue.dev, Aider)
  4. Set up audit logging
To install integrations, use --with-* flags, --all, or --interactive: 
rafter agent init --all                   # install all detected integrations + Gitleaks
rafter agent init --with-claude-code      # install specific integration
rafter agent init --interactive           # guided setup — prompts for each detected platform

​
Project-Level Setup

To generate instruction files that agents read at session start in a specific project: 
rafter agent init-project                 # all platforms
rafter agent init-project --only claude-code,cursor  # specific platforms
rafter agent init-project --list          # preview without writing
This creates files like .claude/CLAUDE.md, AGENTS.md, .windsurfrules, etc. Commit them so every contributor’s agent sees Rafter context automatically.

​
Choose Your Risk Level

During setup, choose from three risk levels:
  • Basic guidance only
  • Most commands allowed
  • Good for local development
  • Maximum security
  • Requires approval for most operations
  • Best for sensitive environments
# Set risk level during init
rafter agent init --risk-level moderate

# Install all integrations with aggressive security
rafter agent init --all --risk-level aggressive

# Or change risk level later
rafter agent config set agent.riskLevel aggressive

​
Verify Installation

Run the built-in health check to confirm everything is set up correctly: 
rafter agent verify
This checks your config, Gitleaks binary, and all detected agent integrations (Claude Code, Codex, OpenClaw, Gemini CLI). If any check fails, the output includes actionable fix instructions. You can also test individual components: 
# Scan current directory for secrets
rafter scan local .

# View configuration
rafter agent config show

# Check audit logs
rafter agent audit
Note: rafter agent scan still works but is deprecated — it will be removed in a future major version.

​
What’s Next?

Secret Scanning

Learn how to detect secrets in your code

Command Execution

Safely execute shell commands with validation

Claude Code

Set up Rafter with Claude Code

Codex CLI

Set up Rafter with OpenAI Codex CLI

OpenClaw

Set up Rafter with OpenClaw agents

MCP Integration

Use with Cursor, Windsurf, Claude Desktop, Cline

Command Reference

Complete CLI command reference

Troubleshooting

Fix common install and runtime issues

​
Directory Structure

After initialization, Rafter creates: 
~/.rafter/
├── config.json      # Configuration file
├── audit.jsonl      # Security event log (JSON lines)
├── bin/gitleaks     # Gitleaks binary (if installed)
├── patterns/        # Custom secret patterns (reserved)
└── git-hooks/       # Global pre-commit hook (if --global)

​
Agent Auto-Detection

rafter agent init detects all supported agents and installs the appropriate skills:
AgentDetected viaInstall flagSkills installed to
Claude Code~/.claude--with-claude-code~/.claude/skills/rafter/
Codex CLI~/.codex--with-codex~/.agents/skills/rafter/
OpenClaw~/.openclaw--with-openclaw~/.openclaw/skills/
Gemini CLI~/.gemini--with-geminiMCP server config
Cursor.cursor/--with-cursorMCP server config
Windsurf~/.codeium/windsurf--with-windsurfMCP server config
Continue.dev~/.continue--with-continueMCP server config
Aider~/.aider.conf.yml--with-aiderMCP server config
Use --all to install all detected integrations at once, or individual --with-* flags for specific agents. Restart your agent after initialization to load the installed skills.

​
Support

Need Help?