Configuration

Clawkeeper configuration depends on which product you are using. The Claude Code hooks are configured via settings.json and enforce policies on every tool call. The CLI scanner uses environment variables and an optional agent daemon for scheduled scans.

Claude Code hooks configuration

The hooks are configured in ~/.claude/settings.json. This file tells Claude Code to send tool calls to Clawkeeper for evaluation before execution, log completed tool calls to the audit trail, and register sessions on startup.

Hook endpoints

Clawkeeper uses four Claude Code hook events:

All four endpoints are fail-open: if the Clawkeeper server is unreachable or returns an error, Claude Code continues normally.

Matcher patterns

Each hook entry includes a matcher field that controls which tools or events trigger the hook:

• UserPromptSubmit: * — fires on every user prompt submission.
• PreToolUse / PostToolUse: Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch — matches the core file-system, shell, and web tools. MCP skill calls (mcp__server__tool) are also caught because they pass through the tool pipeline.
• SessionStart: * — fires on every new session.

API key

• Obtained from Settings > API Keys in the dashboard.
• Starts with ck_live_.
• Write-only: can only send events and check policies. Cannot read back data, list hosts, or access scan results.
• Safe to commit to repos (similar to a Sentry DSN).

Timeout

The timeout field is set to 10 seconds by default. If the endpoint does not respond within this window, Claude Code treats it as a pass and continues execution. This fail-open behavior ensures Clawkeeper never blocks your workflow due to network issues.

Configuration methods

There are five ways to get the hooks into settings.json:

1. Plugin command — Run /clawkeeper:connect inside Claude Code. The plugin writes the hooks JSON for you.
2. Manual — Copy the JSON block below into ~/.claude/settings.json.
3. GitHub Integration — Clawkeeper auto-opens a PR that adds .claude/settings.json to your repo. See GitHub Integration.
4. MDM (JAMF / Intune / Kandji) — Deploy settings.json to managed workstations via a configuration profile. See JAMF Deployment.
5. Project-level — Commit .claude/settings.json to a repo. Claude Code merges project settings with user settings, so hooks apply to anyone working in that repo.

Example settings.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://clawkeeper.dev/api/v1/claude-code/evaluate",
            "headers": {
              "Authorization": "Bearer ck_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch",
        "hooks": [
          {
            "type": "http",
            "url": "https://clawkeeper.dev/api/v1/claude-code/evaluate",
            "headers": {
              "Authorization": "Bearer ck_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|Read|Glob|Grep|WebFetch|WebSearch",
        "hooks": [
          {
            "type": "http",
            "url": "https://clawkeeper.dev/api/v1/claude-code/audit",
            "headers": {
              "Authorization": "Bearer ck_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://clawkeeper.dev/api/v1/claude-code/checkin",
            "headers": {
              "Authorization": "Bearer ck_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Replace ck_live_YOUR_KEY with your actual API key from the Settings page.

CLI scanner configuration

The CLI scanner (clawkeeper.sh) works out of the box with zero configuration. The only optional setting is an API key for SaaS dashboard reporting.

API key

The CLAWKEEPER_API_KEY environment variable connects your scans to the web dashboard at clawkeeper.dev/dashboard. Without it, scans still run locally — you just don't get fleet monitoring.

export CLAWKEEPER_API_KEY="ck_live_..."

You can get an API key from the Settings page in the dashboard after creating an account.

Agent installation

The Clawkeeper agent runs scheduled scans and reports results to the dashboard automatically. It uses systemd timers on Linux and launchd on macOS.

Install the agent

clawkeeper.sh agent --install

This will:

1. Prompt for your API key if CLAWKEEPER_API_KEY is not set
2. Save the config to ~/.config/clawkeeper/
3. Install a scheduled timer/LaunchAgent for periodic scans
4. Run an initial scan and report results

Check agent status

clawkeeper.sh agent --status

Shows whether the agent is configured, the timer is active, and the last scan time.

Remove the agent

clawkeeper.sh agent --uninstall

Removes the scheduled timer, config files, and API key.

Agent config files

The agent stores its configuration in ~/.config/clawkeeper/:

Scan modes

Clawkeeper has two modes controlled by flags:

• Interactive (default for setup/deploy) — prompts you to fix issues as they're found
• Non-interactive (default for scan, also --non-interactive flag) — read-only audit, never modifies your system

The agent always runs in non-interactive mode.

Notification settings

Paid plan users can configure notifications in the dashboard. Email alerts are available on Pro, Team, and Enterprise plans. Webhook alerts require a Team or Enterprise plan. When the agent reports a scan with critical findings, the system can automatically alert you.

Notifications are configured in Settings > Notifications in the dashboard. See the Notifications docs for details on supported event types, webhook payload format, and HMAC signing.

Environment variables

Cloud deploy environment variables

These server-side variables are required for Cloud Deploy and Console. Set them in your hosting environment (e.g. Vercel).