Configuration

AgentKeeper configuration depends on which agent surface you are securing. Claude Code can load hooks from the AgentKeeper plugin, user/project settings.json, or managed settings. The recommended macOS fleet path is the universal signed PKG, which safely reconciles AgentKeeper-owned entries while preserving developer hooks. Customers that want Claude organization plugin governance can optionally distribute AgentKeeper as an organization-managed plugin. Cursor, Windsurf, GitHub Copilot Agent Mode, Codex, Gemini CLI, Google Antigravity, and Claude Desktop / Cowork use local hook scripts or plugin packages. The MCP gateway is optional for teams that also want MCP proxying.

Examples use https://www.agentkeeper.dev as the app origin. Replace it with the URL of your AgentKeeper deployment.

Claude Code hooks configuration

For individual or repo-scoped setup, hooks can be configured in ~/.claude/settings.json or .claude/settings.json. For macOS fleet setup, AgentKeeper's MDM artifact safely merges AgentKeeper-owned hooks into ~/.claude/settings.json without replacing existing hooks. The hook source tells Claude Code to evaluate prompts and tool calls before execution, log completed tool calls to the audit trail, and register sessions on startup.

Hook endpoints

AgentKeeper uses four Claude Code hook events:

The API path is fail-open for normal requests: if the AgentKeeper server is unreachable or returns an error, Claude Code continues normally. If local command preflight detects a critical control-integrity issue before the API call, the hook can still block locally because the server cannot inspect local helper-script contents on its own.

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: *, matches every Claude Code tool event, including core file-system, shell, web, and MCP skill calls (mcp__server__tool).
• SessionStart: *, fires on every new session.

API key

• Obtained from Settings > Access > API keys in the dashboard.
• Starts with ak_live_.
• Write-only: can only send events and check policies. Cannot read back data, list hosts, or access scan results.
• Treat it as a secret. Do not commit it to repositories or paste it into logs, screenshots, or support messages.

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 AgentKeeper never blocks your workflow due to network issues.

Configuration methods

There are five ways to get Claude Code hooks loaded:

1. Plugin command: run /agentkeeper:connect inside Claude Code. The plugin safe-merges the hooks JSON for you, including command-based Inventory Lite for skills, MCP servers, and plugins. It preserves existing non-AgentKeeper hooks and leaves ~/.claude/settings.json untouched if the file is invalid JSON.

2. Manual runtime-only: merge the JSON block below into ~/.claude/settings.json. This protects prompts and tool calls through HTTP, but it is for individual or repo-scoped setup. Do not replace the existing file or the whole hooks object. Use the MDM safe-merge artifact for enterprise macOS rollout.

   Claude Code on Windows uses the same merge rule in the Intune Win32 installer.

3. GitHub Integration: AgentKeeper auto-opens a PR that adds .claude/settings.json to your repo. See GitHub Integration.

4. MDM (Jamf / Iru/Kandji / Intune): start with Enterprise install and deploy the approved OS package for that rollout scope. On macOS, every provider uses the same universal PKG. The runtime must never replace the whole file or the whole hooks object, and malformed existing settings must be fixed before AgentKeeper writes.

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://www.agentkeeper.dev/api/v1/claude-code/evaluate",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://www.agentkeeper.dev/api/v1/claude-code/evaluate",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://www.agentkeeper.dev/api/v1/claude-code/audit",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://www.agentkeeper.dev/api/v1/claude-code/checkin",
            "headers": {
              "Authorization": "Bearer ak_live_YOUR_KEY"
            },
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Replace ak_live_YOUR_KEY with your actual API key from the Settings page. For full Agent Inventory without the MCP gateway, use /agentkeeper:connect so SessionStart runs the plugin's read-only Inventory Lite scanner instead of the HTTP-only example above.

Multi-agent hook installer

This installer is for an unmanaged Mac or standalone Linux workstation. Managed Macs use the universal PKG and must not run this installer beside it. The standalone installer wires Cursor, Windsurf, GitHub Copilot Agent Mode, Codex, Gemini CLI, and Google Antigravity to the unified policy endpoint:

export AGENTKEEPER_API_URL="https://www.agentkeeper.dev"
export AGENTKEEPER_API_KEY="ak_live_..."
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh")

You can target one IDE:

bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide cursor
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide windsurf
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide copilot
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide codex
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide gemini
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide antigravity

The installer stores the API key in ~/.agentkeeper/config and installs the appropriate hook file for the selected tool. Do not run this shell installer from Windows shells or WSL when you are trying to protect the native Windows host. Do not run it on a Mac managed by the universal PKG. Do not run it on a workstation managed by the Linux Universal RPM. Those packages use a device credential, peer-authenticated broker, managed catalog, and owned-entry reconciliation instead of a user API key.

Claude Desktop / Cowork hook installer

Cowork runs inside Claude Desktop and does not support Claude Code slash commands. Use the Cowork installer after the user has opened Claude Desktop and started Cowork at least once.

Windows Cowork

Windows uses PowerShell and the Windows-native Cowork plugin ZIP. The installer checks classic Claude Desktop storage under %APPDATA%\Claude, Microsoft Store/MSIX storage under %LOCALAPPDATA%\Packages\Claude_*\LocalCache\..., and Cowork on 3P storage under %LOCALAPPDATA%\Claude-3p.

