Skip to main content

Claude Code Integration

SigmaShake integrates with Claude Code in two complementary ways:

  1. MCP tools — Claude Code calls ssg_* tools directly to set up governance, search the Hub, write rules, and diagnose issues
  2. PreToolUse hook — Every tool call Claude Code makes is evaluated against your rules before it executes

Both are configured automatically by a single command.

Quick setup​

ssg init --client=claude-code

This writes to .claude/settings.json (macOS/Linux: ~/.claude/settings.json, Windows: %USERPROFILE%\.claude\settings.json):

  • Hook — registers ssg hook eval as a PreToolUse handler
  • MCP server — registers ssg mcp-server as ssg-governance
  • Permissions — 14 standard tools pre-approved, 18 destructive patterns pre-denied

Restart Claude Code once, then say:

"Set up SigmaShake governance for my project"

MCP Tools (AI-assisted setup)​

With the MCP server connected, Claude Code has access to 19 governance tools it can use autonomously:

Ask ClaudeTool
"Set up SigmaShake for my project"ssg_onboard — one-shot project setup
"Check if governance is working"ssg_doctor — full health diagnostics
"Find TypeScript rules on the Hub"ssg_hub_search
"Install rules-docker"ssg_hub_pull
"Block kubectl in production"ssg_write_rule — AI-authored rule

See MCP Server for the complete tool reference.

PreToolUse Hook (runtime protection)​

Every time Claude Code calls a tool, the PreToolUse hook runs ssg hook eval:

Claude calls: Bash("git push --force origin main")
                     ↓
         ssg hook eval evaluates against rules
                     ↓
         Decision: block
                     ↓
         Claude receives: "Force push is blocked."
         Claude does NOT execute the command.

Hook configuration​

The hook entry in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "ssg hook eval"
      }
    ]
  }
}

ssg hook eval automatically dispatches to the native ssg-hook-fast binary when available, which ships alongside ssg in every distribution channel (npm, Homebrew, PyPI, winget) and eliminates ~20ms of Bun startup latency on each tool call.

Circuit breaker​

After 5 consecutive DENY decisions, the hook auto-allows to prevent complete agent lockout. This guards against misconfigured rules that block all tool calls.

Reset: rm /tmp/ssg-deny-count (Windows: del %TEMP%\ssg-deny-count)

Permissions​

ssg init --client=claude-code pre-configures permissions.allow and permissions.deny so you don't need to whitelist tools manually.

Allowed (14 standard tools):

Bash(*), Read, Write, Edit, MultiEdit, Glob, Grep, Agent,
WebFetch, WebSearch, TodoWrite, TodoRead, AskUserQuestion, ToolSearch

Denied (18 destructive patterns):

Bash(rm -rf *)       Bash(rm -r *)        Bash(rmdir *)
Bash(dd *)           Bash(mkfs *)         Bash(git push --force*)
Bash(git push -f*)   Bash(git reset --hard*)  Bash(git clean -f*)
Read(.env)           Read(.env.*)         Read(*/secrets/*)
Read(*/.aws/*)       Read(*/.ssh/*)       Read(*/credentials*)
Write(.env)          Write(.env.*)        Write(*/secrets/*)

Permissions are merged additively — existing entries are never removed. Running ssg init again is safe.

Apply permissions globally (all projects, no hooks):

ssg init --global

Tool capability mapping​

SigmaShake maps Claude Code's tool names to SSG capability categories for rule matching:

Claude Code ToolSSG Capability
Bashexecution
Readread
Write, Edit, MultiEditwrite
Glob, Grepsearch
Agentagent
WebFetch, WebSearchnetwork
Anything elseany

Write rules targeting capabilities, not individual tools:

DENY execution    →  blocks Bash
DENY write        →  blocks Write, Edit, MultiEdit
DENY any          →  blocks everything

Human approval flow (ASK rules)​

When a rule uses ASK, Claude Code pauses and waits:

  1. Terminal bell rings
  2. Claude Code displays: "Waiting for human approval..."
  3. Dashboard at http://localhost:5599 shows the queued decision
  4. You approve or deny in the dashboard
  5. Claude Code resumes with the result

Start the dashboard before using ASK rules:

ssg serve

Agent monitoring​

Monitor Claude Code's Agent tool (sub-agent spawning):

rule log-explore-agents {
  enabled true
  LOG agent
  IF input.subagent_type EQUALS "Explore"
  MESSAGE "Explore agent activity logged."
}

rule block-background-agents {
  enabled true
  DENY agent
  IF input.run_in_background EQUALS "true"
  MESSAGE "Background agents require explicit approval."
}

The dashboard audit table shows agent subagent_type as inline badges.

Example rules for Claude Code​

Require approval for deployments​

rule require-approval-deploy {
  enabled true
  priority 90
  severity error
  ASK execution
  IF command CONTAINS "deploy"
  OR command CONTAINS "kubectl apply"
  OR command CONTAINS "terraform apply"
  MESSAGE "Deployment detected."
  PROMPT "Allow this deployment?"
}

Block npm publish without approval​

rule require-approval-npm-publish {
  enabled true
  priority 90
  severity error
  ASK execution
  IF command CONTAINS "npm publish"
  MESSAGE "npm publish detected."
  PROMPT "Allow publishing to npm registry?"
}

Log all file writes to src/​

rule log-src-writes {
  enabled true
  LOG write
  IF path GLOB "src/**"
  MESSAGE "Source file write logged."
}

Troubleshooting​

Hook not triggering​

Check the hook is registered:

cat .claude/settings.json | grep -A5 "PreToolUse"

Re-run if missing:

ssg init --client=claude-code

All tools being blocked​

Check for broad rules:

ssg list          # show all active rules
ssg lint          # check for syntax issues

Reset circuit breaker:

rm /tmp/ssg-deny-count

MCP tools not visible in Claude Code​

  1. Verify ssg mcp-server starts cleanly: 
    echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ssg mcp-server
  2. Restart Claude Code (MCP connections initialize at startup)
  3. Check ~/.claude/mcp_config.json or .claude/mcp_config.json for the ssg-governance entry

ASK decisions not appearing in dashboard​

ssg status     # check daemon is running
ssg serve      # start dashboard at localhost:5599