gh-greyhaven-ai-claude-code-config-grey-haven-plugins-cc-trace/commands/cc-trace-setup.md

name, description

name	description
cc-trace-setup	Automated setup assistant for cc-trace - install mitmproxy, configure certificates, and verify the environment for intercepting Claude Code API traffic

Set up cc-trace for intercepting and debugging Claude Code API requests using mitmproxy. This command will guide you through the complete setup process automatically.

What This Command Does

1. Check Prerequisites

   • Verify operating system compatibility
   • Check for required tools (brew, python, etc.)
   • Confirm admin permissions available

2. Install mitmproxy

   • Install via platform package manager (Homebrew/apt/pip)
   • Verify installation successful
   • Check version compatibility (9.0+)

3. Generate & Trust Certificate

   • Generate mitmproxy CA certificate
   • Add to system keychain/trust store
   • Verify certificate trust status

4. Verify Setup

   • Run automated verification script
   • Test proxy configuration
   • Confirm certificate validation

5. Provide Usage Instructions

   • Show how to start capture sessions
   • Explain terminal setup
   • Demonstrate basic workflows

Implementation Steps

When you use this command, Claude will:

Step 1: Environment Check

# Check OS type
uname -s

# Check if Homebrew installed (macOS)
which brew

# Check if mitmproxy already installed
which mitmproxy

Step 2: Install mitmproxy

macOS:

brew install mitmproxy

Linux (Debian/Ubuntu):

sudo apt update && sudo apt install -y mitmproxy

Linux (RHEL/Fedora):

sudo dnf install -y mitmproxy

Universal (Python):

pip install mitmproxy

Verify installation:

mitmproxy --version

Step 3: Generate Certificate

Run mitmproxy briefly to generate CA certificate:

# Start and immediately stop mitmproxy to generate cert
timeout 2 mitmproxy 2>/dev/null || true
# OR
mitmproxy &
sleep 2
pkill mitmproxy

Verify certificate exists:

ls -la ~/.mitmproxy/mitmproxy-ca-cert.pem

Step 4: Trust Certificate

macOS:

# Add certificate to system keychain
sudo security add-trusted-cert -d -p ssl -p basic \
  -k /Library/Keychains/System.keychain \
  ~/.mitmproxy/mitmproxy-ca-cert.pem

# Verify trust
security find-certificate -c mitmproxy -a

Linux (Debian/Ubuntu):

# Copy certificate to trusted CA directory
sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem \
  /usr/local/share/ca-certificates/mitmproxy.crt

# Update CA certificates
sudo update-ca-certificates

Linux (RHEL/Fedora):

# Copy certificate
sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem \
  /etc/pki/ca-trust/source/anchors/mitmproxy.pem

# Update trust
sudo update-ca-trust

Step 5: Verify Setup

Run the bundled verification script:

bash ~/.claude/plugins/marketplaces/grey-haven-plugins/grey-haven-plugins/cc-trace/scripts/verify-setup.sh

The script checks:

• ✓ mitmproxy installation
• ✓ Certificate generation
• ✓ Certificate trust (macOS)
• ✓ Proxy configuration readiness

Step 6: Test Proxy Connection

# Start mitmproxy in background
mitmproxy --listen-port 8080 &
MITM_PID=$!

# Test proxy with curl
export HTTPS_PROXY=http://127.0.0.1:8080
export NODE_TLS_REJECT_UNAUTHORIZED=0
curl -I https://api.anthropic.com 2>&1

# Stop mitmproxy
kill $MITM_PID
unset HTTPS_PROXY NODE_TLS_REJECT_UNAUTHORIZED

Success Criteria

Setup is complete when:

• ✅ mitmproxy is installed and working
• ✅ CA certificate exists at ~/.mitmproxy/mitmproxy-ca-cert.pem
• ✅ Certificate is trusted by system (macOS/Linux)
• ✅ Proxy connection test succeeds
• ✅ Verification script passes all checks

Usage After Setup

Option 1: Using the Standalone Script (Recommended)

Terminal 1 - Start mitmweb:

mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com'

Terminal 2 - Run Claude with proxy:

bash ~/.claude/plugins/marketplaces/grey-haven-plugins/grey-haven-plugins/cc-trace/scripts/proxy-claude.sh

