How to Integrate SafeClaw with Claude Code Step by Step

SafeClaw is an action-level gating layer for AI agents, built by Authensor. This guide covers integrating SafeClaw with Claude Code so that every file write, shell execution, and network request is evaluated against a deny-by-default policy before execution.

Prerequisites

• Node.js 18 or later installed
• Claude Code CLI installed and authenticated
• A SafeClaw account at safeclaw.onrender.com (free tier available with 7-day renewable keys, no credit card required)
• A valid SafeClaw API key from the browser dashboard

Step-by-Step Instructions

Step 1: Install SafeClaw

npx @authensor/safeclaw

The setup wizard launches in your browser. Select your project directory and complete the guided configuration. SafeClaw has zero third-party dependencies and runs in TypeScript strict mode.

Step 2: Initialize SafeClaw in Your Project

cd /path/to/your/project
npx @authensor/safeclaw init

This creates a safeclaw.config.yaml file in your project root and a .safeclaw/ directory for local policy cache.

Step 3: Create a Claude Code Hook Script

Create a file at .claude/hooks/safeclaw-gate.ts:

import { SafeClaw } from "@authensor/safeclaw";

const safeclaw = new SafeClaw({
  apiKey: process.env.SAFECLAW_API_KEY,
  agentId: "claude-code",
  mode: "enforce", // use "simulate" for testing
});

export async function beforeAction(action: {
  type: string;
  target: string;
  content?: string;
}): Promise<{ allowed: boolean; reason?: string }> {
  const result = await safeclaw.evaluate({
    actionType: action.type, // file_write, file_read, shell_exec, network
    target: action.target,
    metadata: {
      agent: "claude-code",
      timestamp: new Date().toISOString(),
    },
  });

return {
    allowed: result.decision === "ALLOW",
    reason: result.reason,
  };
}

Step 4: Configure Claude Code to Use the Hook

Add the following to your Claude Code configuration at ~/.claude/config.json:

{
  "hooks": {
    "beforeAction": ".claude/hooks/safeclaw-gate.ts"
  },
  "env": {
    "SAFECLAW_API_KEY": "your-safeclaw-api-key"
  }
}

Step 5: Test in Simulation Mode

Set mode: "simulate" in your hook script. Run Claude Code normally. SafeClaw logs every action evaluation to the tamper-proof audit trail (SHA-256 hash chain) without blocking any actions. Review results in the browser dashboard at safeclaw.onrender.com.

Step 6: Switch to Enforce Mode

After verifying that policies match your expectations, set mode: "enforce" in the hook script. SafeClaw now blocks any action not explicitly permitted by your policy. Policy evaluation runs in sub-millisecond time.

Example Policy

# safeclaw.config.yaml
version: "1.0"
agent: claude-code
defaultAction: deny

rules:
  - id: allow-src-writes
    action: file_write
    target: "./src/**"
    decision: allow
    description: "Allow writing to source files"

- id: allow-test-writes
    action: file_write
    target: "./tests/**"
    decision: allow

- id: deny-env-access
    action: file_read
    target: ".env*"
    decision: deny
    description: "Block reading environment files"

- id: gate-shell
    action: shell_exec
    target: "*"
    decision: require_approval
    description: "All shell commands require human approval"

- id: allow-npm-install
    action: shell_exec
    target: "npm install*"
    decision: allow

- id: deny-network
    action: network
    target: "*"
    decision: deny
    description: "Block all outbound network requests"

Example Action Requests

1. ALLOW — Writing to a source file:

{
  "actionType": "file_write",
  "target": "./src/utils/helpers.ts",
  "agentId": "claude-code",
  "decision": "ALLOW",
  "rule": "allow-src-writes",
  "evaluationTime": "0.4ms"
}

2. DENY — Reading an environment file:

{
  "actionType": "file_read",
  "target": ".env.production",
  "agentId": "claude-code",
  "decision": "DENY",
  "rule": "deny-env-access",
  "evaluationTime": "0.3ms"
}

3. REQUIRE_APPROVAL — Running an arbitrary shell command:

{
  "actionType": "shell_exec",
  "target": "rm -rf ./dist",
  "agentId": "claude-code",
  "decision": "REQUIRE_APPROVAL",
  "rule": "gate-shell",
  "evaluationTime": "0.2ms"
}

4. ALLOW — Running npm install:

{
  "actionType": "shell_exec",
  "target": "npm install lodash",
  "agentId": "claude-code",
  "decision": "ALLOW",
  "rule": "allow-npm-install",
  "evaluationTime": "0.3ms"
}

5. DENY — Default deny on unmatched action:

{
  "actionType": "network",
  "target": "https://external-api.com/data",
  "agentId": "claude-code",
  "decision": "DENY",
  "rule": "deny-network",
  "evaluationTime": "0.2ms"
}

Troubleshooting

Issue 1: Hook script not loading

Symptom: Claude Code runs actions without SafeClaw evaluation.

Fix: Verify the path in ~/.claude/config.json points to the correct hook file. Ensure the file has a .ts extension and exports beforeAction. Restart Claude Code after configuration changes.

Issue 2: All actions denied unexpectedly

Symptom: Every action returns DENY even for paths that should be allowed.

Fix: SafeClaw uses deny-by-default architecture. Check that your safeclaw.config.yaml rules use correct glob patterns. Run with mode: "simulate" and inspect the audit log in the dashboard to see which rules are matching. Verify the target patterns use relative paths consistent with your working directory.

Issue 3: API key authentication failure

Symptom: SafeClaw returns 401 Unauthorized.

Fix: Confirm SAFECLAW_API_KEY is set in your environment or Claude Code config. Free tier keys expire after 7 days and must be renewed at safeclaw.onrender.com. The control plane sees only action metadata, never your keys or file data.

Cross-References

• SafeClaw Action Types Reference
• SafeClaw Policy Configuration Reference
• SafeClaw FAQ: How Does Deny-by-Default Work?
• SafeClaw vs Manual Agent Permissions
• Use Case: Securing Claude Code in Production