$ErrorActionPreference='Stop'; $scriptPath=Join-Path $env:TEMP 'cowork-windows-install.ps1'; $scriptUri='https://www.agentkeeper.dev/cowork-windows-install.ps1'; for($i=1;$i -le 5;$i++){try{Invoke-WebRequest -UseBasicParsing $scriptUri -OutFile $scriptPath -TimeoutSec 60; break}catch{if($i -eq 5){throw}; Start-Sleep -Seconds ([Math]::Min(($i * 2),10))}}; $nativePowerShell=if($env:PROCESSOR_ARCHITEW6432){Join-Path $env:WINDIR 'Sysnative\WindowsPowerShell\v1.0\powershell.exe'}else{Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'}; if(-not (Test-Path $nativePowerShell)){$nativePowerShell='powershell.exe'}; & $nativePowerShell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -AgentKeeperApiUrl 'https://www.agentkeeper.dev' -AgentKeeperApiKey 'ak_live_REPLACE_ME'; if($LASTEXITCODE -ne 0){throw ('AgentKeeper Cowork helper exited with code ' + $LASTEXITCODE)}

Verify with:

$ErrorActionPreference='Stop'; $scriptPath=Join-Path $env:TEMP 'cowork-windows-status.ps1'; $scriptUri='https://www.agentkeeper.dev/cowork-windows-status.ps1'; for($i=1;$i -le 5;$i++){try{Invoke-WebRequest -UseBasicParsing $scriptUri -OutFile $scriptPath -TimeoutSec 60; break}catch{if($i -eq 5){throw}; Start-Sleep -Seconds ([Math]::Min(($i * 2),10))}}; $nativePowerShell=if($env:PROCESSOR_ARCHITEW6432){Join-Path $env:WINDIR 'Sysnative\WindowsPowerShell\v1.0\powershell.exe'}else{Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'}; if(-not (Test-Path $nativePowerShell)){$nativePowerShell='powershell.exe'}; & $nativePowerShell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -AgentKeeperApiUrl 'https://www.agentkeeper.dev' -SelfTest; if($LASTEXITCODE -ne 0){throw ('AgentKeeper Cowork helper exited with code ' + $LASTEXITCODE)}

When running the Windows Cowork status helper elevated, as SYSTEM, or from MDM, add -TargetUser "DOMAIN\developer" or -TargetUserUpn "developer@example.com" so the helper validates the intended developer profile. If no Cowork session directory is found, start a local Cowork session in Claude Desktop, connect/select a folder, send one Cowork message, then rerun the installer.

The self-test is not live protection. After the self-test, fully quit Claude Desktop, relaunch it, start a new Cowork chat, run a real tool action, and rerun status without -SelfTest. Healthy live status shows a non-self-test session_id; if Claude Desktop shows /bin/sh or pre-tool-hook.sh on Windows, replace the plugin with the Windows ZIP below.

Download the Windows plugin ZIP when Claude Desktop asks for a local plugin upload:

Invoke-WebRequest -UseBasicParsing 'https://www.agentkeeper.dev/downloads/cowork/latest/agentkeeper-cowork-guardrail-windows.zip' -OutFile (Join-Path $env:USERPROFILE 'Desktop\agentkeeper-cowork-guardrail-windows.zip')

If Microsoft Store opens, Windows was asked to resolve python, python3, bash, or WSL from the wrong command path. Use the PowerShell commands above.

macOS / vendor-supported standalone Linux Cowork

curl -fsSL https://www.agentkeeper.dev/cowork-install.sh | \
  AGENTKEEPER_API_URL=https://www.agentkeeper.dev \
  bash

The installer opens browser-based device approval, stores the returned key in ~/.agentkeeper-plugin/api_key, writes shared hook config under ~/.agentkeeper/, and registers an AgentKeeper local plugin under ~/Library/Application Support/Claude/local-agent-mode-sessions/**/cowork_plugins. For headless or MDM installs, pass AGENTKEEPER_API_KEY=ak_live_... with the same command.

Anthropic's current Linux requirements cover Ubuntu and Debian, not RHEL or Rocky Linux. The Universal RPM reports Cowork as discovery-only on those distributions and does not claim enforcement.

Verify with:

AGENTKEEPER_API_URL=https://www.agentkeeper.dev \
  bash <(curl -fsSL https://www.agentkeeper.dev/cowork-status.sh)

AGENTKEEPER_API_URL=https://www.agentkeeper.dev \
  bash <(curl -fsSL https://www.agentkeeper.dev/cowork-status.sh) --self-test

The self-test should report server check-in, last evaluate request ... http_status=200, both marketplace/cache manifest hooks, and Cowork plugin enabled.

API key

The AGENTKEEPER_API_KEY environment variable connects local hooks and gateways to the web dashboard.

export AGENTKEEPER_API_KEY="ak_live_..."

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

Local config files

The hook installers store their configuration in ~/.agentkeeper/:

The Cowork one-shot installer also writes ~/.agentkeeper-plugin/api_key and ~/.agentkeeper-plugin/config.json for compatibility with Claude Desktop local plugin execution.

The MCP gateway stores its configuration in ~/.config/agentkeeper-mcp-gateway/config.json. See MCP Gateway for gateway-specific options.

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.

Environment variables