Browser - View traffic:

http://127.0.0.1:8081

Option 2: Manual Environment Variables

Terminal 2:

export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
export NODE_EXTRA_CA_CERTS="$HOME/.mitmproxy/mitmproxy-ca-cert.pem"
export NODE_TLS_REJECT_UNAUTHORIZED=0
claude

Troubleshooting

Certificate Trust Issues (macOS)

If certificate verification fails:

# Remove existing certificate
sudo security delete-certificate -c mitmproxy \
  /Library/Keychains/System.keychain 2>/dev/null || true

# Re-add with trust
sudo security add-trusted-cert -d -p ssl -p basic \
  -k /Library/Keychains/System.keychain \
  ~/.mitmproxy/mitmproxy-ca-cert.pem

# Open Keychain Access to verify manually
open /System/Applications/Utilities/Keychain\ Access.app

Port Already in Use

# Check what's using port 8080
lsof -i :8080

# Kill conflicting process if needed
kill $(lsof -t -i:8080)

# Or use different port
mitmweb --listen-port 9090 --web-port 9091

Permission Denied Errors

If you get permission errors:

# Ensure you have sudo access
sudo -v

# On Linux, you may need to add your user to relevant groups
sudo usermod -a -G ssl-cert $USER

# Log out and back in for group changes to take effect

mitmproxy Not Starting

# Check Python version (requires 3.8+)
python3 --version

# Reinstall mitmproxy
pip uninstall mitmproxy
pip install mitmproxy

# Or via package manager
brew reinstall mitmproxy  # macOS
sudo apt reinstall mitmproxy  # Debian/Ubuntu

Security Warnings

⚠️ Important Security Considerations:

1. Local Use Only - This setup is for local debugging on trusted development machines
2. TLS Verification Disabled - NODE_TLS_REJECT_UNAUTHORIZED=0 disables certificate validation
3. Sensitive Data - Captured flows contain API keys, prompts, and file contents
4. CA Trust - Trusting mitmproxy's CA allows it to intercept ALL HTTPS traffic
5. Temporary Setup - Only use when actively debugging

Best Practices:

• Only enable proxy when actively debugging
• Clear captured flows after analysis
• Never share flow files publicly
• Remove certificate trust when done
• Use separate development machine for sensitive work

Output Format

The command will provide:

1. Installation Progress

   🔧 Installing mitmproxy...
   ✓ mitmproxy 10.1.5 installed successfully
   
   🔐 Generating certificate...
   ✓ Certificate created: ~/.mitmproxy/mitmproxy-ca-cert.pem
   
   🔒 Adding certificate to system trust...
   ✓ Certificate trusted in system keychain
   

2. Verification Results

   🔍 Verifying setup...
   ✓ mitmproxy installation
   ✓ Certificate generation
   ✓ Certificate trust
   ✓ Proxy connectivity
   
   ✅ All checks passed! Setup complete.
   

3. Usage Instructions

   🚀 Ready to capture traffic!
   
   Terminal 1:
     mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com'
   
   Terminal 2:
     bash ~/.claude/plugins/.../scripts/proxy-claude.sh
   
   Browser:
     http://127.0.0.1:8081
   

Requirements

• Operating System: macOS, Linux, or Windows
• Python: 3.8+ (for mitmproxy)
• Package Manager: Homebrew (macOS), apt/dnf (Linux), or pip
• Permissions: Ability to trust system certificates (may require sudo)
• Disk Space: ~50MB for mitmproxy and dependencies

Next Steps After Setup

1. Start a Capture Session - Follow usage instructions above
2. Explore Traffic - Open browser to view captured requests
3. Analyze API Calls - Use bundled scripts to extract data
4. Learn Patterns - Understand how Claude Code makes tool calls
5. Optimize Usage - Identify token consumption and redundant operations

Related Commands

• /cc-trace - Interactive agent for debugging and analysis (coming soon)
• Use the cc-trace agent for guided troubleshooting

Documentation

• Plugin README: ~/.claude/plugins/.../cc-trace/README.md
• Original Repository: https://github.com/alexfazio/cc-trace
• mitmproxy Docs: https://docs.mitmproxy.org/

---

Note: This command performs automated setup. If you encounter issues, you can invoke the cc-trace agent for interactive troubleshooting assistance.