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.

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.

The following hooks are configured:

Images pasted or attached to a prompt are analyzed together with that prompt before Claude receives it, so a prevention policy can block a prompt because of what its image shows. Each image is also stored and shown with its message in the session log.

• Formats and size: PNG, JPEG, GIF and WebP, up to 5 MB per image. Beyond 10 MB of images in one prompt, the remaining images are analyzed after Claude responds and cannot block that prompt.
• What leaves the machine: only images that are part of a submitted prompt. In the terminal, an image pasted and then removed before submitting is not sent.
• Non-interactive runs: images in prompts sent with claude -p are analyzed after Claude responds.
• Older configurations: a managed-settings.json generated before image analysis was available still sends images, but only after Claude responds, so they cannot block the prompt. Redeploy the current configuration to analyze images before submission.

Before you begin, ensure you have:

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

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

Deploy the configuration to every developer machine with your Mobile Device Management (MDM) tool.

Setup:

1. Deploy the downloaded managed-settings.json file to the appropriate path for your platform:

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).

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

3. 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

For step-by-step, platform-specific instructions, see the dedicated MDM guides:

• Jamf Pro
• Kandji
• JumpCloud
• Microsoft Intune
• ManageEngine Endpoint Central
• Microsoft SCCM
• Tanium

For the hooks to take effect:

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

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

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

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

For help with this integration:

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

• Claude Code Hooks Documentation
• Claude Code Hooks Guide
• Claude Code Settings
• Claude Code Hook Configuration