Skip to main content

​
Getting Started

Rafter is the way to shift security left — into your AI coding agent’s feedback loop. 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. Add an API key and your agent can also run the Code Security Engine (deep SAST/SCA) on demand.

​
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 sits inside the loop and gives them that judgment — before damage is done, not after. 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 Betterleaks (formerly 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:
Python 3.10+ required for pip installs. Verify your version:
On Ubuntu/Debian, Python and pip may not be installed by default:
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:
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:

​
Project-Level Setup

To generate instruction files that agents read at session start in a specific project:
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

​
Verify Installation

Run the built-in health check to confirm everything is set up correctly:
This checks your config, Betterleaks binary, and all 8 supported agent integrations (Claude Code, Codex, OpenClaw, Gemini CLI, Cursor, Windsurf, Continue.dev, Aider). Pass --json for CI-consumable output, --probe to confirm Claude Code’s PreToolUse hook actually fires (not just that the file is on disk). If any check fails, the output includes actionable fix instructions. You can also test individual components:
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:

​
Agent Auto-Detection

rafter agent init detects all supported agents and installs the appropriate skills: 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?