Skip to content

Claude Code Integration

Comprehensive guide for using Preloop as a governance layer with Claude Code.

Overview

Claude Code is Anthropic's AI coding assistant, available as a CLI tool and VS Code extension. When combined with Preloop, you get a powerful human-in-the-loop safety layer that:

  • Intercepts dangerous operations before they execute
  • Requires approval for shell commands, file writes, and sensitive actions
  • Provides audit logging for all AI-initiated operations
  • Enables custom policies tailored to your security requirements

Looking for setup instructions?

See the Claude Code Client Reference for installation and basic configuration.

Why Use Preloop with Claude Code?

Claude Code is incredibly capable - it can execute shell commands, modify files, browse the web, and interact with external services. This power comes with risk:

Without Preloop With Preloop
Claude can run any shell command Dangerous commands require approval
Files can be modified silently Sensitive paths trigger review
No audit trail Complete operation history
All-or-nothing access Granular policy control

Quick Start

1. Connect Claude Code to Preloop

claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  preloop \
  https://your-preloop-instance.com/mcp/v1

2. Configure Basic Policies

In your Preloop dashboard, create policies for Claude Code tools:

# Require approval for all shell commands
tools:
  - name: "bash"
    source: "claude_code"
    approval_workflow: "manual-approval"

3. Use Claude Code Normally

When Claude attempts a controlled operation, you'll receive an approval request:

$ claude chat "Delete all log files older than 7 days"

Claude: I'll help you clean up old log files.

Tool call: bash(command="find /var/log -name '*.log' -mtime +7 -delete")

⏳ Waiting for approval...
   Approval request sent to your email and dashboard.

[You approve via email, mobile, or dashboard]

✓ Approval received!
✓ Command executed successfully

Policy Configuration

Shell Command Policies

Shell commands are often the most dangerous operations. Configure policies based on your risk tolerance:

Block Destructive Commands

tools:
  - name: "bash"
    source: "claude_code"
    conditions:
      - expression: |
          args.command.contains('rm -rf') ||
          args.command.contains('drop database') ||
          args.command.contains('truncate table')
        action: "deny"
        message: "Destructive commands must be executed manually"

Approve All Shell Commands (High Security)

tools:
  - name: "bash"
    source: "claude_code"
    approval_workflow: "manual-approval"

Approve Only Specific Patterns (Medium Security)

tools:
  - name: "bash"
    source: "claude_code"
    conditions:
      # Block sudo entirely
      - expression: "args.command.startsWith('sudo')"
        action: "deny"
        message: "Sudo commands require manual execution"

      # Require approval for package management
      - expression: |
          args.command.contains('npm install') ||
          args.command.contains('pip install') ||
          args.command.contains('apt install')
        approval_workflow: "manual-approval"

      # Require approval for git push
      - expression: "args.command.contains('git push')"
        approval_workflow: "manual-approval"

File Write Policies

Control which files Claude Code can modify:

Protect Sensitive Files

tools:
  - name: "write"
    source: "claude_code"
    conditions:
      # Block credential files
      - expression: |
          args.path.endsWith('.env') ||
          args.path.contains('credentials') ||
          args.path.contains('secrets') ||
          args.path.endsWith('.pem') ||
          args.path.endsWith('.key')
        action: "deny"
        message: "Credential files cannot be modified by AI"

      # Approve system config changes
      - expression: |
          args.path.startsWith('/etc/') ||
          args.path.startsWith('/usr/') ||
          args.path.startsWith('/opt/')
        approval_workflow: "manual-approval"

Protect Production Config

tools:
  - name: "write"
    source: "claude_code"
    conditions:
      # Approve production config changes
      - expression: |
          args.path.contains('prod') ||
          args.path.contains('production') ||
          args.path.contains('deploy')
        approval_workflow: "manual-approval"

Browser/Network Policies

If using Claude Code's browser capabilities:

tools:
  - name: "browser"
    source: "claude_code"
    conditions:
      # Approve form submissions
      - expression: "args.action == 'submit'"
        approval_workflow: "manual-approval"

      # Block certain domains
      - expression: |
          args.url.contains('admin.') ||
          args.url.contains('/settings')
        action: "deny"
        message: "Admin pages require direct access"

Workflow Examples

Code Review with Approval

Use Claude Code to review PRs while requiring approval for any modifications:

  1. Claude analyzes the PR: 

    Using @preloop tools, review PR #123 for security issues

  2. Claude identifies issues and proposes changes: 

    Claude: I found 3 security issues in this PR:
1. SQL injection vulnerability in user_service.py
2. Hardcoded API key in config.py
3. Missing input validation in api/users.py

I'll add review comments and request changes.

Tool call: update_pull_request(
  pull_request="https://github.com/myorg/myrepo/pull/123",
  review_action="request_changes",
  review_body="Security issues found..."
)

