Skip to main content

Claude Code Integration

This guide expands on the quickstart and explains the hook flow in detail.

Quickstart first: Govern Claude Code in 10 Minutes.

Architecture​

Claude Code -> PreToolUse Hook -> @sequenceware/cli -> Sequenceware Events API
                                                     |
                                                     +-> Policy engine -> allow | warn | block | require_approval

1. Configure project-level Sequenceware settings​

{
  "baseUrl": "http://localhost:3000",
  "apiKey": "acl_replace_with_your_key",
  "agentId": "claude-code"
}

Save this as .sequenceware.json at your project root.

2. Configure Claude Code hook​

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "command": "npx @sequenceware/cli check"
      }
    ]
  }
}

Save this as .claude/settings.json.

3. Verify hook behavior​

Blocked example:

echo '{"tool_input":{"command":"git push --force origin main"},"session_id":"cc-deep-dive-1","tool_name":"Bash"}' \
  | npx @sequenceware/cli check

echo "$?"

Expected status codes:

  • 0: allow (or warn)
  • 2: block or approval required

4. Understand what is tracked​

Each check sends a tool.called event with:

  • runId (auto-managed per Claude session)
  • toolName
  • inputPayload
  • sessionId
  • matchedPolicies and resulting status from Sequenceware

Review the raw contract in Events API.

5. Approval behavior​

When a policy action is require_approval, CLI feedback is written to stderr and includes an approval URL when provided by Sequenceware.

Review queue behavior in Approvals.

Troubleshooting​

  • Missing config: ensure .sequenceware.json exists or set SEQUENCEWARE_URL + SEQUENCEWARE_API_KEY.
  • No events in dashboard: confirm backend is reachable at baseUrl and API key is valid.
  • Hook not firing: verify Claude reads .claude/settings.json from your current workspace.