Initial commit

2025-11-29 18:29:02 +08:00
commit bcf931aa4e
7 changed files with 1607 additions and 0 deletions
--- a/commands/cc-trace-setup.md
+++ b/commands/cc-trace-setup.md
@@ -0,0 +1,344 @@
+---
+name: cc-trace-setup
+description: 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
+```bash
+# Check OS type
+uname -s
+
+# Check if Homebrew installed (macOS)
+which brew
+
+# Check if mitmproxy already installed
+which mitmproxy
+```
+
+### Step 2: Install mitmproxy
+
+**macOS:**
+```bash
+brew install mitmproxy
+```
+
+**Linux (Debian/Ubuntu):**
+```bash
+sudo apt update && sudo apt install -y mitmproxy
+```
+
+**Linux (RHEL/Fedora):**
+```bash
+sudo dnf install -y mitmproxy
+```
+
+**Universal (Python):**
+```bash
+pip install mitmproxy
+```
+
+Verify installation:
+```bash
+mitmproxy --version
+```
+
+### Step 3: Generate Certificate
+
+Run mitmproxy briefly to generate CA certificate:
+```bash
+# Start and immediately stop mitmproxy to generate cert
+timeout 2 mitmproxy 2>/dev/null || true
+# OR
+mitmproxy &
+sleep 2
+pkill mitmproxy
+```
+
+Verify certificate exists:
+```bash
+ls -la ~/.mitmproxy/mitmproxy-ca-cert.pem
+```
+
+### Step 4: Trust Certificate
+
+**macOS:**
+```bash
+# 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):**
+```bash
+# 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):**
+```bash
+# 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
+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
+
+```bash
+# 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:**
+```bash
+mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com'
+```
+
+**Terminal 2 - Run Claude with proxy:**
+```bash
+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:**
+```bash
+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:
+```bash
+# 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
+
+```bash
+# 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:
+```bash
+# 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
+
+```bash
+# 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.