> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafter.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Integration

> Set up Rafter security for Claude Code

# Claude Code Integration

Rafter provides two skills for [Claude Code](https://claude.ai/code) that separate remote code analysis from local security operations.

## Why Two Skills?

<CardGroup cols={2}>
  <Card title="Remote Code Analysis (rafter)" icon="cloud">
    **Auto-invocable** - Claude can proactively suggest scans

    * API-based SAST/SCA scanning
    * Read-only operations
    * Safe for Claude to auto-invoke
    * `rafter run` / `rafter scan` / `rafter get` / `rafter usage`
  </Card>

  <Card title="Local Security Toolkit (rafter-agent-security)" icon="shield">
    **User-only** - Requires explicit invocation

    * Local secret scanning
    * Policy enforcement
    * Extension auditing
    * Side effects require permission
  </Card>
</CardGroup>

This architecture separates read-only remote analysis from local security operations that have side effects.

## Setup

### 1. Install Rafter CLI

Install globally:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @rafter-security/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @rafter-security/cli
  ```
</CodeGroup>

### 2. Initialize Local Security

Run initialization with Claude Code integration:

```bash theme={null}
rafter agent init --with-claude-code
```

Or install all detected integrations at once:

```bash theme={null}
rafter agent init --all
```

If Claude Code is detected (checks for `~/.claude/` directory), Rafter will:

* Install Remote Code Analysis skill to `~/.claude/skills/rafter/SKILL.md`
* Install Local Security skill to `~/.claude/skills/rafter-agent-security/SKILL.md`
* Install a first-class **`rafter` sub-agent** to `~/.claude/agents/rafter.md` (v0.7.9+, rf-q7j) — the calling agent can invoke it as `Agent(subagent_type="rafter")`. Sub-agents appear in the main agent's tool list (skills only surface in the activation prompt), making delegation the natural motion for "is this safe / secure / production worthy?" questions. Hard-restricted to `Bash`, `Read`, `Grep`.
* Enable agent integration in config

<Tip>Use `rafter agent init --with-claude-code --dry-run` (v0.8.0+) to see every file path that would be created or modified before running the install for real.</Tip>

### 3. Restart Claude Code

Restart your Claude Code session to load the skills:

```bash theme={null}
# Kill existing session
pkill -f claude

# Start new session
claude
```

## Remote Code Analysis: Automated Scanning

The remote analysis skill allows Claude to proactively suggest security scans.

### Commands

<ParamField path="rafter run" type="command">
  Trigger a comprehensive security scan on your repository

  **Auto-detects:** Current repo and branch from git

  **Example:**

  ```bash theme={null}
  rafter run
  rafter scan --repo myorg/myrepo --branch feature-branch
  ```

  <Tip>`rafter scan` is an alias for `rafter run`.</Tip>
</ParamField>

<ParamField path="rafter get" type="command">
  Retrieve results from a completed or in-progress scan

  **Example:**

  ```bash theme={null}
  rafter get scan_abc123xyz
  ```
</ParamField>

<ParamField path="rafter usage" type="command">
  View your API quota and usage statistics

  **Example:**

  ```bash theme={null}
  rafter usage
  ```
</ParamField>

### When Claude Uses It

Claude will automatically invoke backend scanning when you:

* Mention "security", "vulnerabilities", or "code analysis"
* Start working on a new feature
* Review a pull request
* Update dependencies
* Ask about security issues

### Example Interactions

<Accordion title="Proactive Scan Suggestion">
  **You:** "I just updated all the npm packages"

  **Claude:** "Let me run a security scan to check for any new vulnerabilities in the updated dependencies."

  *\[Invokes: rafter run]*

  **Claude:** "Scan complete! Found 2 medium-severity issues in newly updated packages. Here's what needs attention..."
</Accordion>

<Accordion title="Pre-PR Security Check">
  **You:** "Can you review my changes before I create a PR?"

  **Claude:** "I'll run a security scan on your feature branch first."

  *\[Invokes: rafter run --branch feature-auth]*

  **Claude:** "Security scan passed with no issues. Your changes look good from a security perspective. Ready to create the PR?"
</Accordion>

<Accordion title="Quota Check">
  **You:** "How many scans do I have left this month?"

  **Claude:** *\[Invokes: rafter usage]*

  **Claude:** "You've used 45 of 100 scans this month. 55 remaining. Your quota resets on March 1st."
</Accordion>

## Local Security Skill

The local security skill provides secret scanning, policy enforcement, and extension auditing. **You must explicitly invoke these commands.**

### Commands

<ParamField path="/rafter-scan" type="slash-command">
  Scan files for secrets before commits

  **Example:**

  ```
  /rafter-scan .
  /rafter-scan src/config.ts
  ```

  **Detects:** AWS keys, GitHub tokens, Stripe keys, database credentials, private keys (21+ patterns)
</ParamField>

<ParamField path="/rafter-bash" type="slash-command">
  Execute commands with security validation

  **Example:**

  ```
  /rafter-bash "git commit -m 'Add feature'"
  /rafter-bash "sudo systemctl restart nginx"
  ```

  **Features:**

  * Blocks destructive commands (rm -rf /, fork bombs)
  * Requires approval for dangerous operations
  * Scans staged files before git commits
  * Logs all command attempts
</ParamField>

<ParamField path="/rafter-audit-skill" type="slash-command">
  Comprehensive security audit of a Claude Code skill before installation

  **Example:**

  ```
  /rafter-audit-skill ~/.claude/skills/untrusted-skill/SKILL.md
  ```

  **Analyzes:** 12 security dimensions including network calls, command execution, file access, credential handling, input validation, and more
</ParamField>

<ParamField path="/rafter-audit" type="slash-command">
  View security event logs

  **Example:**

  ```
  /rafter-audit
  /rafter-audit --last 20
  ```

  **Events:** Command attempts, secret detections, policy overrides, config changes
</ParamField>

### Usage Examples

<Accordion title="Pre-Commit Secret Scan">
  **You:** `/rafter-scan .`

  **Output:**

  ```
  🔍 Scanning 47 files...

  ⚠️  Found 1 secret:

  File: src/config.ts:12
  Type: AWS Access Key
  Value: AKIA...REDACTED...XYZ
  Severity: HIGH

  ❌ Secrets detected! Do not commit.
  ```
</Accordion>

<Accordion title="Safe Command Execution">
  **You:** `/rafter-bash "git commit -m 'Add authentication'"`

  **Process:**

  1. Rafter evaluates command risk level
  2. Scans staged files for secrets (for git commands)
  3. If clean: executes commit
  4. If secrets found or command blocked: alerts user

  **Output:**

  ```
  ✓ No secrets detected in staged files
  ✓ Command approved: git commit
  [main abc123d] Add authentication
  ```
</Accordion>

<Accordion title="Skill Security Audit">
  **You:** `/rafter-audit-skill ~/.claude/skills/github-integration/SKILL.md`

  **Output:**

  ```
  # Skill Audit Report

  **Skill**: github-integration
  **Risk Rating**: MEDIUM

  ## Findings

  ### Network Security: ⚠️ Warning
  - 3 external URLs found
  - https://api.github.com (HTTPS ✓)
  - http://internal-api.local (HTTP ⚠️)

  ### Command Execution: ✓ Pass
  - No dangerous commands detected

  ## Recommendation: ✓ YES (with modifications)

  Change http://internal-api.local to HTTPS before installing.
  ```
</Accordion>

## Configuration

### Risk Levels

Choose based on your security requirements:

<AccordionGroup>
  <Accordion title="Minimal (Development)" icon="shield-check">
    Best for: Local development, prototyping

    ```bash theme={null}
    rafter agent config set agent.riskLevel minimal
    ```

    * Allows most commands
    * Basic secret detection
    * Minimal workflow interruption
  </Accordion>

  <Accordion title="Moderate (Recommended)" icon="shield">
    Best for: General use, team environments

    ```bash theme={null}
    rafter agent config set agent.riskLevel moderate
    ```

    * Blocks critical commands
    * Requires approval for high-risk operations
    * Secret scanning on all git operations
    * **Default setting**
  </Accordion>

  <Accordion title="Aggressive (Production)" icon="shield-halved">
    Best for: Sensitive environments, compliance requirements

    ```bash theme={null}
    rafter agent config set agent.riskLevel aggressive
    ```

    * Maximum security checks
    * Requires approval for most operations
    * Comprehensive audit logging
  </Accordion>
</AccordionGroup>

### View Current Config

```bash theme={null}
# View all settings
rafter agent config show

# Check specific setting
rafter agent config get agent.riskLevel
```

## Workflows

### Secure Development Cycle

<Steps>
  <Step title="Start Feature">
    **You:** "Add user authentication"

    **Claude:** Writes code, then suggests: "Should I run a security scan?"

    *\[Invokes: rafter run]*
  </Step>

  <Step title="Pre-Commit Check">
    **You:** `/rafter-scan .`

    Verify no secrets before committing
  </Step>

  <Step title="Safe Commit">
    **You:** `/rafter-bash "git commit -m 'Add auth'"`

    Rafter scans and executes if clean
  </Step>

  <Step title="Pre-PR Review">
    **You:** "Review my changes"

    **Claude:** *\[Invokes: rafter run --branch feature-auth]*

    "Security scan passed. Ready to create PR?"
  </Step>
</Steps>

### Installing Untrusted Skills

Before installing skills from unknown sources:

<Steps>
  <Step title="Download Skill">
    Save skill file to local directory
  </Step>

  <Step title="Audit Security">
    **You:** `/rafter-audit-skill /path/to/skill.md`

    Review comprehensive 12-dimension security analysis
  </Step>

  <Step title="Make Informed Decision">
    Based on audit findings:

    * ✓ Install if LOW/MEDIUM risk
    * ⚠️ Modify if issues found
    * ❌ Don't install if HIGH/CRITICAL
  </Step>
</Steps>

## Monitoring

### View Agent Activity

```bash theme={null}
# Recent command executions
rafter agent audit --event command_intercepted

# Secret detections
rafter agent audit --event secret_detected

# Last 50 events
rafter agent audit --last 50
```

### Audit Reports

Generate compliance reports:

```bash theme={null}
# Export as JSON
rafter agent audit --json > agent-audit.json

# Filter by date
rafter agent audit --since 2026-01-01
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Skills Not Loading">
    If Claude doesn't recognize Rafter skills:

    1. **Verify skill files exist:**
       ```bash theme={null}
       ls ~/.claude/skills/rafter/SKILL.md
       ls ~/.claude/skills/rafter-agent-security/SKILL.md
       ```

    2. **Reinstall skills:**
       ```bash theme={null}
       rafter agent init
       ```

    3. **Restart Claude Code session**
  </Accordion>

  <Accordion title="Backend Skill Not Auto-Invoked">
    If Claude isn't suggesting scans automatically:

    1. **Check skill is loaded:** Look for system reminders showing "rafter" skill

    2. **Verify RAFTER\_API\_KEY is set:**
       ```bash theme={null}
       echo $RAFTER_API_KEY
       ```

    3. **Try explicit request:** "Can you run a Rafter security scan?"
  </Accordion>

  <Accordion title="API Key Issues">
    If backend scans fail:

    1. **Set API key:**
       ```bash theme={null}
       export RAFTER_API_KEY="your-key-here"
       ```

    2. **Or use .env file:**
       ```bash theme={null}
       echo "RAFTER_API_KEY=your-key-here" >> .env
       ```

    3. **Get key from:** [rafter.so/dashboard](https://rafter.so/dashboard)
  </Accordion>

  <Accordion title="Commands Bypassing Validation">
    If `/rafter-bash` isn't validating:

    1. **Check config:**
       ```bash theme={null}
       rafter agent config get agent.environments.claudeCode.enabled
       # Should return: true
       ```

    2. **Enable if disabled:**
       ```bash theme={null}
       rafter agent config set agent.environments.claudeCode.enabled true
       ```
  </Accordion>
</AccordionGroup>

## Best Practices

<Card title="Recommended Workflow" icon="list-check">
  1. **Let Claude auto-scan**: Don't disable the backend skill - proactive scans catch issues early
  2. **Scan before commits**: Always run `/rafter-scan` before committing
  3. **Audit untrusted skills**: Use `/rafter-audit-skill` for skills from unknown sources
  4. **Review audit logs**: Check `/rafter-audit` after suspicious activity
  5. **Start with moderate**: Adjust risk level based on your needs
  6. **Keep CLI updated**: `npm update -g @rafter-security/cli`
</Card>

## Advanced Usage

### Pre-Commit Hooks

Automate secret scanning for all commits:

```bash theme={null}
# Install pre-commit hook
rafter agent install-hook

# Install globally (all repos)
rafter agent install-hook --global
```

This automatically runs `/rafter-scan --staged` before every commit.

### Custom Blocked Patterns

Add organization-specific command patterns:

Edit `~/.rafter/config.json`:

```json theme={null}
{
  "agent": {
    "commandPolicy": {
      "blockedPatterns": [
        "kubectl delete namespace production",
        "terraform destroy",
        "rm -rf /important-data"
      ]
    }
  }
}
```

### Skill Auditing Framework

The `/rafter-audit-skill` command analyzes 12 security dimensions:

1. **Trust & Attribution** - Source verification
2. **Network Security** - External API calls
3. **Command Execution** - Shell commands
4. **File System Access** - Read/write operations
5. **Credential Handling** - API keys, secrets
6. **Input Validation** - Injection risks
7. **Data Exfiltration** - Data leaving system
8. **Obfuscation** - Hidden behavior
9. **Scope Alignment** - Behavior vs purpose
10. **Error Handling** - Info leakage
11. **Dependencies** - Supply chain risks
12. **Environment Manipulation** - System modifications

Each dimension gets a risk rating: ✓ Pass / ⚠️ Warning / ❌ Critical

## Comparison: OpenClaw vs Claude Code

<AccordionGroup>
  <Accordion title="Skill Architecture">
    **OpenClaw:** Single skill with all features

    **Claude Code:** Two skills (remote analysis + local security)

    **Why different?** Claude Code's auto-invocation capability allows separating safe API calls from local operations
  </Accordion>

  <Accordion title="Invocation Model">
    **OpenClaw:** User or agent invokes all commands

    **Claude Code:**

    * Backend skill: Auto-invoked by Claude
    * Local security: User invokes via slash commands
  </Accordion>

  <Accordion title="Command Prefix">
    **OpenClaw:** `/rafter-scan`, `/rafter-bash`, etc.

    **Claude Code:**

    * Backend: `rafter run`, `rafter get`, `rafter usage` (auto)
    * Agent: `/rafter-scan`, `/rafter-bash`, etc. (manual)
  </Accordion>
</AccordionGroup>

## Support

<CardGroup cols={2}>
  <Card title="Documentation" icon="book" href="https://docs.rafter.so">
    Complete guides and API reference
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/raftersecurity/rafter-cli/issues">
    Report bugs and request features
  </Card>

  <Card title="Dashboard" icon="table-columns" href="https://rafter.so/dashboard">
    Manage API keys and view scan history
  </Card>

  <Card title="Claude Code Docs" icon="book-open" href="https://claude.ai/code">
    Learn more about Claude Code
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Command Reference" icon="terminal" href="/guides/agent-security/reference">
    Complete CLI command documentation
  </Card>

  <Card title="Secret Scanning" icon="key" href="/guides/agent-security/secret-scanning">
    Deep dive into secret detection
  </Card>

  <Card title="CI/CD Integration" icon="gears" href="/guides/ci-cd">
    Use Rafter in continuous integration
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Backend API documentation
  </Card>
</CardGroup>