⏳ Waiting for approval...

  3. You review Claude's proposed feedback and approve

  4. Review is submitted to GitHub/GitLab

Database Migrations with Approval

Claude: Based on the new User model, I'll generate and run the migration.

Tool call: bash(command="alembic revision --autogenerate -m 'add_user_table'")
✓ Generated migration file

Tool call: bash(command="alembic upgrade head")
⏳ Waiting for approval...
   Migration detected - requires human review.

[You review the migration and approve]

✓ Migration applied successfully

Deployment with Safeguards

Configure policies to require approval for any deployment-related operations:

tools:
  - name: "bash"
    source: "claude_code"
    conditions:
      - expression: |
          args.command.contains('deploy') ||
          args.command.contains('kubectl apply') ||
          args.command.contains('docker push') ||
          args.command.contains('terraform apply')
        approval_workflow: "manual-approval"
        timeout_seconds: 1800  # 30 min timeout for deploy reviews

Enterprise Configuration

Team-Based Approvals

Configure different approval requirements based on team or role:

approval_workflows:
  - name: "production-deploy"
    description: "Requires senior engineer approval"
    approvers:
      - role: "senior-engineer"
      - role: "tech-lead"
    required_approvals: 1

  - name: "infrastructure-change"
    description: "Requires ops team approval"
    approvers:
      - team: "platform-ops"
    required_approvals: 2

Audit Logging

All Claude Code operations through Preloop are logged:

{
  "timestamp": "2025-01-27T10:23:45Z",
  "user": "alice@company.com",
  "agent": "claude_code",
  "tool": "bash",
  "arguments": {
    "command": "rm -rf /tmp/cache/*"
  },
  "approval_status": "approved",
  "approver": "bob@company.com",
  "execution_result": "success"
}

Access audit logs via: - Dashboard: Settings → Audit Logs - API: GET /api/v1/audit/logs - Export: CSV, JSON, or SIEM integration

SSO Integration

For enterprise deployments, configure SSO for seamless authentication:

  1. Set up SAML/OIDC in Preloop admin
  2. Map Claude Code users to Preloop accounts
  3. Apply policies based on identity provider groups

Best Practices

1. Start Permissive, Then Tighten

Begin with approval requirements for obviously dangerous operations, then expand based on observed patterns:

# Phase 1: Block only the most dangerous
- expression: "args.command.contains('rm -rf /')"
  action: "deny"

# Phase 2: Add approval for destructive operations
- expression: "args.command.contains('rm -rf')"
  approval_workflow: "manual-approval"

# Phase 3: Require approval for all shell commands
approval_workflow: "manual-approval"

2. Use Descriptive Denial Messages

When blocking operations, explain why:

conditions:
  - expression: "args.command.startsWith('sudo')"
    action: "deny"
    message: |
      Sudo commands are blocked for AI agents.
      Please execute this command manually:
      {{ args.command }}

3. Set Appropriate Timeouts

Long-running operations need longer approval windows:

approval_workflows:
  - name: "quick-approval"
    timeout_seconds: 300  # 5 minutes for simple operations

  - name: "deployment-approval"
    timeout_seconds: 3600  # 1 hour for complex deployments

4. Enable Mobile Notifications

For time-sensitive approvals, enable push notifications:

  1. Install the Preloop mobile app
  2. Enable notifications for Claude Code approvals
  3. Approve from your phone, watch, or tablet

5. Review Audit Logs Regularly

Monitor Claude Code's behavior to: - Identify patterns that need new policies - Detect unusual or suspicious activity - Optimize approval workflows

Troubleshooting

Connection Issues

MCP server not responding: 

# Test connectivity
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-preloop-instance.com/mcp/v1/health

# Check Claude Code MCP status
claude mcp test preloop

Authentication failures: - Verify API key is valid and not expired - Check key has appropriate scopes - Ensure no extra whitespace in key

Approval Timeouts

Approvals expiring before you can respond:

  1. Increase timeout in policy configuration
  2. Enable push notifications
  3. Check email spam folders for approval requests

Approvals not appearing:

  1. Verify you're in the approvers list
  2. Check tool matches policy conditions
  3. Review audit logs for routing issues

Policy Not Triggering

Operations bypassing policies:

  1. Verify policy is enabled
  2. Check condition expressions match the tool arguments
  3. Test with more specific conditions
  4. Review policy evaluation order (first match wins)

Security Considerations

API Key Management

  • Generate separate API keys for each developer
  • Rotate keys regularly (monthly recommended)
  • Never commit keys to version control
  • Use environment variables: PRELOOP_API_KEY

Network Security

For enterprise deployments: - Use private endpoints where possible - Configure IP allowlists - Enable mTLS for MCP connections - Monitor for unusual traffic patterns

Data Privacy

Preloop processes tool call data for policy evaluation: - Command text and file paths are evaluated - Configure data retention policies - Use on-premise deployment for sensitive environments - Enable end-to-end encryption for approvals