Claude Code

This guide shows how to integrate Claude Code with Maybe Don’t using hooks.

Prerequisites

Maybe Don’t gateway running in http or sse mode (see Get Started)
Claude Code installed
jq and curl on PATH
MAYBE_DONT_URL environment variable set (e.g., http://localhost:8080)

Install the Hook

Export the hook script into your project’s .claude/hooks/ directory:

mkdir -p .claude/hooks
maybe-dont hooks export --agent claude-code > $CLAUDE_PROJECT_DIR/.claude/hooks/maybe-dont-hook.sh
chmod +x $CLAUDE_PROJECT_DIR/.claude/hooks/maybe-dont-hook.sh

Configure Claude Code

Export the config snippet and add it to your Claude Code settings:

maybe-dont hooks export --agent claude-code --config

This outputs a JSON snippet to merge into .claude/settings.json. Update the command path to where you placed the hook script. The default configuration uses "matcher": "Bash" to validate CLI tool calls via hooks while the MCP gateway handles MCP tools:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/maybe-dont-hook.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/maybe-dont-hook.sh"
          }
        ]
      }
    ]
  }
}

Using hooks without the MCP gateway? Change the matcher to "*" to validate all tool calls (both CLI and MCP) via hooks, or add a second entry with "matcher": "mcp__.*" for MCP tools specifically. See the comments in the exported config for details.

Set the gateway URL before starting Claude Code:

export MAYBE_DONT_URL="http://localhost:8080"

Supported Events

Event	Phase	Description
`PreToolUse`	Pre-tool	Fires before Claude Code executes a tool. The hook can block the tool call.
`PostToolUse`	Post-tool	Fires after tool execution. Observability only — results are logged but cannot be blocked or modified.

Verify It Works

Start Claude Code and trigger a tool call. Check the gateway’s audit log for entries — you should see an intercept record for the tool call.

claude

The hook is silent on allow. On deny, you’ll see stderr output like:

[maybe-dont] WARNING (PostToolUse): Policy violation detected — <reason>

Filtering

Claude Code hooks use a matcher field to filter which tools trigger the hook. The matcher is a regex tested against the tool name. The default configuration uses "Bash" to match CLI tools only, while the MCP gateway handles MCP tools.

Matcher	What it matches
`"Bash"`	CLI tool calls only (default)
`"mcp__.*"`	MCP tool calls only
`"Edit\|Write"`	File editing tools
`"*"` or omitted	All tools

To change what triggers the hook, update the matcher field in .claude/settings.json. See the Claude Code hooks reference for the full list of matcher patterns.

Agent-Specific Notes

$CLAUDE_PROJECT_DIR resolves to the project root at runtime, ensuring the hook works regardless of the agent’s working directory.
Claude Code passes tool details as JSON on stdin to the hook script.

Cursor