Skip to content
Guides
/
/
Claude Code
Last updated

Claude Code Integration

Connect Claude Code to Capsule Security for complete visibility into AI coding assistant activity, including prompts, tool execution, session lifecycle, and MCP tool usage.

Overview

This integration uses Claude Code's hooks system to capture AI coding assistant activity. Hooks are shell commands that execute at specific points in Claude Code's lifecycle, providing automated workflows and audit capabilities.

Claude Code Hooks

The following hooks are configured:

Hook EventDescription
SessionStartSession initialization and context with MCP tools definitions
UserPromptSubmitUser prompts before submission to Claude
PreToolUseTool execution requests (before execution)
PostToolUseTool execution results (after successful completion)
StopAgent stop events when the agent finished responding
SessionEndSession termination and cleanup

Prerequisites

Before you begin, ensure you have:

  • Claude Code installed
  • A Capsule Security account with admin access

Step 1: Generate the Configuration

  1. Log in to the Capsule Security portal

  2. Navigate to Integrations and locate Claude Code

  3. Click Install — Capsule automatically generates a managed-settings.json file containing:

    • Hook commands for all lifecycle events
    • An embedded authentication token scoped to your organization
    • Platform-specific scripts (bash for macOS/Linux, PowerShell for Windows)

  4. Select your target platform (macOS, Linux, or Windows) to download the configuration file

Step 2: Deploy the Configuration

Deployment Methods

Enterprise organizations with Claude Code Pro can use remote managed settings to centrally control and distribute hooks across the organization.

Overview:

Remote managed settings are configured via the Claude.ai admin console and automatically fetched when users authenticate. This method provides the highest level of security and control by:

  • Enforcing organization-wide hook policies that cannot be overridden by users
  • Automatically synchronizing configurations to all authenticated team members
  • Allowing strict control over which hooks are permitted to run
  • Blocking user, project, and plugin hooks when allowManagedHooksOnly is enabled

Setup:

  1. Access the Claude.ai admin console with your enterprise administrator account

  2. Navigate to the Settings section

  3. Configure the hooks provided by Capsule Security with allowManagedHooksOnly enabled:

    {
  "allowManagedHooksOnly": true,
  "hooks": {
    "UserPromptSubmit": [...],
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SessionStart": [...],
    "SessionEnd": [...]
  }
}

  4. Save and publish the configuration

Behavior:

When allowManagedHooksOnly is set to true:

  • Managed hooks (configured via admin console) are loaded and executed
  • User hooks (~/.claude/settings.json) are blocked
  • Project hooks (.claude/settings.json) are blocked
  • Plugin hooks are blocked

This ensures only administrator-approved hooks run, preventing users from disabling or circumventing the Capsule Security integration.

Settings Precedence:

Claude Code applies settings in the following order (highest to lowest):

  1. Remote managed settings - Cannot be overridden
  2. File-based managed settings (managed-settings.json) - Ignored when remote managed settings are configured
  3. Command line arguments
  4. Local project settings (.claude/settings.local.json)
  5. Shared project settings (.claude/settings.json)
  6. User settings (~/.claude/settings.json)

Key Features:

  • Centralized management through Claude.ai admin console
  • Automatic synchronization to all authenticated team members
  • Cannot be overridden by users or project settings
  • Enforces enterprise security policies across the organization
  • No manual deployment to individual machines required

MDM Distribution with User Settings

For organizations without Claude Code Enterprise or those preferring traditional MDM deployment, use Mobile Device Management tools to deploy hooks to user settings files.

Setup:

  1. Deploy the downloaded managed-settings.json file to the appropriate path for your platform:
PlatformPath
macOS/Library/Application Support/ClaudeCode/managed-settings.json
Linux / WSL/etc/claude-code/managed-settings.json
WindowsC:\Program Files\ClaudeCode\managed-settings.json

Use your organization's device management solution (Jamf, Intune, SCCF, etc.) to distribute the file to all developer machines. Set appropriate file permissions (read-only recommended).

  1. Include the hooks configuration provided by Capsule Security in the deployed file

  2. Set appropriate file permissions (read-only recommended to prevent user modifications)

Limitations:

  • Users can potentially override or disable hooks with project-level settings (.claude/settings.json)
  • Users can add local overrides via .claude/settings.local.json
  • Requires MDM infrastructure capable of deploying user-level configuration files
  • Manual updates required when hooks configuration changes

Key Considerations:

  • Centrally managed by your IT or security team
  • Your organization is responsible for deployment and updates
  • Less secure than Option A as users may override settings
  • Suitable when remote managed settings are not available

Step 3: Restart Claude Code

For the hooks to take effect:

  1. Exit Claude Code by pressing Ctrl+C or typing /exit
  2. Restart Claude Code

Step 4: Verify the Installation

  1. Run /hooks in Claude Code to confirm all hooks are listed

  2. Start a session and execute a simple task to generate activity:

    Create a new file called test.txt with the content "Hello World"

  3. Log in to the Capsule Security portal

  4. Navigate to Inventory > Agents and confirm your Claude Code agent appears

  5. Click on the agent and review the audit logs to verify events are captured:

    • Session start event
    • User prompt
    • Tool execution (Write tool)
    • Session activity

  6. To view the full conversation, navigate to Observability and filter by Activity Type — Session

Troubleshooting

If events are not appearing:

  1. Verify the managed-settings.json is in the correct path for your platform (see Step 2)

  2. Check file permissions — the file must be readable by the user running Claude Code

  3. Verify settings file syntax — ensure the file contains valid JSON:

    cat "/Library/Application Support/ClaudeCode/managed-settings.json" | python3 -m json.tool

  4. Run /hooks in Claude Code — if no hooks are listed, the file is not being loaded

  5. Check Claude Code logs for hook execution errors

  6. Contact Capsule Security support if issues persist

Security Considerations

Claude Code hooks execute with your current environment credentials. Before deploying hooks:

  1. Review all hook scripts provided by Capsule Security
  2. Verify the endpoint URL matches your organization's Capsule instance
  3. Protect authentication tokens used by hooks (never commit to version control)
  4. Use .claude/settings.local.json for sensitive configuration values
  5. Ensure .claude/settings.local.json is in .gitignore

Support

For help with this integration:

  • Email: support@capsule.security
  • Include: Your organization ID, integration status, and any error messages

References

Previous page
Next page