docsClaude Code

Claude Code Integration

Reins integrates with Claude Code via PreToolUse and PostToolUse hooks registered in .claude/settings.json. Every tool call is intercepted synchronously — the agent cannot proceed until the hook exits.

Install

npm install -g @pegasi-ai/reins
reins init

reins init detects Claude Code, writes the hooks into .claude/settings.json, and runs an initial security scan.

What gets installed

reins init adds hook entries for five matchers: Bash, Edit, MultiEdit, Write, and "" (empty matcher catches all MCP tool calls).

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",      "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/pre-tool-use.js", "_reins": true }] },
      { "matcher": "Edit",      "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/pre-tool-use.js", "_reins": true }] },
      { "matcher": "MultiEdit", "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/pre-tool-use.js", "_reins": true }] },
      { "matcher": "Write",     "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/pre-tool-use.js", "_reins": true }] },
      { "matcher": "",          "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/pre-tool-use.js", "_reins": true }] }
    ],
    "PostToolUse": [
      { "matcher": "Bash",      "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/post-tool-use.js", "_reins": true }] },
      { "matcher": "Edit",      "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/post-tool-use.js", "_reins": true }] },
      { "matcher": "MultiEdit", "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/post-tool-use.js", "_reins": true }] },
      { "matcher": "Write",     "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/post-tool-use.js", "_reins": true }] },
      { "matcher": "",          "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/post-tool-use.js", "_reins": true }] }
    ]
  }
}

The _reins marker lets Reins identify and update its own hooks without touching any other entries.

Hook exit codes

Exit codeMeaningClaude Code behavior
0ALLOWEDProceed normally
2BLOCKEDTool call is cancelled; stderr is shown to the user
0 + JSON decision: WARNWARNINGProceed with caution; warning surfaced in output

Skill

The Reins skill teaches Claude Code how to respond when an action is blocked — attributing the block to Reins, explaining the rule, and suggesting safe alternatives.

Claude Code has no npx add-skill command or central skill registry. Skills are markdown files placed in ~/.claude/skills/<name>/SKILL.md. There are three ways to get it:

Via reins init (recommended) — the wizard installs the skill automatically alongside the hooks. Nothing else needed.

Project-level — commit .claude/skills/reins/SKILL.md into your repo. Anyone who clones gets it with no install step:

.claude/skills/reins/SKILL.md

Personal install via curl — available across all your projects, not just this repo:

mkdir -p ~/.claude/skills/reins
curl -o ~/.claude/skills/reins/SKILL.md \
  https://raw.githubusercontent.com/pegasi-ai/reins/main/skill/SKILL.md

All three can coexist. reins init installs to ~/.claude/skills/reins/ (personal). The project-level file takes no extra steps and works for contributors who haven’t run reins init.

Personal — available across all your projects:

mkdir -p ~/.claude/skills/reins
curl -o ~/.claude/skills/reins/SKILL.md \
  https://raw.githubusercontent.com/pegasi-ai/reins/main/skill/SKILL.md

Examples

Blocked: recursive root deletion

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | node dist/hooks/pre-tool-use.js
🪢 Reins: action blocked
  Severity: CRITICAL
  Reason:   Critically destructive command
  Tool:     Bash
  Action:   rm -rf /
  Rule:     rm\s+-rf\s+[\/~]

This action was blocked by Reins. Do not retry it.
Run `reins audit -n 5` to view the logged decision.

Blocked: write to protected path

echo '{"tool_name":"Write","tool_input":{"file_path":"~/.ssh/authorized_keys","content":"..."}}' \
  | node dist/hooks/pre-tool-use.js
🪢 Reins: action blocked
  Severity: CRITICAL
  Reason:   Write to protected path
  Tool:     Write
  Action:   ~/.ssh/authorized_keys
  Rule:     protected_path:~/.ssh

Audit trail after blocks

reins audit -n 3
════════════════════════════════════════════════════════════════════════════════
   📋 ClawReins Audit Trail
════════════════════════════════════════════════════════════════════════════════

Showing last 3 decision(s):

8:28:28 PM | Shell.bash                | BLOCKED    |   0.0s
8:29:01 PM | FileSystem.write          | BLOCKED    |   0.0s
8:31:15 PM | FileSystem.read           | ALLOWED    |   0.0s

Audit log: ~/.openclaw/clawreins/decisions.jsonl

Verify your setup

reins status   # hook status + Reins Cloud connection
reins scan     # 13-check security audit
reins audit    # last 50 decisions

Temporarily suspend enforcement

reins disable   # suspend all hooks
reins enable    # resume

Disabled state is stored in ~/.openclaw/clawreins/config.json so it persists across sessions. Always re-enable after testing.

Getting StartedOpenClaw