├── scripts ├── show-last-prompt.sh ├── extract-slash-commands.py ├── verify-setup.sh └── parse-streamed-response.ts ├── LICENSE.txt ├── reference ├── usage-cli-interface.md ├── setup-installation-certificate.md ├── setup-shell-configuration.md ├── workflow-daily-tips.md ├── usage-web-interface.md ├── advanced-features-security.md └── usage-programmatic-access.md └── SKILL.md /scripts/show-last-prompt.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Show the last user prompt sent to Claude API 3 | # Usage: ./show-last-prompt.sh [flow-file] 4 | 5 | FLOW_FILE="${1:-$HOME/claude-flows.mitm}" 6 | 7 | if [ ! -f "$FLOW_FILE" ]; then 8 | echo "No flow file found at: $FLOW_FILE" 9 | exit 1 10 | fi 11 | 12 | echo "Extracting last user prompt from: $FLOW_FILE" 13 | echo "================================================================" 14 | 15 | mitmdump -r "$FLOW_FILE" -s - <<'PYTHON' 16 | import json 17 | from mitmproxy import http 18 | 19 | last_user_message = None 20 | 21 | def response(flow: http.HTTPFlow): 22 | global last_user_message 23 | 24 | if "api.anthropic.com" not in flow.request.pretty_url: 25 | return 26 | 27 | try: 28 | data = json.loads(flow.request.content.decode('utf-8')) 29 | messages = data.get('messages', []) 30 | 31 | # Find last user message 32 | for msg in reversed(messages): 33 | if msg.get('role') == 'user': 34 | content = msg.get('content', []) 35 | if isinstance(content, str): 36 | last_user_message = content 37 | elif isinstance(content, list): 38 | text = '\n'.join([c.get('text', '') for c in content if c.get('type') == 'text']) 39 | last_user_message = text 40 | break 41 | except: 42 | pass 43 | 44 | def done(): 45 | if last_user_message: 46 | print(last_user_message) 47 | else: 48 | print("No user messages found") 49 | PYTHON 50 | -------------------------------------------------------------------------------- /scripts/extract-slash-commands.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | Extract slash command expansions from captured mitmproxy flows. 4 | Usage: mitmdump -r flows.mitm -s extract-slash-commands.py 5 | """ 6 | 7 | import json 8 | from mitmproxy import http 9 | 10 | def response(flow: http.HTTPFlow): 11 | """Process each flow and extract user messages (slash command expansions)""" 12 | 13 | if "api.anthropic.com" not in flow.request.pretty_url: 14 | return 15 | 16 | try: 17 | # Parse request body 18 | request_data = json.loads(flow.request.content.decode('utf-8')) 19 | 20 | # Extract messages 21 | messages = request_data.get('messages', []) 22 | 23 | for i, msg in enumerate(messages): 24 | if msg.get('role') == 'user': 25 | content = msg.get('content', []) 26 | 27 | # Handle both string and array content formats 28 | if isinstance(content, str): 29 | text = content 30 | elif isinstance(content, list): 31 | text_parts = [c.get('text', '') for c in content if c.get('type') == 'text'] 32 | text = '\n'.join(text_parts) 33 | else: 34 | continue 35 | 36 | # Print user message with separator 37 | print(f"\n{'='*80}") 38 | print(f"USER MESSAGE #{i+1}") 39 | print(f"{'='*80}") 40 | print(text) 41 | print(f"{'='*80}\n") 42 | 43 | except Exception as e: 44 | print(f"Error processing flow: {e}") 45 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | MICROSOFT REFERENCE SOURCE LICENSE (MS-RSL) 2 | 3 | This license governs use of the accompanying software. If you use the software, you accept this license. If you do not accept the license, do not use the software. 4 | 1. Definitions 5 | 6 | The terms "reproduce," "reproduction" and "distribution" have the same meaning here as under U.S. copyright law. 7 | 8 | "You" means the licensee of the software. 9 | 10 | "Your company" means the company you worked for when you downloaded the software. 11 | 12 | "Reference use" means use of the software within your company as a reference, in read only form, for the sole purposes of debugging your products, maintaining your products, or enhancing the interoperability of your products with the software, and specifically excludes the right to distribute the software outside of your company. 13 | 14 | "Licensed patents" means any Licensor patent claims which read directly on the software as distributed by the Licensor under this license. 15 | 2. Grant of Rights 16 | 17 | (A) Copyright Grant- Subject to the terms of this license, the Licensor grants you a non-transferable, non-exclusive, worldwide, royalty-free copyright license to reproduce the software for reference use. 18 | 19 | (B) Patent Grant- Subject to the terms of this license, the Licensor grants you a non-transferable, non-exclusive, worldwide, royalty-free patent license under licensed patents for reference use. 20 | 3. Limitations 21 | 22 | (A) No Trademark License- This license does not grant you any rights to use the Licensor's name, logo, or trademarks. 23 | 24 | (B) If you begin patent litigation against the Licensor over patents that you think may apply to the software (including a cross-claim or counterclaim in a lawsuit), your license to the software ends automatically. 25 | 26 | (C) The software is licensed "as-is." You bear the risk of using it. The Licensor gives no express warranties, guarantees or conditions. You may have additional consumer rights under your local laws which this license cannot change. To the extent permitted under your local laws, the Licensor excludes the implied warranties of merchantability, fitness for a particular purpose and non-infringement. 27 | 28 | Read more about this license at http://referencesource.microsoft.com/license.html 29 | -------------------------------------------------------------------------------- /reference/usage-cli-interface.md: -------------------------------------------------------------------------------- 1 | # CLI Interface Guide (Optional/Advanced) 2 | 3 | This guide covers using mitmproxy's terminal interface instead of the web interface. 4 | 5 | **[← Previous: Web Interface Guide](usage-web-interface.md)** | **[Next: Daily Workflow & Tips →](workflow-daily-tips.md)** 6 | 7 | --- 8 | 9 | ## Using mitmproxy CLI 10 | 11 | If you prefer a terminal interface instead of web: 12 | 13 | ### Start mitmproxy 14 | 15 | 1. Start mitmproxy (CLI version) 16 | 17 | ```bash 18 | mitmproxy 19 | ``` 20 | 21 | 2. The terminal interface will appear with a list view of captured flows 22 | 23 | ### Basic Keyboard Shortcuts 24 | 25 | - `↑`/`↓`: Navigate flows 26 | - `Enter`: View flow details 27 | - `q`: Back/quit 28 | - `f`: Filter 29 | - `C`: Clear all flows 30 | - `?`: Help 31 | 32 | ### Viewing Flow Details 33 | 34 | 1. Use arrow keys to select a flow 35 | 2. Press `Enter` to view details 36 | 3. Navigate tabs: 37 | - `Tab`: Cycle through Request/Response/Detail tabs 38 | - `e`: Edit the selected flow 39 | - `m`: Change view mode (hex, auto, etc.) 40 | 4. Press `q` to return to flow list 41 | 42 | ### Filtering Flows 43 | 44 | 1. Filter examples: 45 | - Press `f` 46 | - Type: `~d api.anthropic.com` 47 | - Press `Enter` 48 | 49 | Common filter expressions: 50 | 51 | ``` 52 | # Show only Anthropic API requests 53 | ~d api.anthropic.com 54 | 55 | # Show only POST requests 56 | ~m POST 57 | 58 | # Show requests with "messages" in URL 59 | ~u messages 60 | 61 | # Combine filters 62 | ~d api.anthropic.com & ~m POST 63 | 64 | # Show only responses with status 200 65 | ~c 200 66 | 67 | # Show requests larger than 1000 bytes 68 | ~bq 1000 69 | ``` 70 | 71 | 2. Clear filter: 72 | - Press `f` 73 | - Clear the filter text 74 | - Press `Enter` 75 | 76 | --- 77 | 78 | ## Using mitmdump (Headless Mode) 79 | 80 | For logging traffic without an interface: 81 | 82 | ### Basic Usage 83 | 84 | ```bash 85 | # Log all traffic to a file 86 | mitmdump -w output.mitm 87 | 88 | # Filter while logging 89 | mitmdump -w output.mitm --set flow_filter='~d api.anthropic.com' 90 | 91 | # Print requests to console 92 | mitmdump --flow-detail 2 93 | ``` 94 | 95 | ### Replay Captured Flows 96 | 97 | ```bash 98 | # Replay with mitmproxy CLI 99 | mitmproxy -r saved-flows.mitm 100 | 101 | # Replay with mitmweb 102 | mitmweb -r saved-flows.mitm 103 | ``` 104 | 105 | --- 106 | 107 | ## Quick Reference: CLI Commands 108 | 109 | ```bash 110 | # Start mitmproxy (CLI) 111 | mitmproxy 112 | 113 | # Start with filtering 114 | mitmproxy --set flow_filter='~d api.anthropic.com' 115 | 116 | # Start mitmdump (headless, logging) 117 | mitmdump -w output.mitm 118 | 119 | # Replay saved flows 120 | mitmproxy -r saved-flows.mitm 121 | ``` 122 | 123 | --- 124 | 125 | ## When to Use CLI vs Web Interface 126 | 127 | **Use Web Interface (mitmweb) when:** 128 | - You want easy visual inspection 129 | - You need to search/filter frequently 130 | - You're analyzing complex request/response structures 131 | - You prefer point-and-click navigation 132 | 133 | **Use CLI (mitmproxy) when:** 134 | - You prefer keyboard-driven workflows 135 | - You're working on a remote server without GUI 136 | - You want to minimize resource usage 137 | - You're comfortable with terminal interfaces 138 | 139 | **Use mitmdump when:** 140 | - You need automated logging 141 | - You're running scripts to process traffic 142 | - You want minimal overhead 143 | - You're integrating with other tools 144 | 145 | --- 146 | 147 | **[← Previous: Web Interface Guide](usage-web-interface.md)** | **[Next: Daily Workflow & Tips →](workflow-daily-tips.md)** 148 | -------------------------------------------------------------------------------- /reference/setup-installation-certificate.md: -------------------------------------------------------------------------------- 1 | # Installation & Certificate Setup 2 | 3 | This guide covers installing mitmproxy, generating certificates, and installing them on your system. 4 | 5 | **[← Back to Overview](SKILL.md)** | **[Next: Shell Configuration →](setup-shell-configuration.md)** 6 | 7 | --- 8 | 9 | ## Step 1: Install mitmproxy 10 | 11 | ### Option A: Using Homebrew (Recommended for macOS) 12 | 13 | 1. Install via Homebrew 14 | 15 | ```bash 16 | brew install --cask mitmproxy 17 | ``` 18 | 19 | 2. Verify installation 20 | 21 | ```bash 22 | mitmproxy --version 23 | ``` 24 | 25 | You should see version information for mitmproxy, mitmweb, and mitmdump. 26 | 27 | ### Option B: Download Standalone Binaries 28 | 29 | 1. Visit https://mitmproxy.org/ 30 | 2. Download the appropriate package for your OS 31 | 3. Extract and add to your PATH 32 | 33 | ### Troubleshooting: "Command not found: mitmproxy" 34 | 35 | If you get this error after installation: 36 | 37 | 1. Verify Homebrew installation: 38 | 39 | ```bash 40 | brew list | grep mitmproxy 41 | ``` 42 | 43 | 2. Reinstall if needed: 44 | 45 | ```bash 46 | brew reinstall mitmproxy 47 | ``` 48 | 49 | 3. Check PATH: 50 | 51 | ```bash 52 | which mitmweb 53 | ``` 54 | 55 | --- 56 | 57 | ## Step 2: Start mitmproxy and Generate Certificates 58 | 59 | 1. Start mitmproxy for the first time (this generates the CA certificate in `~/.mitmproxy/`): 60 | 61 | ```bash 62 | mitmproxy 63 | ``` 64 | 65 | 2. Verify certificate generation 66 | 67 | ```bash 68 | ls ~/.mitmproxy/ 69 | ``` 70 | 71 | You should see files like: 72 | - mitmproxy-ca-cert.pem 73 | - mitmproxy-ca-cert.p12 74 | - mitmproxy-ca.pem 75 | - And others 76 | 77 | 3. Exit mitmproxy (press `q` then `y` to quit) 78 | 79 | --- 80 | 81 | ## Step 3: Install mitmproxy CA Certificate on macOS 82 | 83 | To intercept HTTPS traffic, you need to trust mitmproxy's Certificate Authority. 84 | 85 | ### Method A: Automatic Installation (Easiest) 86 | 87 | 1. Start mitmweb 88 | 89 | ```bash 90 | mitmweb 91 | ``` 92 | 93 | 2. Configure your browser to use the proxy temporarily 94 | - Set HTTP/HTTPS proxy to localhost:8080 95 | - Or use browser extensions like FoxyProxy 96 | 97 | 3. Visit the magic URL 98 | - Navigate to http://mitm.it 99 | - Click on the Apple icon 100 | - Download and install the certificate 101 | - Follow macOS prompts to trust it 102 | 103 | 4. Quit mitmweb (press `Ctrl+C` in the terminal) 104 | 105 | ### Method B: Command Line Installation (Recommended) 106 | 107 | This method directly installs the certificate to the system keychain: 108 | 109 | ```bash 110 | sudo security add-trusted-cert -d -p ssl -p basic -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem 111 | ``` 112 | 113 | Enter your macOS password when prompted. 114 | 115 | ### Verify Certificate Installation 116 | 117 | 1. Open Keychain Access (`Cmd+Space`, type "Keychain Access") 118 | 2. Select System keychain 119 | 3. Search for "mitmproxy" 120 | 4. You should see "mitmproxy" certificate marked as trusted 121 | 122 | --- 123 | 124 | ## Verification Checklist 125 | 126 | Use this to ensure everything is working: 127 | 128 | - [ ] mitmproxy is installed (`mitmproxy --version` works) 129 | - [ ] Certificate generated in `~/.mitmproxy/` 130 | - [ ] CA certificate installed and trusted in macOS Keychain 131 | 132 | --- 133 | 134 | ## Troubleshooting 135 | 136 | ### SSL/Certificate Errors 137 | 138 | **Error:** `UNABLE_TO_VERIFY_LEAF_SIGNATURE` or similar 139 | 140 | **Solutions:** 141 | 142 | 1. Verify certificate path is correct: 143 | 144 | ```bash 145 | ls -la ~/.mitmproxy/mitmproxy-ca-cert.pem 146 | ``` 147 | 148 | 2. Check certificate is trusted: 149 | 150 | ```bash 151 | security find-certificate -c mitmproxy -a 152 | ``` 153 | 154 | 3. Re-install the certificate: 155 | 156 | ```bash 157 | sudo security add-trusted-cert -d -p ssl -p basic -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem 158 | ``` 159 | 160 | 4. Check the certificate file exists and is readable: 161 | 162 | ```bash 163 | cat ~/.mitmproxy/mitmproxy-ca-cert.pem | head -n 3 164 | ``` 165 | 166 | Should show `-----BEGIN CERTIFICATE-----` 167 | 168 | ### Proxy works but HTTPS content is encrypted/unreadable 169 | 170 | **Solutions:** 171 | 172 | 1. Verify NODE_EXTRA_CA_CERTS will be set (we'll configure this in the next guide) 173 | 174 | 2. Test certificate manually: 175 | 176 | ```bash 177 | NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem curl -x http://127.0.0.1:8080 https://api.anthropic.com 178 | ``` 179 | 180 | --- 181 | 182 | **[← Back to Overview](SKILL.md)** | **[Next: Shell Configuration →](setup-shell-configuration.md)** 183 | -------------------------------------------------------------------------------- /reference/setup-shell-configuration.md: -------------------------------------------------------------------------------- 1 | # Shell Configuration 2 | 3 | This guide covers setting up the `proxy_claude` function to easily run Claude Code through mitmproxy. 4 | 5 | **[← Previous: Installation & Certificate Setup](setup-installation-certificate.md)** | **[Next: Web Interface Guide →](usage-web-interface.md)** 6 | 7 | --- 8 | 9 | ## Configure Shell for Claude Code Proxying 10 | 11 | ### Edit Your Shell Configuration 12 | 13 | 1. Open your shell config file 14 | 15 | For zsh (default on modern macOS): 16 | 17 | ```bash 18 | nano ~/.zshrc 19 | ``` 20 | 21 | For bash: 22 | 23 | ```bash 24 | nano ~/.bashrc 25 | ``` 26 | 27 | 2. Copy and paste this at the end of the file: 28 | 29 | ```bash 30 | proxy_claude() { 31 | # Set proxy environment variables 32 | export HTTP_PROXY=http://127.0.0.1:8080 33 | export HTTPS_PROXY=http://127.0.0.1:8080 34 | export http_proxy=http://127.0.0.1:8080 35 | export https_proxy=http://127.0.0.1:8080 36 | 37 | # Point Node.js to mitmproxy's CA certificate for HTTPS 38 | export NODE_EXTRA_CA_CERTS="$HOME/.mitmproxy/mitmproxy-ca-cert.pem" 39 | 40 | # Disable SSL verification warnings (optional, use with caution) 41 | export NODE_TLS_REJECT_UNAUTHORIZED=0 42 | 43 | echo "🔍 Proxy configured for mitmproxy (http://127.0.0.1:8080)" 44 | echo "📜 Using CA cert: $NODE_EXTRA_CA_CERTS" 45 | echo "🚀 Starting Claude Code..." 46 | 47 | # Launch Claude Code 48 | claude 49 | } 50 | ``` 51 | 52 | 3. Save the file (press `Ctrl+O`, then `Enter`, then `Ctrl+X`) 53 | 54 | 4. Reload your shell configuration 55 | 56 | ```bash 57 | # For zsh 58 | source ~/.zshrc 59 | 60 | # For bash 61 | source ~/.bashrc 62 | ``` 63 | 64 | 5. Verify the function exists 65 | 66 | ```bash 67 | type proxy_claude 68 | ``` 69 | 70 | You should see the function definition printed. 71 | 72 | --- 73 | 74 | ## Verification Checklist 75 | 76 | - [ ] `proxy_claude` function exists (`type proxy_claude` works) 77 | - [ ] Function is saved in shell configuration file 78 | 79 | --- 80 | 81 | ## Troubleshooting 82 | 83 | ### Claude Code doesn't respect proxy settings 84 | 85 | **Solutions:** 86 | 87 | 1. Ensure you're using `proxy_claude` function, not just `claude` 88 | 89 | 2. Verify in the proxy_claude terminal: 90 | 91 | ```bash 92 | env | grep -i proxy 93 | ``` 94 | 95 | Should show `HTTP_PROXY`, `HTTPS_PROXY`, etc. 96 | 97 | 3. Try setting additional proxy variables: 98 | 99 | ```bash 100 | export ALL_PROXY=http://127.0.0.1:8080 101 | export no_proxy="localhost,127.0.0.1" 102 | ``` 103 | 104 | ### No traffic appears in mitmweb 105 | 106 | If you complete this setup and later find no traffic is being captured: 107 | 108 | 1. Check environment variables in Claude Code terminal: 109 | 110 | ```bash 111 | echo $HTTP_PROXY 112 | echo $HTTPS_PROXY 113 | echo $NODE_EXTRA_CA_CERTS 114 | ``` 115 | 116 | All should be set correctly. 117 | 118 | 2. Test the proxy with curl: 119 | 120 | ```bash 121 | curl -x http://127.0.0.1:8080 http://example.com 122 | ``` 123 | 124 | This should appear in mitmweb when it's running. 125 | 126 | ### Function not found after restart 127 | 128 | If `proxy_claude` is not available after restarting your terminal: 129 | 130 | 1. Verify you edited the correct shell config file: 131 | 132 | ```bash 133 | # Check which shell you're using 134 | echo $SHELL 135 | 136 | # For zsh, should be in ~/.zshrc 137 | # For bash, should be in ~/.bashrc 138 | ``` 139 | 140 | 2. Make sure the function was saved properly: 141 | 142 | ```bash 143 | # For zsh 144 | grep -A 20 "proxy_claude()" ~/.zshrc 145 | 146 | # For bash 147 | grep -A 20 "proxy_claude()" ~/.bashrc 148 | ``` 149 | 150 | --- 151 | 152 | ## Custom Port Configuration 153 | 154 | If you need to use different ports (e.g., port 8080 is already in use), modify the function: 155 | 156 | ```bash 157 | proxy_claude() { 158 | # Use custom ports (example: 9090 for proxy, 9091 for web) 159 | export HTTP_PROXY=http://127.0.0.1:9090 160 | export HTTPS_PROXY=http://127.0.0.1:9090 161 | export http_proxy=http://127.0.0.1:9090 162 | export https_proxy=http://127.0.0.1:9090 163 | 164 | export NODE_EXTRA_CA_CERTS="$HOME/.mitmproxy/mitmproxy-ca-cert.pem" 165 | export NODE_TLS_REJECT_UNAUTHORIZED=0 166 | 167 | echo "🔍 Proxy configured for mitmproxy (http://127.0.0.1:9090)" 168 | echo "📜 Using CA cert: $NODE_EXTRA_CA_CERTS" 169 | echo "🚀 Starting Claude Code..." 170 | 171 | claude 172 | } 173 | ``` 174 | 175 | Then start mitmweb with: `mitmweb --listen-port 9090 --web-port 9091` 176 | 177 | --- 178 | 179 | **[← Previous: Installation & Certificate Setup](setup-installation-certificate.md)** | **[Next: Web Interface Guide →](usage-web-interface.md)** 180 | -------------------------------------------------------------------------------- /reference/workflow-daily-tips.md: -------------------------------------------------------------------------------- 1 | # Daily Workflow & Tips 2 | 3 | This guide covers typical daily usage patterns and what insights you can gain from inspecting Claude Code's traffic. 4 | 5 | **[← Previous: CLI Interface Guide](usage-cli-interface.md)** | **[Next: Advanced Features & Security →](advanced-features-security.md)** 6 | 7 | --- 8 | 9 | ## Daily Usage Workflow 10 | 11 | Once set up, here's your typical workflow: 12 | 13 | ### Start Your Session 14 | 15 | 1. Terminal 1: Start mitmweb 16 | 17 | ```bash 18 | mitmweb --web-port 8081 19 | ``` 20 | 21 | 2. Terminal 2: Start Claude Code with proxy 22 | 23 | ```bash 24 | proxy_claude 25 | ``` 26 | 27 | 3. Browser: Open mitmweb at http://127.0.0.1:8081 28 | 29 | ### During Your Session 30 | 31 | - Use Claude Code normally 32 | - Monitor traffic in mitmweb 33 | - Click on requests to inspect details 34 | - Filter as needed with: `~d api.anthropic.com` 35 | 36 | ### End Your Session 37 | 38 | 1. Exit Claude Code (type `/exit` or close the session) 39 | 2. Stop mitmweb (press `Ctrl+C` in Terminal 1) 40 | 3. Optional: Clear proxy environment 41 | 42 | ```bash 43 | unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NODE_EXTRA_CA_CERTS 44 | ``` 45 | 46 | --- 47 | 48 | ## Parse Streamed Responses (Optional) 49 | 50 | Anthropic's API uses Server-Sent Events (SSE) streaming, which can be hard to read in raw format. 51 | 52 | ### Option A: Use the Web Interface 53 | 54 | mitmweb shows streamed responses but they may appear as: 55 | 56 | ``` 57 | event: message_start 58 | data: {"type":"message_start"...} 59 | 60 | event: content_block_delta 61 | data: {"type":"content_block_delta"...} 62 | ``` 63 | 64 | ### Option B: Parse with a Python Script 65 | 66 | 1. Save the following script as `~/claude-analysis/parse-sse.py`: 67 | 68 | ```python 69 | #!/usr/bin/env python3 70 | import sys 71 | import json 72 | 73 | for line in sys.stdin: 74 | line = line.strip() 75 | if line.startswith('data: '): 76 | try: 77 | data = json.loads(line[6:]) 78 | print(json.dumps(data, indent=2)) 79 | except json.JSONDecodeError: 80 | pass 81 | ``` 82 | 83 | 2. Make it executable 84 | 85 | ```bash 86 | chmod +x ~/claude-analysis/parse-sse.py 87 | ``` 88 | 89 | 3. Use it by copying the raw response from mitmweb and pasting into the terminal: 90 | 91 | ```bash 92 | pbpaste | python3 ~/claude-analysis/parse-sse.py 93 | ``` 94 | 95 | ### Option C: Use a TypeScript Parser 96 | 97 | For more advanced parsing: 98 | - Get the TypeScript parser from https://github.com/gsabran/claude-code-system-prompts 99 | - Use `npx tsx` to run it 100 | 101 | --- 102 | 103 | ## What You Can Inspect 104 | 105 | Once properly set up, you'll see: 106 | 107 | ### Request Details 108 | 109 | - **System prompts:** Instructions given to Claude Code 110 | - **User messages:** Your actual queries 111 | - **Tool definitions:** Available tools (Read, Write, Bash, TodoWrite, Task, etc.) 112 | - **Context:** File contents, git status, conversation history 113 | - **Model parameters:** 114 | - `model`: e.g., "claude-sonnet-4-5-20250929" 115 | - `max_tokens`: Token limits 116 | - `temperature`: Randomness setting 117 | - `stream`: Whether using streaming responses 118 | 119 | ### Response Details 120 | 121 | - **Model outputs:** Claude's text responses 122 | - **Tool calls:** Which tools Claude uses and when 123 | - **Tool parameters:** Arguments passed to each tool 124 | - **Token usage:** Input/output token counts 125 | - **Thinking blocks:** Claude's reasoning process (if available) 126 | - **Stop reasons:** Why generation stopped 127 | 128 | --- 129 | 130 | ## Patterns You'll Discover 131 | 132 | By inspecting traffic over time, you'll notice: 133 | 134 | ### Parallel Tool Calls 135 | - Multiple tools called simultaneously 136 | - Used when operations are independent 137 | 138 | ### Sequential Operations 139 | - Tool dependencies (one result feeds into another) 140 | - Used when operations must happen in order 141 | 142 | ### Context Window Management 143 | - How Claude Code summarizes conversations 144 | - When context is trimmed to fit token limits 145 | 146 | ### Task Delegation 147 | - When sub-agents are spawned 148 | - How tasks are isolated with separate context 149 | 150 | ### TODO System 151 | - How tasks are tracked and completed 152 | - When todos are created, updated, and marked complete 153 | 154 | ### Optimization Strategies 155 | - Using cheaper models (Haiku) for simple tasks 156 | - Delegating subtasks to isolate context 157 | - Summarizing when approaching token limits 158 | 159 | --- 160 | 161 | ## Tips for Effective Analysis 162 | 163 | ### Focus on Specific Endpoints 164 | 165 | ```bash 166 | # Only show /messages endpoint 167 | mitmweb --set flow_filter='~d api.anthropic.com & ~u /messages' 168 | ``` 169 | 170 | ### Look for Patterns 171 | 172 | - Compare requests for similar tasks 173 | - Note which tools are used together 174 | - Observe how context grows over time 175 | 176 | ### Export Important Flows 177 | 178 | - Right-click → Export to save interesting interactions 179 | - Keep a library of examples for reference 180 | 181 | ### Compare Model Behavior 182 | 183 | - Try the same task multiple times 184 | - Note variations in tool usage 185 | - Identify consistent patterns 186 | 187 | --- 188 | 189 | **[← Previous: CLI Interface Guide](usage-cli-interface.md)** | **[Next: Advanced Features & Security →](advanced-features-security.md)** 190 | -------------------------------------------------------------------------------- /scripts/verify-setup.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | # Setup verification script for cc-trace skill 3 | # Verifies mitmproxy installation, certificate trust, and proxy configuration 4 | 5 | set -e 6 | 7 | # Colors for output 8 | RED='\033[0;31m' 9 | GREEN='\033[0;32m' 10 | YELLOW='\033[1;33m' 11 | NC='\033[0m' # No Color 12 | 13 | echo "🔍 CC-Trace Setup Verification" 14 | echo "================================" 15 | echo "" 16 | 17 | # Track overall status 18 | ALL_CHECKS_PASSED=true 19 | 20 | # Check 1: mitmproxy installation 21 | echo "📦 Checking mitmproxy installation..." 22 | if command -v mitmproxy &> /dev/null; then 23 | MITM_VERSION=$(mitmproxy --version 2>&1 | head -n 1) 24 | echo -e "${GREEN}✓${NC} mitmproxy is installed: $MITM_VERSION" 25 | else 26 | echo -e "${RED}✗${NC} mitmproxy is not installed" 27 | echo " Install with: brew install mitmproxy" 28 | ALL_CHECKS_PASSED=false 29 | fi 30 | echo "" 31 | 32 | # Check 2: mitmproxy certificate exists 33 | echo "🔐 Checking mitmproxy certificate..." 34 | CERT_PATH="$HOME/.mitmproxy/mitmproxy-ca-cert.pem" 35 | if [ -f "$CERT_PATH" ]; then 36 | echo -e "${GREEN}✓${NC} Certificate exists at: $CERT_PATH" 37 | 38 | # Check certificate trust on macOS 39 | if [[ "$OSTYPE" == "darwin"* ]]; then 40 | if security find-certificate -c mitmproxy -a 2>/dev/null | grep -q "mitmproxy"; then 41 | echo -e "${GREEN}✓${NC} Certificate is installed in keychain" 42 | 43 | # Check if trusted for SSL 44 | if security find-certificate -c mitmproxy -p 2>/dev/null | openssl x509 -noout -text 2>/dev/null | grep -q "Certificate"; then 45 | echo -e "${GREEN}✓${NC} Certificate appears to be trusted" 46 | else 47 | echo -e "${YELLOW}⚠${NC} Could not verify certificate trust - may need manual verification" 48 | fi 49 | else 50 | echo -e "${RED}✗${NC} Certificate is NOT installed in keychain" 51 | echo " Install with: sudo security add-trusted-cert -d -p ssl -p basic -k /Library/Keychains/System.keychain $CERT_PATH" 52 | ALL_CHECKS_PASSED=false 53 | fi 54 | fi 55 | else 56 | echo -e "${RED}✗${NC} Certificate not found at: $CERT_PATH" 57 | echo " Generate by running: mitmproxy (then quit with 'q')" 58 | ALL_CHECKS_PASSED=false 59 | fi 60 | echo "" 61 | 62 | # Check 3: Shell function existence 63 | echo "⚙️ Checking proxy_claude function..." 64 | if type proxy_claude &> /dev/null; then 65 | echo -e "${GREEN}✓${NC} proxy_claude function is defined" 66 | else 67 | echo -e "${RED}✗${NC} proxy_claude function is not defined" 68 | echo " Add function to ~/.zshrc or ~/.bashrc (see setup-shell-configuration.md)" 69 | ALL_CHECKS_PASSED=false 70 | fi 71 | echo "" 72 | 73 | # Check 4: Current proxy environment (if any) 74 | echo "🌐 Checking current proxy environment..." 75 | if [ -n "$HTTP_PROXY" ] || [ -n "$HTTPS_PROXY" ]; then 76 | echo -e "${YELLOW}⚠${NC} Proxy environment variables are currently set:" 77 | [ -n "$HTTP_PROXY" ] && echo " HTTP_PROXY=$HTTP_PROXY" 78 | [ -n "$HTTPS_PROXY" ] && echo " HTTPS_PROXY=$HTTPS_PROXY" 79 | [ -n "$NODE_EXTRA_CA_CERTS" ] && echo " NODE_EXTRA_CA_CERTS=$NODE_EXTRA_CA_CERTS" 80 | echo "" 81 | echo " If mitmproxy is running, this is correct." 82 | echo " If not, you may want to unset these variables." 83 | else 84 | echo -e "${GREEN}✓${NC} No proxy environment variables currently set" 85 | echo " This is normal when not running mitmproxy" 86 | fi 87 | echo "" 88 | 89 | # Check 5: mitmproxy ports availability 90 | echo "🔌 Checking port availability..." 91 | if lsof -i :8080 &> /dev/null; then 92 | PORT_8080_PROCESS=$(lsof -i :8080 | tail -n 1 | awk '{print $1}') 93 | echo -e "${YELLOW}⚠${NC} Port 8080 is in use by: $PORT_8080_PROCESS" 94 | echo " This is expected if mitmproxy is running" 95 | else 96 | echo -e "${GREEN}✓${NC} Port 8080 is available" 97 | fi 98 | 99 | if lsof -i :8081 &> /dev/null; then 100 | PORT_8081_PROCESS=$(lsof -i :8081 | tail -n 1 | awk '{print $1}') 101 | echo -e "${YELLOW}⚠${NC} Port 8081 is in use by: $PORT_8081_PROCESS" 102 | echo " This is expected if mitmweb is running" 103 | else 104 | echo -e "${GREEN}✓${NC} Port 8081 is available" 105 | fi 106 | echo "" 107 | 108 | # Check 6: Node.js/npm for TypeScript parser (optional) 109 | echo "📜 Checking TypeScript parser dependencies (optional)..." 110 | if command -v node &> /dev/null; then 111 | NODE_VERSION=$(node --version) 112 | echo -e "${GREEN}✓${NC} Node.js is installed: $NODE_VERSION" 113 | 114 | if command -v npx &> /dev/null; then 115 | echo -e "${GREEN}✓${NC} npx is available (can run TypeScript parser with 'npx tsx')" 116 | else 117 | echo -e "${YELLOW}⚠${NC} npx not found (install npm to use TypeScript parser)" 118 | fi 119 | else 120 | echo -e "${YELLOW}⚠${NC} Node.js not installed (optional - only needed for parse-streamed-response.ts)" 121 | echo " Install with: brew install node" 122 | fi 123 | echo "" 124 | 125 | # Final summary 126 | echo "================================" 127 | if [ "$ALL_CHECKS_PASSED" = true ]; then 128 | echo -e "${GREEN}✓ All critical checks passed!${NC}" 129 | echo "" 130 | echo "You're ready to use cc-trace:" 131 | echo " 1. Start mitmweb: mitmweb --web-port 8081" 132 | echo " 2. Start Claude Code: proxy_claude" 133 | echo " 3. View traffic: http://127.0.0.1:8081" 134 | else 135 | echo -e "${RED}✗ Some checks failed${NC}" 136 | echo "" 137 | echo "Please fix the issues above before using cc-trace." 138 | echo "See SKILL.md for detailed setup instructions." 139 | fi 140 | echo "" 141 | -------------------------------------------------------------------------------- /reference/usage-web-interface.md: -------------------------------------------------------------------------------- 1 | # Web Interface Guide 2 | 3 | This guide covers using mitmweb to capture and inspect Claude Code's API traffic. 4 | 5 | **[← Previous: Shell Configuration](setup-shell-configuration.md)** | **[Next: CLI Interface Guide →](usage-cli-interface.md)** 6 | 7 | --- 8 | 9 | ## Start mitmweb (Web Interface) 10 | 11 | 1. Open a new terminal window 12 | 2. Start mitmweb 13 | 14 | ```bash 15 | mitmweb --web-port 8081 16 | ``` 17 | 18 | Options explained: 19 | - `--web-port 8081`: Web interface port (default is 8081) 20 | - Proxy listens on port 8080 by default 21 | 22 | Optional flags: 23 | 24 | ```bash 25 | # Don't automatically open browser 26 | mitmweb --web-port 8081 --no-web-open-browser 27 | 28 | # Bind to all interfaces (useful for remote access) 29 | mitmweb --web-host 0.0.0.0 --web-port 8081 30 | 31 | # Set a specific listen port for the proxy 32 | mitmweb --listen-port 8080 --web-port 8081 33 | ``` 34 | 35 | 3. Access the web interface 36 | - Automatically opens in your browser, or 37 | - Manually navigate to: http://127.0.0.1:8081 38 | 4. You should see the mitmweb interface with a clean, modern web UI (initially empty with no flows captured yet) 39 | 40 | ### Troubleshooting: mitmweb won't start / Port already in use 41 | 42 | **Error:** `OSError: [Errno 48] Address already in use` 43 | 44 | **Solutions:** 45 | 46 | 1. Check what's using the port: 47 | 48 | ```bash 49 | lsof -i :8080 50 | lsof -i :8081 51 | ``` 52 | 53 | 2. Kill the process: 54 | 55 | ```bash 56 | kill -9 57 | ``` 58 | 59 | 3. Or use different ports: 60 | 61 | ```bash 62 | mitmweb --listen-port 8888 --web-port 8889 63 | ``` 64 | 65 | Remember to update your `proxy_claude` function to use port 8888. 66 | 67 | --- 68 | 69 | ## Start Claude Code with Proxy 70 | 71 | 1. Open a new terminal window (keep mitmweb running in the first) 72 | 2. Run Claude Code through the proxy 73 | 74 | ```bash 75 | proxy_claude 76 | ``` 77 | 78 | 3. You should see: 79 | 80 | ``` 81 | 🔍 Proxy configured for mitmproxy (http://127.0.0.1:8080) 82 | 📜 Using CA cert: /Users/yourname/.mitmproxy/mitmproxy-ca-cert.pem 83 | 🚀 Starting Claude Code... 84 | ``` 85 | 86 | Claude Code starts normally 87 | 88 | --- 89 | 90 | ## Verify Traffic Capture 91 | 92 | 1. Ask Claude Code a question 93 | - Type any prompt in Claude Code 94 | - Wait for a response 95 | 96 | 2. Check mitmweb interface 97 | - Switch to your browser with mitmweb 98 | - You should see requests to api.anthropic.com 99 | - Each request appears as a row in the flow list 100 | 101 | 3. If no traffic appears, see Troubleshooting section below 102 | 103 | ### Troubleshooting: No traffic appears in mitmweb 104 | 105 | **Solutions:** 106 | 107 | 1. Verify mitmweb is running: 108 | 109 | ```bash 110 | # Check if proxy port is listening 111 | lsof -i :8080 112 | ``` 113 | 114 | 2. Check environment variables in Claude Code terminal: 115 | 116 | ```bash 117 | echo $HTTP_PROXY 118 | echo $HTTPS_PROXY 119 | echo $NODE_EXTRA_CA_CERTS 120 | ``` 121 | 122 | All should be set correctly. 123 | 124 | 3. Test the proxy with curl: 125 | 126 | ```bash 127 | curl -x http://127.0.0.1:8080 http://example.com 128 | ``` 129 | 130 | This should appear in mitmweb. 131 | 132 | 4. Ensure you're using `proxy_claude` function: 133 | 134 | ```bash 135 | # Verify environment in the Claude terminal 136 | env | grep -i proxy 137 | ``` 138 | 139 | --- 140 | 141 | ## Inspect API Requests and Responses 142 | 143 | ### Understanding the mitmweb Interface 144 | 145 | **Main View:** 146 | - Flow List (left): All captured HTTP requests 147 | - Flow Detail (right): Selected request/response details 148 | 149 | ### Inspecting a Request 150 | 151 | 1. Click on any api.anthropic.com request 152 | 2. View Request Details 153 | - Click Request tab 154 | - See: Headers (Authentication, content-type, etc.), Content (the actual JSON payload sent to Claude), Query (URL parameters if any) 155 | 3. View Response Details 156 | - Click Response tab 157 | - See: Status (HTTP status code), Headers (Response metadata), Content (Claude's response, may be streamed) 158 | 4. Inspect the JSON payload 159 | - Look for: `system` (System prompts), `messages` (Conversation history), `tools` (Available tool definitions), `model` (Which Claude model is being used), `max_tokens` (Token limits) 160 | 161 | ### Filtering Requests 162 | 163 | 1. Use the filter bar at the top of flow list 164 | 165 | Common filters: 166 | 167 | ``` 168 | # Show only Anthropic API requests 169 | ~d api.anthropic.com 170 | 171 | # Show only POST requests 172 | ~m POST 173 | 174 | # Show requests with "messages" in URL 175 | ~u messages 176 | 177 | # Combine filters 178 | ~d api.anthropic.com & ~m POST 179 | ``` 180 | 181 | Type directly in the filter box and press Enter to apply. 182 | 183 | ### Useful Features 184 | 185 | - **Search:** `Cmd+F` to search within requests/responses 186 | - **Export:** Right-click → Export for saving flows 187 | - **Clear:** Click the trash icon to clear all flows 188 | - **Replay:** Right-click → Replay to resend a request 189 | 190 | --- 191 | 192 | ## Quick Reference: Common mitmweb Commands 193 | 194 | ```bash 195 | # Start mitmweb (web interface) 196 | mitmweb --web-port 8081 197 | 198 | # Start with filtering 199 | mitmweb --set flow_filter='~d api.anthropic.com' 200 | 201 | # Start without opening browser 202 | mitmweb --no-web-open-browser 203 | 204 | # Start on custom ports 205 | mitmweb --listen-port 9090 --web-port 9091 206 | 207 | # Start with a script 208 | mitmweb -s my_script.py 209 | 210 | # Replay saved flows 211 | mitmweb -r saved-flows.mitm 212 | ``` 213 | 214 | --- 215 | 216 | **[← Previous: Shell Configuration](setup-shell-configuration.md)** | **[Next: CLI Interface Guide →](usage-cli-interface.md)** 217 | -------------------------------------------------------------------------------- /scripts/parse-streamed-response.ts: -------------------------------------------------------------------------------- 1 | // To read a streamed message from Anthropic, you can use this script with 2 | // pbpaste | yarn tsx ./scripts/parse-streamed-response.ts 3 | 4 | interface StreamDelta { 5 | type: string 6 | text?: string 7 | partial_json?: string 8 | } 9 | 10 | interface InputJsonDelta { 11 | type: "input_json_delta" 12 | partial_json: string 13 | } 14 | 15 | interface StreamData { 16 | type: string 17 | delta: StreamDelta 18 | index?: number 19 | } 20 | 21 | interface ContentBlock { 22 | type: string 23 | id?: string 24 | name?: string 25 | input?: unknown 26 | } 27 | 28 | interface ContentBlockStart { 29 | type: string 30 | index: number 31 | content_block: ContentBlock 32 | } 33 | 34 | interface AnthropicToolCall { 35 | name?: string 36 | parameters?: unknown 37 | raw?: string 38 | } 39 | 40 | function extractTextFromStream(inputText: string): { text: string; tools: AnthropicToolCall[] } { 41 | // Split the input into lines 42 | const lines = inputText.trim().split("\n") 43 | 44 | // Initialize variables 45 | let currentText = "" 46 | const tools: AnthropicToolCall[] = [] 47 | const toolDataByIndex: Map = new Map() 48 | 49 | // Process each line 50 | for (let i = 0; i < lines.length; i++) { 51 | const line = lines[i] 52 | 53 | // Handle content_block_start events for tool_use 54 | if (line.startsWith("event: content_block_start")) { 55 | const dataLine = lines[i + 1] 56 | if (dataLine && dataLine.startsWith("data:")) { 57 | try { 58 | const jsonStr = dataLine.slice(5).trim() 59 | const data = JSON.parse(jsonStr) as ContentBlockStart 60 | 61 | if (data.content_block?.type === "tool_use") { 62 | const toolName = data.content_block.name || "" 63 | const index = data.index 64 | if (toolName && index !== undefined) { 65 | toolDataByIndex.set(index, { name: toolName, json: "" }) 66 | } 67 | } 68 | } catch { 69 | // Skip invalid JSON 70 | continue 71 | } 72 | } 73 | } 74 | 75 | // Handle content_block_delta events 76 | else if (line.startsWith("event: content_block_delta")) { 77 | const dataLine = lines[i + 1] 78 | if (dataLine && dataLine.startsWith("data:")) { 79 | try { 80 | const jsonStr = dataLine.slice(5).trim() 81 | const data = JSON.parse(jsonStr) as StreamData 82 | 83 | // Extract text from text_delta 84 | if (data.delta?.text) { 85 | currentText += data.delta.text 86 | } 87 | // Extract tool parameters from partial_json (old format) or input_json_delta (new format) 88 | else if ( 89 | data.delta?.partial_json || 90 | (data.delta && "partial_json" in data.delta && data.delta.type === "input_json_delta") 91 | ) { 92 | const partialJson = data.delta.partial_json || (data.delta as InputJsonDelta).partial_json 93 | const index = data.index 94 | 95 | if (index !== undefined) { 96 | const toolData = toolDataByIndex.get(index) 97 | if (toolData) { 98 | // New format: we have tool name from content_block_start, or old format continuation 99 | toolData.json += partialJson 100 | } else { 101 | // Old format: create new entry for this index 102 | const existingData = { name: "", json: partialJson } 103 | toolDataByIndex.set(index, existingData) 104 | } 105 | } 106 | } 107 | } catch { 108 | // Skip invalid JSON 109 | continue 110 | } 111 | } 112 | } 113 | 114 | // Handle content_block_stop events to finalize tools 115 | else if (line.startsWith("event: content_block_stop")) { 116 | const dataLine = lines[i + 1] 117 | if (dataLine && dataLine.startsWith("data:")) { 118 | try { 119 | const jsonStr = dataLine.slice(5).trim() 120 | const data = JSON.parse(jsonStr) 121 | const index = data.index 122 | 123 | if (index !== undefined) { 124 | const toolData = toolDataByIndex.get(index) 125 | if (toolData && (toolData.name || toolData.json.trim())) { 126 | try { 127 | if (toolData.name && toolData.json.trim()) { 128 | // New format: we have tool name from content_block_start and parameters from input_json_delta 129 | const parsedParameters = JSON.parse(toolData.json) 130 | tools.push({ 131 | name: toolData.name, 132 | parameters: parsedParameters, 133 | }) 134 | } else if (toolData.json.trim()) { 135 | // Old format: everything is in partial_json 136 | const parsedTool = JSON.parse(toolData.json) 137 | tools.push({ 138 | name: parsedTool.name, 139 | parameters: parsedTool.parameters, 140 | }) 141 | } 142 | } catch { 143 | // If tool JSON is malformed, return the raw string 144 | tools.push({ 145 | raw: toolData.json, 146 | }) 147 | } 148 | // Remove processed tool data 149 | toolDataByIndex.delete(index) 150 | } 151 | } 152 | } catch { 153 | // Skip invalid JSON 154 | continue 155 | } 156 | } 157 | } 158 | } 159 | 160 | // Handle any remaining tools that didn't have content_block_stop events 161 | for (const [, toolData] of toolDataByIndex) { 162 | if (toolData.name || toolData.json.trim()) { 163 | try { 164 | if (toolData.name && toolData.json.trim()) { 165 | // New format: we have tool name from content_block_start and parameters from input_json_delta 166 | const parsedParameters = JSON.parse(toolData.json) 167 | tools.push({ 168 | name: toolData.name, 169 | parameters: parsedParameters, 170 | }) 171 | } else if (toolData.json.trim()) { 172 | // Old format: everything is in partial_json 173 | const parsedTool = JSON.parse(toolData.json) 174 | tools.push({ 175 | name: parsedTool.name, 176 | parameters: parsedTool.parameters, 177 | }) 178 | } 179 | } catch { 180 | // If tool JSON is malformed, return the raw string 181 | tools.push({ 182 | raw: toolData.json, 183 | }) 184 | } 185 | } 186 | } 187 | 188 | return { text: currentText, tools } 189 | } 190 | 191 | // Export the function for testing 192 | export { extractTextFromStream } 193 | 194 | // Read from stdin if no file is provided 195 | async function main() { 196 | let inputText: string 197 | 198 | if (process.argv.length > 2) { 199 | // Read from file 200 | const fs = await import("fs/promises") 201 | inputText = await fs.readFile(process.argv[2], "utf-8") 202 | } else { 203 | // Read from stdin 204 | inputText = await new Promise((resolve) => { 205 | let data = "" 206 | process.stdin.on("data", (chunk) => { 207 | data += chunk 208 | }) 209 | process.stdin.on("end", () => { 210 | resolve(data) 211 | }) 212 | }) 213 | } 214 | 215 | // Extract and print the text 216 | const extractedText = extractTextFromStream(inputText) 217 | console.log(JSON.stringify(extractedText, null, 2)) 218 | } 219 | 220 | main().catch(console.error) 221 | -------------------------------------------------------------------------------- /reference/advanced-features-security.md: -------------------------------------------------------------------------------- 1 | # Advanced Features & Security 2 | 3 | This guide covers advanced mitmproxy features and important security considerations. 4 | 5 | **[← Previous: Daily Workflow & Tips](workflow-daily-tips.md)** | **[Back to Overview](SKILL.md)** 6 | 7 | --- 8 | 9 | ## Advanced Features 10 | 11 | ### Save Flows for Later Analysis 12 | 13 | #### Export from Web Interface 14 | 15 | 1. Export all flows 16 | - In mitmweb, click the ≡ menu 17 | - Select File → Export 18 | - Choose format (mitmproxy, HAR, etc.) 19 | 20 | 2. Export specific flows 21 | - Right-click on a flow 22 | - Select Export 23 | - Save to file 24 | 25 | #### Replay Flows 26 | 27 | ```bash 28 | # Replay with mitmproxy CLI 29 | mitmproxy -r saved-flows.mitm 30 | 31 | # Replay with mitmweb 32 | mitmweb -r saved-flows.mitm 33 | 34 | # Replay with mitmdump 35 | mitmdump -r saved-flows.mitm 36 | ``` 37 | 38 | --- 39 | 40 | ### Python Scripting 41 | 42 | Create custom scripts to modify traffic on-the-fly. 43 | 44 | #### Example: Log Requests 45 | 46 | Create `~/claude-analysis/log_requests.py`: 47 | 48 | ```python 49 | def request(flow): 50 | if "api.anthropic.com" in flow.request.pretty_url: 51 | print(f"→ {flow.request.method} {flow.request.path}") 52 | 53 | def response(flow): 54 | if "api.anthropic.com" in flow.request.pretty_url: 55 | print(f"← {flow.response.status_code}") 56 | ``` 57 | 58 | Run with: 59 | 60 | ```bash 61 | mitmweb -s ~/claude-analysis/log_requests.py 62 | ``` 63 | 64 | #### Example: Extract Token Usage 65 | 66 | Create `~/claude-analysis/extract_tokens.py`: 67 | 68 | ```python 69 | import json 70 | 71 | def response(flow): 72 | if "api.anthropic.com" in flow.request.pretty_url: 73 | try: 74 | # Parse response body 75 | content = flow.response.text 76 | if "usage" in content: 77 | data = json.loads(content) 78 | if "usage" in data: 79 | usage = data["usage"] 80 | print(f"Tokens - Input: {usage.get('input_tokens', 0)}, Output: {usage.get('output_tokens', 0)}") 81 | except: 82 | pass 83 | ``` 84 | 85 | #### Example: Modify Requests 86 | 87 | ```python 88 | def request(flow): 89 | if "api.anthropic.com" in flow.request.pretty_url: 90 | # Example: Add custom headers 91 | flow.request.headers["X-Custom-Header"] = "value" 92 | 93 | # Example: Modify request body 94 | try: 95 | data = json.loads(flow.request.text) 96 | # Modify data as needed 97 | flow.request.text = json.dumps(data) 98 | except: 99 | pass 100 | ``` 101 | 102 | **Note:** Be careful when modifying requests - this can break functionality! 103 | 104 | --- 105 | 106 | ### Filter Specific API Endpoints 107 | 108 | #### Using Command-Line Filters 109 | 110 | ```bash 111 | # Only show /messages endpoint 112 | mitmweb --set flow_filter='~d api.anthropic.com & ~u /messages' 113 | 114 | # Show only successful responses 115 | mitmweb --set flow_filter='~c 200' 116 | 117 | # Show only large responses (>10000 bytes) 118 | mitmweb --set flow_filter='~bs 10000' 119 | ``` 120 | 121 | #### Filter Syntax Reference 122 | 123 | ``` 124 | ~d domain # Domain filter 125 | ~u url # URL filter 126 | ~m method # Method (GET, POST, etc.) 127 | ~c code # Status code 128 | ~bs size # Response body size 129 | ~bq size # Request body size 130 | ~h header # Header filter 131 | ~t "text" # Body text search 132 | & # AND operator 133 | | # OR operator 134 | ! # NOT operator 135 | ``` 136 | 137 | --- 138 | 139 | ## Security Notes 140 | 141 | ### Important Security Considerations 142 | 143 | **Local use only:** The proxy setup in this guide is for local debugging only 144 | 145 | **Certificate trust:** You're trusting mitmproxy to intercept HTTPS traffic 146 | - This gives mitmproxy access to decrypt all HTTPS traffic 147 | - Only install the certificate on machines you control 148 | - Remove it when you're done debugging 149 | 150 | **Sensitive data:** Be careful with API keys and tokens in captured traffic 151 | - Captured traffic contains your API keys 152 | - Don't share raw exports without redacting sensitive data 153 | - Store captured flows securely 154 | 155 | **Production warning:** Never use this setup in production environments 156 | - The `NODE_TLS_REJECT_UNAUTHORIZED=0` setting disables security 157 | - Only use for local development and debugging 158 | 159 | ### Clean Up After Debugging 160 | 161 | #### Remove the Certificate 162 | 163 | When you're done debugging, remove the certificate: 164 | 165 | ```bash 166 | sudo security delete-certificate -c mitmproxy /Library/Keychains/System.keychain 167 | ``` 168 | 169 | Verify removal: 170 | 171 | ```bash 172 | security find-certificate -c mitmproxy -a 173 | ``` 174 | 175 | Should return no results. 176 | 177 | #### Clear Proxy Settings 178 | 179 | Clear environment variables when not debugging: 180 | 181 | ```bash 182 | unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NODE_EXTRA_CA_CERTS NODE_TLS_REJECT_UNAUTHORIZED 183 | ``` 184 | 185 | Add this to a function for easy cleanup: 186 | 187 | ```bash 188 | # Add to ~/.zshrc or ~/.bashrc 189 | unproxy() { 190 | unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NODE_EXTRA_CA_CERTS NODE_TLS_REJECT_UNAUTHORIZED 191 | echo "🚫 Proxy environment variables cleared" 192 | } 193 | ``` 194 | 195 | #### Delete Saved Flows 196 | 197 | If you've saved flows with sensitive data: 198 | 199 | ```bash 200 | # Find and remove flow files 201 | find ~/claude-analysis -name "*.mitm" -delete 202 | find ~/claude-analysis -name "*.har" -delete 203 | ``` 204 | 205 | --- 206 | 207 | ## Quick Reference: Common Commands 208 | 209 | ### Starting mitmproxy 210 | 211 | ```bash 212 | # Start mitmweb (web interface) 213 | mitmweb --web-port 8081 214 | 215 | # Start with filtering 216 | mitmweb --set flow_filter='~d api.anthropic.com' 217 | 218 | # Start without opening browser 219 | mitmweb --no-web-open-browser 220 | 221 | # Start on custom ports 222 | mitmweb --listen-port 9090 --web-port 9091 223 | 224 | # Start with a script 225 | mitmweb -s my_script.py 226 | 227 | # Start mitmproxy (CLI) 228 | mitmproxy 229 | 230 | # Start mitmdump (headless, logging) 231 | mitmdump -w output.mitm 232 | 233 | # Replay saved flows 234 | mitmweb -r saved-flows.mitm 235 | ``` 236 | 237 | ### Certificate Management 238 | 239 | ```bash 240 | # Install certificate (macOS) 241 | sudo security add-trusted-cert -d -p ssl -p basic \ 242 | -k /Library/Keychains/System.keychain \ 243 | ~/.mitmproxy/mitmproxy-ca-cert.pem 244 | 245 | # Verify certificate is trusted 246 | security find-certificate -c mitmproxy -a 247 | 248 | # Remove certificate 249 | sudo security delete-certificate -c mitmproxy /Library/Keychains/System.keychain 250 | ``` 251 | 252 | --- 253 | 254 | ## Additional Resources 255 | 256 | ### Official Documentation 257 | - Official Documentation: https://docs.mitmproxy.org/ 258 | - Installation Guide: https://docs.mitmproxy.org/stable/overview/installation/ 259 | - Certificate Setup: https://docs.mitmproxy.org/stable/concepts/certificates/ 260 | - mitmweb Tutorial: https://docs.mitmproxy.org/stable/mitmproxytutorial/userinterface/ 261 | - Scripting Guide: https://docs.mitmproxy.org/stable/addons-overview/ 262 | 263 | ### Community & Support 264 | - GitHub Repository: https://github.com/mitmproxy/mitmproxy 265 | - Community Discord: https://discord.gg/mitmproxy 266 | 267 | ### Related Projects 268 | - System Prompts Repo: https://github.com/gsabran/claude-code-system-prompts 269 | 270 | --- 271 | 272 | ## Conclusion 273 | 274 | You're now equipped with everything you need to intercept, analyze, and understand Claude Code's API requests using mitmproxy! This free, open-source setup gives you deep insights into how AI coding assistants work under the hood. 275 | 276 | Remember to: 277 | - Use this only for debugging and learning 278 | - Remove certificates when done 279 | - Keep captured data secure 280 | - Never use in production 281 | 282 | Happy debugging! 283 | 284 | --- 285 | 286 | **[← Previous: Daily Workflow & Tips](workflow-daily-tips.md)** | **[Back to Overview](SKILL.md)** 287 | -------------------------------------------------------------------------------- /reference/usage-programmatic-access.md: -------------------------------------------------------------------------------- 1 | # Programmatic Access to Captured Traffic 2 | 3 | This guide explains how to programmatically analyze captured API traffic while mitmweb or mitmproxy is running, enabling automated extraction of system prompts, slash command expansions, token usage statistics, and other API data. 4 | 5 | ## Overview 6 | 7 | mitmproxy supports multiple interaction modes: 8 | 9 | 1. **Web UI Only** - Manual inspection via browser (http://localhost:8081) 10 | 2. **Programmatic Access** - Automated analysis using Python scripts and CLI tools 11 | 3. **Hybrid Mode** - Both web UI and programmatic access simultaneously 12 | 13 | ## Enabling Programmatic Access 14 | 15 | To enable programmatic access while using mitmweb, start it with flow saving: 16 | 17 | ```bash 18 | mitmweb --web-port 8081 \ 19 | --set flow_filter='~d api.anthropic.com' \ 20 | --save-stream-file ~/claude-flows.mitm 21 | ``` 22 | 23 | **Key differences:** 24 | 25 | | Mode | Command | Web UI | Programmatic | Use Case | 26 | |------|---------|--------|--------------|----------| 27 | | Web only | `mitmweb --web-port 8081` | ✅ | ❌ | Manual exploration | 28 | | Programmatic | `mitmdump -w flows.mitm` | ❌ | ✅ | Headless automation | 29 | | Hybrid | `mitmweb --save-stream-file flows.mitm` | ✅ | ✅ | Interactive + automation | 30 | 31 | ## Bundled Analysis Scripts 32 | 33 | ### 1. Extract Slash Command Expansions 34 | 35 | **Script**: `~/.claude/skills/cc-trace/scripts/extract-slash-commands.py` 36 | 37 | Shows how slash commands are expanded with arguments before being sent to the API. 38 | 39 | **Usage**: 40 | ```bash 41 | mitmdump -r ~/claude-flows.mitm -s ~/.claude/skills/cc-trace/scripts/extract-slash-commands.py 42 | ``` 43 | 44 | **Output**: 45 | ``` 46 | ================================================================================ 47 | USER MESSAGE #1 48 | ================================================================================ 49 | Review the JSON file at /Users/alex/.../extraction.json and process files in /Users/alex/.../output/... 50 | ================================================================================ 51 | ``` 52 | 53 | **What it does**: 54 | - Parses all flows in the capture file 55 | - Extracts user messages from the `messages` array 56 | - Displays the complete expanded prompt text 57 | - Handles both string and array content formats 58 | 59 | ### 2. Show Last User Prompt 60 | 61 | **Script**: `~/.claude/skills/cc-trace/scripts/show-last-prompt.sh` 62 | 63 | Quickly displays the most recent prompt sent to the API. 64 | 65 | **Usage**: 66 | ```bash 67 | ~/.claude/skills/cc-trace/scripts/show-last-prompt.sh 68 | # Or specify a different flow file: 69 | ~/.claude/skills/cc-trace/scripts/show-last-prompt.sh /path/to/flows.mitm 70 | ``` 71 | 72 | **Output**: 73 | ``` 74 | Extracting last user prompt from: /Users/alex/claude-flows.mitm 75 | ================================================================ 76 | Review the JSON file at /Users/alex/.../extraction.json... 77 | ``` 78 | 79 | **Use cases**: 80 | - Debug slash command argument substitution 81 | - Verify what prompt was actually sent 82 | - Compare expected vs actual input 83 | 84 | ### 3. Parse Streamed Responses 85 | 86 | **Script**: `~/.claude/skills/cc-trace/scripts/parse-streamed-response.ts` 87 | 88 | Parses Anthropic's Server-Sent Events (SSE) streaming format into readable output. 89 | 90 | **Usage**: 91 | ```bash 92 | # Copy response from mitmweb, then: 93 | pbpaste | npx tsx ~/.claude/skills/cc-trace/scripts/parse-streamed-response.ts 94 | ``` 95 | 96 | **Output**: Extracted text content and tool calls from the stream. 97 | 98 | ## Custom Analysis with mitmdump 99 | 100 | ### Reading Saved Flows 101 | 102 | ```bash 103 | # View all flows 104 | mitmdump -r ~/claude-flows.mitm 105 | 106 | # View with detailed info 107 | mitmdump -r ~/claude-flows.mitm --flow-detail 2 108 | 109 | # Filter specific flows 110 | mitmdump -r ~/claude-flows.mitm -n "~d api.anthropic.com & ~m POST" 111 | ``` 112 | 113 | ### Writing Custom Python Scripts 114 | 115 | Create a Python script that runs on each flow: 116 | 117 | **Example**: Extract token usage statistics 118 | 119 | ```python 120 | # save as: token-stats.py 121 | import json 122 | from mitmproxy import http 123 | 124 | total_input = 0 125 | total_output = 0 126 | 127 | def response(flow: http.HTTPFlow): 128 | global total_input, total_output 129 | 130 | if "api.anthropic.com" not in flow.request.pretty_url: 131 | return 132 | 133 | try: 134 | data = json.loads(flow.response.content.decode('utf-8')) 135 | usage = data.get('usage', {}) 136 | 137 | input_tokens = usage.get('input_tokens', 0) 138 | output_tokens = usage.get('output_tokens', 0) 139 | 140 | total_input += input_tokens 141 | total_output += output_tokens 142 | 143 | print(f"Request: {input_tokens} in, {output_tokens} out") 144 | except: 145 | pass 146 | 147 | def done(): 148 | print(f"\nTotal: {total_input} input tokens, {total_output} output tokens") 149 | ``` 150 | 151 | **Run it**: 152 | ```bash 153 | mitmdump -r ~/claude-flows.mitm -s token-stats.py 154 | ``` 155 | 156 | ### Extracting System Prompts 157 | 158 | ```python 159 | # save as: extract-system-prompt.py 160 | import json 161 | from mitmproxy import http 162 | 163 | def response(flow: http.HTTPFlow): 164 | if "api.anthropic.com" not in flow.request.pretty_url: 165 | return 166 | 167 | try: 168 | data = json.loads(flow.request.content.decode('utf-8')) 169 | system = data.get('system', '') 170 | 171 | if system: 172 | print("="*80) 173 | print("SYSTEM PROMPT") 174 | print("="*80) 175 | print(system) 176 | print("="*80) 177 | except: 178 | pass 179 | ``` 180 | 181 | ### Extracting Tool Definitions 182 | 183 | ```python 184 | # save as: extract-tools.py 185 | import json 186 | from mitmproxy import http 187 | 188 | seen_tools = set() 189 | 190 | def response(flow: http.HTTPFlow): 191 | if "api.anthropic.com" not in flow.request.pretty_url: 192 | return 193 | 194 | try: 195 | data = json.loads(flow.request.content.decode('utf-8')) 196 | tools = data.get('tools', []) 197 | 198 | for tool in tools: 199 | name = tool.get('name') 200 | if name and name not in seen_tools: 201 | seen_tools.add(name) 202 | print(f"\nTool: {name}") 203 | print(f"Description: {tool.get('description', 'N/A')}") 204 | except: 205 | pass 206 | ``` 207 | 208 | ## Real-Time Analysis 209 | 210 | When using `--save-stream-file`, flows are written as they're captured, enabling real-time analysis: 211 | 212 | ```bash 213 | # Terminal 1: Start mitmweb with flow saving 214 | mitmweb --web-port 8081 --save-stream-file ~/claude-flows.mitm 215 | 216 | # Terminal 2: Run Claude Code with proxy 217 | proxy_claude 218 | 219 | # Terminal 3: Monitor flows in real-time 220 | watch -n 1 'mitmdump -r ~/claude-flows.mitm -s token-stats.py 2>/dev/null | tail -5' 221 | ``` 222 | 223 | ## Exporting Flows from Web UI 224 | 225 | If you started mitmweb without `--save-stream-file`, you can export manually: 226 | 227 | 1. Open mitmweb: http://localhost:8081 228 | 2. Click "≡" menu (top right) 229 | 3. File → Save 230 | 4. Save as `~/captured-flows.mitm` 231 | 5. Analyze: `mitmdump -r ~/captured-flows.mitm -s script.py` 232 | 233 | **Export formats**: 234 | - `.mitm` - Native mitmproxy format (recommended) 235 | - `.har` - HTTP Archive format (for compatibility) 236 | 237 | ## Common Analysis Tasks 238 | 239 | ### Task: Find slash command expansion 240 | 241 | ```bash 242 | # Use the bundled script 243 | ~/.claude/skills/cc-trace/scripts/show-last-prompt.sh 244 | ``` 245 | 246 | ### Task: Compare token usage across requests 247 | 248 | ```bash 249 | mitmdump -r ~/claude-flows.mitm -s token-stats.py 250 | ``` 251 | 252 | ### Task: Extract all tool calls 253 | 254 | ```python 255 | # save as: extract-tool-calls.py 256 | import json 257 | from mitmproxy import http 258 | 259 | def response(flow: http.HTTPFlow): 260 | if "api.anthropic.com" not in flow.request.pretty_url: 261 | return 262 | 263 | try: 264 | data = json.loads(flow.response.content.decode('utf-8')) 265 | 266 | # Handle streaming response 267 | if flow.response.content.startswith(b'event:'): 268 | # This is SSE format - use parse-streamed-response.ts instead 269 | return 270 | 271 | content = data.get('content', []) 272 | for block in content: 273 | if block.get('type') == 'tool_use': 274 | print(f"\nTool: {block.get('name')}") 275 | print(f"Input: {json.dumps(block.get('input', {}), indent=2)}") 276 | except: 277 | pass 278 | ``` 279 | 280 | ### Task: Search for specific patterns 281 | 282 | ```bash 283 | # Find all requests mentioning "slash command" 284 | mitmdump -r ~/claude-flows.mitm | grep -i "slash command" 285 | 286 | # Extract requests with large token counts 287 | mitmdump -r ~/claude-flows.mitm -s - <<'PYTHON' 288 | import json 289 | from mitmproxy import http 290 | 291 | def response(flow): 292 | try: 293 | data = json.loads(flow.response.content) 294 | tokens = data.get('usage', {}).get('input_tokens', 0) 295 | if tokens > 10000: 296 | print(f"Large request: {tokens} tokens") 297 | except: 298 | pass 299 | PYTHON 300 | ``` 301 | 302 | ## API Access via REST (Advanced) 303 | 304 | Modern mitmweb uses WebSocket-based APIs that are not easily accessible via curl. For REST-like programmatic access, use: 305 | 306 | 1. **Flow saving** (recommended): `--save-stream-file` + `mitmdump` 307 | 2. **Flow export** (manual): Export from web UI, then analyze 308 | 3. **Custom addon**: Write a Python addon that exposes a REST API 309 | 310 | ## Troubleshooting 311 | 312 | ### Issue: "No such file" when running mitmdump 313 | 314 | **Cause**: Flow file doesn't exist yet or wrong path 315 | 316 | **Solution**: 317 | ```bash 318 | # Check if file exists 319 | ls -lh ~/claude-flows.mitm 320 | 321 | # Verify flows are being saved 322 | lsof | grep claude-flows.mitm 323 | ``` 324 | 325 | ### Issue: Scripts show no output 326 | 327 | **Cause**: No flows match the filter or script has errors 328 | 329 | **Solution**: 330 | ```bash 331 | # Check if flows were captured 332 | mitmdump -r ~/claude-flows.mitm --flow-detail 0 333 | 334 | # Test script with verbose output 335 | mitmdump -r ~/claude-flows.mitm -s script.py --set termlog_verbosity=debug 336 | ``` 337 | 338 | ### Issue: Permission denied when running scripts 339 | 340 | **Cause**: Scripts not executable 341 | 342 | **Solution**: 343 | ```bash 344 | chmod +x ~/.claude/skills/cc-trace/scripts/*.sh 345 | ``` 346 | 347 | ## Best Practices 348 | 349 | 1. **Start with flow saving enabled** - Always use `--save-stream-file` for hybrid mode 350 | 2. **Use bundled scripts first** - Leverage pre-built analysis scripts before writing custom ones 351 | 3. **Filter early** - Use `--set flow_filter='~d api.anthropic.com'` to reduce noise 352 | 4. **Back up important captures** - Flow files can be large; compress or archive when done 353 | 5. **Clean up sensitive data** - Delete flow files containing API keys when analysis is complete 354 | 355 | ## Security Considerations 356 | 357 | - Flow files contain **complete API requests** including API keys and sensitive data 358 | - Store flow files securely (not in git repositories or public locations) 359 | - Delete flow files after analysis is complete 360 | - Never share flow files without sanitizing sensitive information 361 | 362 | ## Summary 363 | 364 | **For interactive exploration**: Use mitmweb web UI only 365 | **For automated analysis**: Use mitmdump or mitmweb with `--save-stream-file` 366 | **For both**: Start mitmweb with `--save-stream-file ~/claude-flows.mitm` 367 | 368 | The hybrid mode enables: 369 | - ✅ Visual inspection in browser 370 | - ✅ Automated analysis with Python scripts 371 | - ✅ Real-time monitoring and alerting 372 | - ✅ Batch processing of captured traffic 373 | -------------------------------------------------------------------------------- /SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: cc-trace 3 | description: Interactive assistant for intercepting, debugging, analyzing and reviewing Claude Code API requests using mitmproxy. Guides setup, certificate configuration, and active traffic inspection via web or CLI interface. Supports learning Claude Code internals, debugging issues, and optimizing API usage. 4 | allowed-tools: Bash, Read, Write, Edit, AskUserQuestion 5 | --- 6 | 7 | # CC-Trace: Claude Code API Request Interception Assistant 8 | 9 | ## Task Context 10 | 11 | This skill transforms Claude into an interactive assistant for capturing and analyzing Claude Code's API communications using mitmproxy, a free, open-source HTTPS proxy tool. The skill supports three equally important use cases: 12 | 13 | 1. **Learning & Exploration** - Understanding Claude Code's internal workings, system prompts, tool definitions, and request structure 14 | 2. **Debugging & Troubleshooting** - Diagnosing unexpected behavior, failed tool calls, or API errors by inspecting actual traffic 15 | 3. **Optimization & Analysis** - Analyzing token consumption patterns, identifying inefficiencies, and optimizing API usage 16 | 17 | **Target users**: Technical professionals who understand software development and command-line interfaces but may be unfamiliar with HTTPS interception, certificate authorities, or proxy configuration. 18 | 19 | **Operating mode**: Interactive assistant that: 20 | - Assesses user's current setup state (fresh start, partial configuration, or fully operational) 21 | - Guides through each step of setup with verification 22 | - Helps troubleshoot errors with diagnostic commands 23 | - Teaches traffic inspection and analysis techniques 24 | - Adapts assistance level based on user's experience 25 | 26 | ## Skill Capabilities 27 | 28 | This skill provides assistance across three domains: 29 | 30 | **For setup:** 31 | - Guide through installation step-by-step (mitmproxy, certificate, shell configuration) 32 | - Troubleshoot certificate or proxy configuration issues 33 | - Verify setup is correct with diagnostic commands 34 | - Explain errors encountered during setup 35 | - Support macOS, Linux, and Windows platforms 36 | 37 | **For usage:** 38 | - Start and configure mitmproxy/mitmweb with appropriate flags 39 | - Filter and find specific requests in captured traffic 40 | - Explain captured traffic structure and content 41 | - Export flows for later analysis or replay 42 | - Write custom Python scripts for traffic logging and modification 43 | 44 | **For analysis:** 45 | - Interpret system prompts and tool definitions in requests 46 | - Explain token usage patterns and optimization opportunities 47 | - Analyze tool call sequences (parallel vs sequential, dependencies) 48 | - Parse and understand Server-Sent Events streaming responses 49 | - Compare different API interactions to identify patterns 50 | 51 | ## Prerequisites 52 | 53 | Before using this skill, verify: 54 | - **Operating system**: macOS, Linux, or Windows (mitmproxy is cross-platform) 55 | - **Claude Code CLI**: Already installed and functional 56 | - **Package manager**: Homebrew (macOS), apt/pip (Linux), or ability to download installers (Windows) 57 | - **Terminal access**: Basic command-line knowledge for running commands and editing config files 58 | - **Permissions**: Ability to install certificates and modify system keychain (may require sudo/administrator) 59 | 60 | ## Tone & Communication Style 61 | 62 | Communicate in clear, objective, technical language that: 63 | - Uses imperative/infinitive form (verb-first instructions) 64 | - Explains technical concepts without condescension 65 | - Provides rationale for security-sensitive operations 66 | - Balances brevity with necessary detail 67 | - Avoids jargon when simpler terms suffice 68 | - Includes "why" along with "how" for complex steps 69 | 70 | **Example good tone**: "To intercept HTTPS traffic, install mitmproxy's certificate authority into the system keychain. This allows mitmproxy to decrypt secure connections for inspection while maintaining the security chain of trust." 71 | 72 | **Avoid**: "You need to trust the cert or it won't work" or overly verbose academic explanations. 73 | 74 | ### Question Asking Protocol 75 | 76 | **CRITICAL**: When you need to ask the user questions, you MUST use the AskUserQuestion tool rather than asking in plain text. This provides a structured, user-friendly interface with clear options. 77 | 78 | **When to use AskUserQuestion**: 79 | - Determining user's current setup state (fresh start, troubleshooting, active usage) 80 | - Identifying platform/operating system 81 | - Assessing experience level 82 | - Clarifying which path to take in setup or troubleshooting 83 | - Confirming command output or verification results 84 | - Choosing between multiple diagnostic approaches 85 | 86 | **How to structure questions with AskUserQuestion**: 87 | - Keep questions focused and specific (1-4 questions per call) 88 | - Provide 2-4 clear, mutually exclusive options 89 | - Include descriptive explanations for each option 90 | - Use short headers (max 12 chars) for quick identification 91 | - Remember users can always select "Other" for custom input 92 | 93 | **Example - Initial assessment**: 94 | ``` 95 | Question: "What is your current situation with cc-trace?" 96 | Header: "Setup state" 97 | Options: 98 | - "First time setup" - "I haven't installed or configured cc-trace yet" 99 | - "Troubleshooting" - "I have cc-trace set up but encountering issues" 100 | - "Ready to use" - "Everything is configured, I want to start capturing traffic" 101 | - "Analyzing" - "I already have captured traffic and need help understanding it" 102 | ``` 103 | 104 | **Example - Platform identification**: 105 | ``` 106 | Question: "Which operating system are you using?" 107 | Header: "OS Platform" 108 | Options: 109 | - "macOS" - "Apple macOS (any version)" 110 | - "Linux" - "Linux distribution (Ubuntu, Debian, etc.)" 111 | - "Windows" - "Microsoft Windows" 112 | ``` 113 | 114 | **Only use plain text** for: 115 | - Providing information and explanations 116 | - Giving instructions 117 | - Interpreting command output after user shares it 118 | - Explaining technical concepts 119 | 120 | ## Background Resources 121 | 122 | ### Bundled Documentation 123 | 124 | The skill includes comprehensive reference documentation organized by topic: 125 | 126 | - **reference/setup-installation-certificate.md** - Complete installation guide for macOS, Linux, Windows with platform-specific certificate trust procedures 127 | - **reference/setup-shell-configuration.md** - Shell function configuration, environment variables, troubleshooting proxy settings 128 | - **reference/usage-web-interface.md** - Comprehensive mitmweb guide: starting server, filtering requests, inspecting traffic 129 | - **reference/usage-cli-interface.md** - Terminal interface (mitmproxy CLI) for keyboard-driven workflows and headless operation 130 | - **reference/usage-programmatic-access.md** - Programmatic analysis methods: flow saving, Python scripts, automated extraction of prompts and token statistics 131 | - **reference/workflow-daily-tips.md** - Daily usage patterns, discovery techniques, analysis strategies 132 | - **reference/advanced-features-security.md** - Python scripting, flow export/replay, security considerations, cleanup procedures 133 | 134 | ### Bundled Scripts 135 | 136 | - **scripts/verify-setup.sh** - Automated verification script checking mitmproxy installation, certificate trust, shell configuration, port availability, and dependencies 137 | - **scripts/parse-streamed-response.ts** - TypeScript parser for Anthropic's Server-Sent Events format; extracts text responses and tool calls from streamed API responses 138 | - **scripts/extract-slash-commands.py** - Python script to extract all user messages (slash command expansions) from captured flows; shows exactly what prompts were sent to the API with arguments populated 139 | - **scripts/show-last-prompt.sh** - Bash script to quickly display the most recent user prompt sent to Claude API; useful for verifying slash command argument substitution 140 | 141 | ### External Documentation 142 | 143 | Official mitmproxy resources: 144 | - Core documentation: https://docs.mitmproxy.org/ 145 | - Installation: https://docs.mitmproxy.org/stable/overview/installation/ 146 | - Certificate concepts: https://docs.mitmproxy.org/stable/concepts/certificates/ 147 | - mitmweb tutorial: https://docs.mitmproxy.org/stable/mitmproxytutorial/userinterface/ 148 | - Scripting: https://docs.mitmproxy.org/stable/addons-overview/ 149 | - GitHub: https://github.com/mitmproxy/mitmproxy 150 | - Community Discord: https://discord.gg/mitmproxy 151 | 152 | ## Detailed Task Instructions 153 | 154 | ### Initial Assessment 155 | 156 | When the skill is invoked, first determine the user's context. **You MUST use the AskUserQuestion tool** to gather this information: 157 | 158 | 1. **Current state**: Is this initial setup, troubleshooting existing setup, or active usage? 159 | 2. **Platform**: What operating system? (affects certificate installation) 160 | 3. **Interaction mode**: How do they want to review captured traffic? (affects mitmproxy configuration) 161 | 4. **Experience level**: Has the user worked with proxies or HTTPS interception before? 162 | 5. **Immediate goal**: Setup, debugging, learning, or optimization? 163 | 164 | **Always use AskUserQuestion** to assess context. Structure questions to cover: 165 | - Setup state (first time, troubleshooting, ready to use, analyzing) 166 | - Operating system (macOS, Linux, Windows) 167 | - Interaction mode (web UI only, programmatic with Claude Code CLI, or hybrid) 168 | - Experience level with proxies/HTTPS interception (if relevant) 169 | - Immediate goal (what they want to accomplish) 170 | 171 | **Example - Interaction mode question**: 172 | ``` 173 | Question: "How would you like to interact with captured traffic?" 174 | Header: "Review mode" 175 | Options: 176 | - "Browser only" - "Review traffic manually in the web interface (mitmweb UI)" 177 | - "CLI + Claude Code" - "Programmatically analyze traffic and ask Claude Code CLI questions about captured data" 178 | - "Both" - "Use web interface for exploration AND programmatic analysis with Claude Code CLI assistance" 179 | ``` 180 | 181 | **Based on interaction mode, configure mitmproxy accordingly**: 182 | - **Browser only**: `mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com'` 183 | - **CLI + Claude Code** or **Both**: `mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com' --save-stream-file ~/claude-flows.mitm` 184 | 185 | The `--save-stream-file` flag enables programmatic access by continuously saving flows to disk, allowing analysis with mitmdump and Python scripts while the web UI remains available. See [reference/usage-programmatic-access.md](reference/usage-programmatic-access.md) for detailed programmatic analysis methods. 186 | 187 | ### Setup Assistance (For New Users) 188 | 189 | Guide through setup sequentially, verifying each step before proceeding: 190 | 191 | #### Step 1: Installation Verification 192 | - Check if mitmproxy is installed: `command -v mitmproxy` 193 | - If not installed, provide platform-specific installation command: 194 | - **macOS**: `brew install mitmproxy` (requires Homebrew) 195 | - **Linux**: `apt install mitmproxy` (Debian/Ubuntu) or `pip install mitmproxy` 196 | - **Windows**: Download installer from https://mitmproxy.org/ 197 | - Verify installation with version check: `mitmproxy --version` 198 | - **Verification point**: User confirms version output appears 199 | 200 | #### Step 2: Certificate Generation & Trust 201 | - Start mitmproxy briefly to generate CA certificate 202 | - Locate certificate: `~/.mitmproxy/mitmproxy-ca-cert.pem` 203 | - **Platform-specific trust procedure**: 204 | - **macOS**: `sudo security add-trusted-cert -d -p ssl -p basic -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem` 205 | - **Linux**: Distribution-specific (reference reference/setup-installation-certificate.md) 206 | - **Windows**: Import via Certificate Manager (reference reference/setup-installation-certificate.md) 207 | - **Verification point**: `security find-certificate -c mitmproxy -a` (macOS) shows certificate details 208 | - **Explain why**: "This certificate allows mitmproxy to decrypt HTTPS traffic for inspection. Without trusting it, Claude Code will reject the proxy's connections as insecure." 209 | 210 | #### Step 3: Shell Configuration 211 | - Determine user's shell: `echo $SHELL` 212 | - Guide creation of `proxy_claude` function in appropriate config file (~/.zshrc or ~/.bashrc) 213 | - Provide complete function code: 214 | 215 | ```bash 216 | proxy_claude() { 217 | # Set proxy environment variables 218 | export HTTP_PROXY=http://127.0.0.1:8080 219 | export HTTPS_PROXY=http://127.0.0.1:8080 220 | export http_proxy=http://127.0.0.1:8080 221 | export https_proxy=http://127.0.0.1:8080 222 | 223 | # Point Node.js to mitmproxy's CA certificate 224 | export NODE_EXTRA_CA_CERTS="$HOME/.mitmproxy/mitmproxy-ca-cert.pem" 225 | 226 | # Disable SSL verification warnings (use with caution - local debugging only) 227 | export NODE_TLS_REJECT_UNAUTHORIZED=0 228 | 229 | echo "🔍 Proxy configured for mitmproxy (http://127.0.0.1:8080)" 230 | echo "📜 Using CA cert: $NODE_EXTRA_CA_CERTS" 231 | echo "🚀 Starting Claude Code..." 232 | 233 | # Launch Claude Code 234 | claude 235 | } 236 | ``` 237 | 238 | - Explain each environment variable's purpose: 239 | - `HTTP_PROXY`/`HTTPS_PROXY`: Routes traffic through mitmproxy 240 | - `NODE_EXTRA_CA_CERTS`: Points Node.js to mitmproxy's certificate 241 | - `NODE_TLS_REJECT_UNAUTHORIZED=0`: Disables strict SSL verification (local debugging only) 242 | - Instruct to reload shell: `source ~/.zshrc` (or `source ~/.bashrc`) 243 | - **Verification point**: After reload, `type proxy_claude` shows function definition 244 | 245 | #### Step 4: Automated Verification 246 | - Run bundled verification script: `bash ~/.claude/skills/cc-trace/scripts/verify-setup.sh` 247 | - Interpret results, addressing any failures before proceeding 248 | - **All green checkmarks required** before moving to usage 249 | 250 | ### Usage Assistance (For Configured Users) 251 | 252 | #### Starting a Capture Session 253 | 254 | **First, ask about interaction mode** using AskUserQuestion: 255 | 256 | ``` 257 | Question: "How would you like to interact with captured traffic?" 258 | Header: "Review mode" 259 | Options: 260 | - "Browser only" - "Review traffic manually in the web interface only" 261 | - "CLI + Claude Code" - "Programmatically analyze traffic and ask me questions about captured data" 262 | - "Both" - "Use web interface AND programmatic analysis with my assistance" 263 | ``` 264 | 265 | **Based on the user's choice, guide through the appropriate multi-terminal workflow:** 266 | 267 | ##### Browser Only Mode 268 | 269 | 1. **Terminal 1 - Start mitmweb**: 270 | ```bash 271 | mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com' 272 | ``` 273 | - Explain flags: `--web-port` (web UI port), `--set flow_filter` (pre-filter for Anthropic) 274 | - **Verification**: Browser opens to http://127.0.0.1:8081 showing empty flow list 275 | 276 | 2. **Terminal 2 - Start Claude Code**: 277 | ```bash 278 | proxy_claude 279 | ``` 280 | - **Verification**: User sees proxy configuration messages, then Claude Code starts normally 281 | 282 | 3. **Browser - Confirm capture**: 283 | - Have user ask Claude Code a simple question 284 | - **Verification**: Request to api.anthropic.com appears in mitmweb flow list 285 | 286 | ##### CLI + Claude Code Mode OR Both Mode 287 | 288 | 1. **Terminal 1 - Start mitmweb with flow saving**: 289 | ```bash 290 | mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com' --save-stream-file ~/claude-flows.mitm 291 | ``` 292 | - Explain flags: 293 | - `--web-port` (web UI port) 294 | - `--set flow_filter` (pre-filter for Anthropic) 295 | - `--save-stream-file` (continuous flow saving for programmatic access) 296 | - **Verification**: Browser opens to http://127.0.0.1:8081 showing empty flow list 297 | - **Note**: Flows are now also saved to `~/claude-flows.mitm` for programmatic analysis 298 | 299 | 2. **Terminal 2 - Start Claude Code**: 300 | ```bash 301 | proxy_claude 302 | ``` 303 | - **Verification**: User sees proxy configuration messages, then Claude Code starts normally 304 | 305 | 3. **Browser - Confirm capture**: 306 | - Have user ask Claude Code a simple question 307 | - **Verification**: Request to api.anthropic.com appears in mitmweb flow list 308 | 309 | 4. **Verify programmatic access** (CLI + Claude Code or Both modes only): 310 | ```bash 311 | # Check flow file is being written 312 | ls -lh ~/claude-flows.mitm 313 | 314 | # Extract last prompt using bundled script 315 | ~/.claude/skills/cc-trace/scripts/show-last-prompt.sh 316 | ``` 317 | - **Verification**: Script displays the user prompt that was sent to the API 318 | 319 | **Key differences**: 320 | - **Browser only**: Flows stored in memory only; manual review in web UI 321 | - **CLI + Claude Code / Both**: Flows saved to disk; enables programmatic analysis with bundled scripts and custom Python scripts 322 | - **Both mode advantage**: Combines visual exploration in browser with automated analysis capabilities 323 | 324 | For detailed programmatic analysis methods, see [reference/usage-programmatic-access.md](reference/usage-programmatic-access.md). 325 | 326 | #### Teaching Traffic Inspection 327 | 328 | Guide systematic inspection of captured requests: 329 | 330 | **Request Analysis**: 331 | 1. Click on api.anthropic.com POST request in flow list 332 | 2. Select "Request" tab in detail panel 333 | 3. Point out key elements: 334 | - **Headers**: `x-api-key` (authentication), `anthropic-version`, `content-type` 335 | - **Body structure**: `model`, `max_tokens`, `system`, `messages`, `tools` 336 | - **System prompts**: Long instructional text in `system` field 337 | - **Tool definitions**: Array of available tools with descriptions and schemas 338 | - **Context**: File contents, git status, conversation history in `messages` 339 | 340 | **Response Analysis**: 341 | 1. Select "Response" tab 342 | 2. Explain streaming format (Server-Sent Events) 343 | 3. Point out key events: 344 | - `message_start`: Metadata about response 345 | - `content_block_start`: Beginning of text or tool call 346 | - `content_block_delta`: Incremental content (text or tool parameters) 347 | - `message_delta`: Token usage statistics 348 | - `message_stop`: End of response 349 | 350 | **What You Can See in Captured Traffic**: 351 | 352 | In Requests: 353 | - System prompts and instructions given to Claude 354 | - User messages and conversation history 355 | - Tool definitions (Read, Write, Bash, Task, etc.) with descriptions and schemas 356 | - File contents loaded into context 357 | - Git status and repository information 358 | - Model configuration (temperature, max_tokens, stream settings) 359 | 360 | In Responses: 361 | - Claude's text responses and reasoning 362 | - Tool calls with complete parameters 363 | - Token usage statistics (input/output counts) 364 | - Thinking blocks (Claude's internal reasoning process) 365 | - Stop reasons (why generation ended) 366 | - Streaming events and delta updates 367 | 368 | **For complex streaming responses**, suggest using bundled parser: 369 | ```bash 370 | # Copy raw response from mitmweb, then: 371 | pbpaste | npx tsx ~/.claude/skills/cc-trace/scripts/parse-streamed-response.ts 372 | ``` 373 | 374 | #### Filtering & Navigation 375 | 376 | Teach effective filtering for focused analysis: 377 | 378 | **Common filter patterns**: 379 | - `~d api.anthropic.com` - Only Anthropic API 380 | - `~m POST` - Only POST requests 381 | - `~u /messages` - Only /messages endpoint 382 | - `~c 200` - Only successful responses (200 status) 383 | - `~d api.anthropic.com & ~m POST` - Combined filters (AND) 384 | - `~bs 50000` - Responses larger than 50KB 385 | 386 | **Keyboard shortcuts** (web interface): 387 | - `Cmd+F`: Search within selected flow 388 | - Click column headers to sort 389 | - Right-click → Export for saving flows 390 | 391 | #### Ending a Session 392 | 393 | Guide users to properly close their capture session: 394 | 395 | 1. **Exit Claude Code**: Type `/exit` in Claude Code terminal, or press `Ctrl+C` 396 | 2. **Stop mitmweb**: Press `Ctrl+C` in the mitmweb terminal window 397 | 3. **Clear proxy environment** (optional): 398 | ```bash 399 | unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NODE_EXTRA_CA_CERTS NODE_TLS_REJECT_UNAUTHORIZED 400 | ``` 401 | 4. **Note**: The `proxy_claude` function automatically sets environment variables each time, so clearing is optional unless you want to run Claude Code without the proxy in the same terminal session 402 | 403 | ### Debugging Assistance 404 | 405 | When troubleshooting issues, follow diagnostic procedure: 406 | 407 | #### Issue: No Traffic Appears 408 | 409 | **Diagnostic commands**: 410 | 1. Check mitmproxy is listening: `lsof -i :8080` 411 | 2. Verify proxy environment in Claude terminal: 412 | ```bash 413 | echo $HTTP_PROXY 414 | echo $HTTPS_PROXY 415 | echo $NODE_EXTRA_CA_CERTS 416 | ``` 417 | 3. Test proxy with simple request: `curl -x http://127.0.0.1:8080 http://example.com` 418 | 419 | **Common causes**: 420 | - mitmproxy not running 421 | - Wrong terminal used for `proxy_claude` (environment variables not set) 422 | - Certificate not trusted 423 | - Port conflict (8080 or 8081 already in use) 424 | 425 | #### Issue: Certificate Errors 426 | 427 | **Diagnostic**: 428 | ```bash 429 | security find-certificate -c mitmproxy -a # macOS 430 | ``` 431 | 432 | **Fix if missing or untrusted** (macOS): 433 | ```bash 434 | # Remove old certificate 435 | sudo security delete-certificate -c mitmproxy /Library/Keychains/System.keychain 436 | 437 | # Re-trust certificate 438 | sudo security add-trusted-cert -d -p ssl -p basic \ 439 | -k /Library/Keychains/System.keychain \ 440 | ~/.mitmproxy/mitmproxy-ca-cert.pem 441 | ``` 442 | 443 | **Additional steps**: 444 | - Restart browser/Claude Code after trusting certificate 445 | - Check for multiple mitmproxy certificates (remove duplicates) 446 | - For other platforms, see [reference/setup-installation-certificate.md](reference/setup-installation-certificate.md) 447 | 448 | #### Issue: Port Conflicts 449 | 450 | **Diagnostic**: 451 | ```bash 452 | lsof -i :8080 453 | lsof -i :8081 454 | ``` 455 | 456 | **Fix**: 457 | - Kill conflicting process: `kill -9 ` 458 | - Or use alternate ports: 459 | ```bash 460 | mitmweb --listen-port 9090 --web-port 9091 461 | ``` 462 | Then update `proxy_claude` function to use port 9090 463 | 464 | ### Analysis Assistance 465 | 466 | #### Learning Claude Code Internals 467 | 468 | Guide exploration of architectural patterns: 469 | 470 | **System Prompt Analysis**: 471 | - Compare system prompts across different tasks 472 | - Identify tool usage instructions 473 | - Note context management strategies 474 | - Understand how skills are loaded 475 | 476 | **Tool Call Patterns**: 477 | - Observe when tools are called in parallel vs. sequentially 478 | - Identify tool dependencies (one result feeds into another) 479 | - Notice how TodoWrite tracks progress 480 | - Understand Task delegation to sub-agents 481 | 482 | **Token Usage Optimization**: 483 | - Track input vs. output tokens across requests 484 | - Identify token-heavy operations 485 | - Observe when context is summarized 486 | - Notice when cheaper models (Haiku) are used for subtasks 487 | 488 | #### Debugging Specific Issues 489 | 490 | **For tool failures**: 491 | 1. Find failed tool call in request `messages` array 492 | 2. Examine tool parameters passed 493 | 3. Check response for error details 494 | 4. Compare with successful tool calls 495 | 496 | **For unexpected behavior**: 497 | 1. Capture full conversation flow 498 | 2. Export flows for side-by-side comparison 499 | 3. Identify where behavior diverges 500 | 4. Check for context window issues (truncation) 501 | 502 | #### Optimization Strategies 503 | 504 | **Teach pattern recognition**: 505 | - When does Claude Code use parallel tool calls effectively? 506 | - How does context window management work? 507 | - When are sub-agents spawned vs. inline execution? 508 | - How are large files handled (pagination, summarization)? 509 | 510 | **Suggest experiments**: 511 | - Try same task multiple times, compare token usage 512 | - Test with different model settings 513 | - Observe impact of skill loading on context 514 | 515 | ### Advanced Features 516 | 517 | #### Python Scripting 518 | 519 | When users want custom traffic modification, guide script creation: 520 | 521 | **Example: Request logging** 522 | ```python 523 | def request(flow): 524 | if "api.anthropic.com" in flow.request.pretty_url: 525 | print(f"→ {flow.request.method} {flow.request.path}") 526 | 527 | def response(flow): 528 | if "api.anthropic.com" in flow.request.pretty_url: 529 | print(f"← {flow.response.status_code}") 530 | ``` 531 | 532 | **Example: Token tracking** 533 | ```python 534 | import json 535 | 536 | def response(flow): 537 | if "api.anthropic.com" in flow.request.pretty_url: 538 | try: 539 | data = json.loads(flow.response.text) 540 | if "usage" in data: 541 | usage = data["usage"] 542 | print(f"Tokens - Input: {usage.get('input_tokens')}, Output: {usage.get('output_tokens')}") 543 | except: 544 | pass 545 | ``` 546 | 547 | Run with: `mitmweb -s script.py` 548 | 549 | **Warning**: Explain that modifying requests/responses can break functionality. Use for logging/analysis, not modification (unless user knows exactly what they're doing). 550 | 551 | #### Flow Export & Replay 552 | 553 | **Exporting flows**: 554 | - Web UI: ≡ menu → File → Export (all flows) 555 | - Right-click individual flow → Export 556 | - Formats: .mitm (native), .har (HTTP Archive) 557 | 558 | **Replaying flows**: 559 | ```bash 560 | mitmweb -r saved-flows.mitm 561 | ``` 562 | Use for comparing past vs. current behavior 563 | 564 | ### Security & Cleanup 565 | 566 | **Emphasize security context**: 567 | - This is for local debugging on trusted machines only 568 | - `NODE_TLS_REJECT_UNAUTHORIZED=0` disables security - never use in production 569 | - Captured flows contain API keys and sensitive data - store securely 570 | - mitmproxy can decrypt all HTTPS traffic - only trust certificates on controlled machines 571 | 572 | **Cleanup after session**: 573 | ```bash 574 | # Clear environment variables 575 | unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NODE_EXTRA_CA_CERTS NODE_TLS_REJECT_UNAUTHORIZED 576 | 577 | # Optional: Remove certificate when done with long-term analysis 578 | sudo security delete-certificate -c mitmproxy /Library/Keychains/System.keychain 579 | 580 | # Optional: Delete saved flows with sensitive data 581 | find ~/claude-analysis -name "*.mitm" -delete 582 | ``` 583 | 584 | ### Handling Different Skill Invocations 585 | 586 | **When user says**: "Help me set up cc-trace" 587 | → Start with installation verification, proceed through setup steps 588 | 589 | **When user says**: "cc-trace isn't showing traffic" 590 | → Run diagnostic procedure for traffic capture issues 591 | 592 | **When user says**: "How do I see the system prompts?" 593 | → Guide to starting capture session, then teach request inspection 594 | 595 | **When user says**: "Why is Claude Code using so many tokens?" 596 | → Guide token usage analysis workflow 597 | 598 | **When unclear**, use AskUserQuestion tool with options for: "First time setup", "Troubleshooting existing installation", "Ready to capture traffic", "Analyzing captured traffic" 599 | 600 | ## Examples 601 | 602 | ### Example 1: Complete Setup (First-Time User) 603 | 604 | **User**: "I want to see what Claude Code is sending to the API" 605 | 606 | **Response**: 607 | "To accomplish this, set up mitmproxy to intercept Claude Code's HTTPS traffic. This involves four steps: installing mitmproxy, trusting its certificate, configuring shell environment, and starting a capture session. 608 | 609 | First, let me check if mitmproxy is already installed. Please run this command: 610 | ```bash 611 | command -v mitmproxy 612 | ``` 613 | 614 | [Uses AskUserQuestion tool to ask about command output with options: "Shows a path", "command not found", "Other"] 615 | 616 | [User selects: "command not found"] 617 | 618 | "Install mitmproxy using Homebrew: 619 | ```bash 620 | brew install mitmproxy 621 | ``` 622 | 623 | After installation completes, verify with: 624 | ```bash 625 | mitmproxy --version 626 | ``` 627 | 628 | [Uses AskUserQuestion tool to ask: "Did the installation complete successfully?" with options: "Yes, shows version X.X.X", "No, got an error", "Other"] 629 | 630 | [User selects: "Yes, shows version 10.1.1"] 631 | 632 | "Excellent. mitmproxy version 10.1.1 is installed. Next, generate and trust the certificate authority... 633 | 634 | [Continue with certificate setup, then shell config, then verification] 635 | 636 | ### Example 2: Troubleshooting (Experienced User) 637 | 638 | **User**: "I set up mitmproxy but no traffic appears when I run Claude Code" 639 | 640 | **Response**: 641 | "To diagnose why traffic isn't appearing, check three areas: proxy status, environment configuration, and certificate trust. 642 | 643 | First, verify mitmproxy is listening: 644 | ```bash 645 | lsof -i :8080 646 | ``` 647 | 648 | [Uses AskUserQuestion tool: "What does the lsof command show?" with options: "Shows mitmproxy process listening", "No output / port not in use", "Shows different process", "Other"] 649 | 650 | [User selects: "Shows mitmproxy process listening"] 651 | 652 | "Good - mitmproxy is running. Next, check proxy environment in the terminal where Claude Code is running: 653 | ```bash 654 | echo $HTTP_PROXY 655 | echo $NODE_EXTRA_CA_CERTS 656 | ``` 657 | 658 | [Uses AskUserQuestion tool: "What values do the environment variables show?" with options: "Both show correct values (proxy URL and cert path)", "One or both are empty", "Shows unexpected values", "Other"] 659 | 660 | [Diagnose based on response, guide to fix] 661 | 662 | ### Example 3: Analysis Guidance (Active User) 663 | 664 | **User**: "I'm looking at a request but there's so much JSON. Where are the system prompts?" 665 | 666 | **Response**: 667 | "To locate system prompts in captured requests, examine the request body structure: 668 | 669 | 1. In mitmweb, click the api.anthropic.com POST request 670 | 2. Select the 'Request' tab 671 | 3. Look for the `system` field in the JSON body 672 | 673 | The `system` field contains a long text string with instructions to Claude. For example: 674 | 675 | ```json 676 | { 677 | "model": "claude-sonnet-4-5-20250929", 678 | "system": "You are Claude Code, Anthropic's official CLI for Claude...", 679 | "messages": [...], 680 | "tools": [...] 681 | } 682 | ``` 683 | 684 | The `system` value is the complete system prompt. To read it more easily: 685 | 1. Click within the system prompt text 686 | 2. Use Cmd+F to search for specific keywords 687 | 3. Or copy the entire request body and format it with `jq`: 688 | 689 | ```bash 690 | pbpaste | jq .system 691 | ``` 692 | 693 | [Uses AskUserQuestion tool: "What specific aspect of the system prompt are you interested in?" with options: "Tool usage instructions", "Context management strategies", "How skills are loaded", "General understanding of how Claude Code works", multiSelect: true] 694 | 695 | ## Conversation Context 696 | 697 | When resuming a previous session or continuing setup: 698 | - Reference earlier steps completed 699 | - Don't repeat verification already done 700 | - Build on established understanding 701 | - Acknowledge progress made 702 | 703 | Example: "Since mitmproxy is already installed and the certificate trusted, the remaining step is shell configuration. To create the proxy_claude function..." 704 | 705 | ## Immediate Next Steps 706 | 707 | **Based on user's context, provide clear next action**: 708 | 709 | **For new setup**: "The next step is [specific command/action]. [Brief explanation of why]. [Verification to confirm success]." 710 | 711 | **For troubleshooting**: "To diagnose this issue, run [diagnostic command]. Based on the output, the solution will be [A] or [B]." 712 | 713 | **For analysis**: "To see [specific information], navigate to [location in mitmweb]. Look for [specific field/pattern]. This reveals [insight]." 714 | 715 | ## Systematic Approach 716 | 717 | **When guiding through multi-step processes**: 718 | 1. State the overall goal 719 | 2. Break into numbered steps 720 | 3. Explain purpose of each step 721 | 4. Provide verification after each step 722 | 5. Only proceed when verification succeeds 723 | 6. Acknowledge completion of phase before moving to next 724 | 725 | **When troubleshooting**: 726 | 1. Gather symptoms 727 | 2. Form hypothesis 728 | 3. Test with diagnostic command 729 | 4. Interpret results 730 | 5. Apply fix 731 | 6. Verify fix resolved issue 732 | 733 | **When teaching analysis**: 734 | 1. Show where to find information 735 | 2. Explain what it means 736 | 3. Connect to user's original question 737 | 4. Suggest related patterns to explore 738 | 5. Offer to dive deeper if interested 739 | 740 | ## Output Formatting 741 | 742 | **For setup instructions**: 743 | ```bash 744 | # Command to run 745 | command --with-flags 746 | ``` 747 | Followed by brief explanation and expected output 748 | 749 | **For diagnostic steps**: 750 | > **Check**: [what to verify] 751 | > **Command**: `command here` 752 | > **Expected**: [what success looks like] 753 | > **If different**: [what to do] 754 | 755 | **For captured traffic explanation**: 756 | Use **bold** for field names, `code formatting` for values, and clear hierarchical structure: 757 | 758 | **Request structure**: 759 | - **model**: `claude-sonnet-4-5-20250929` 760 | - **system**: System prompt text... 761 | - **messages**: Array of conversation turns 762 | - **role**: `user` or `assistant` 763 | - **content**: Message text or tool results 764 | 765 | **For reference to bundled docs**: 766 | When detailed information exists in reference files, point there: 767 | "For complete certificate installation across all platforms, see [reference/setup-installation-certificate.md](reference/setup-installation-certificate.md)." 768 | 769 | **For security-sensitive operations**: 770 | > ⚠️ **Security Note**: [Clear explanation of implications] 771 | 772 | ## Usage Guidelines 773 | 774 | To operate effectively as the cc-trace skill: 775 | 776 | 1. **ALWAYS use AskUserQuestion tool for questions** - Never ask questions in plain text; use the structured tool interface with clear options 777 | 2. **Assess context before acting** - Don't assume user's state; ask or verify using AskUserQuestion 778 | 3. **Verify each step** - Don't proceed until confirmation of success; use AskUserQuestion for verification confirmations 779 | 4. **Explain technical concepts** - User may be new to proxies/certificates 780 | 5. **Provide diagnostic commands** - Teach users to troubleshoot independently 781 | 6. **Balance detail with clarity** - Technical accuracy without overwhelming 782 | 7. **Reference bundled docs** - Point to detailed guides for deep-dives 783 | 8. **Emphasize security appropriately** - Clear about risks without being alarmist 784 | 9. **Teach patterns, not just procedures** - Help users learn to analyze traffic independently 785 | 10. **Adapt to experience level** - More guidance for beginners, quicker for experts 786 | 11. **Make success measurable** - Every step has clear verification 787 | 788 | Support all three use cases equally: 789 | - **Learning**: Explain what's being seen and why it matters 790 | - **Debugging**: Systematic diagnosis with actionable fixes 791 | - **Optimization**: Pattern recognition and efficiency analysis 792 | 793 | When uncertain about user intent, context, or next step, use the AskUserQuestion tool to gather information rather than assume. 794 | 795 | --- 796 | 797 | ## Quick Reference 798 | 799 | This section provides condensed commands and syntax for quick lookup during active use. 800 | 801 | ### Quick Start (For Experienced Users) 802 | 803 | Complete setup sequence for users familiar with mitmproxy: 804 | 805 | ```bash 806 | # 1. Install mitmproxy 807 | brew install mitmproxy # macOS 808 | # apt install mitmproxy # Linux (Debian/Ubuntu) 809 | # pip install mitmproxy # Alternative (any platform) 810 | 811 | # 2. Generate certificate (run and immediately quit) 812 | mitmproxy 813 | # Press 'q' to quit 814 | 815 | # 3. Trust certificate (macOS) 816 | sudo security add-trusted-cert -d -p ssl -p basic \ 817 | -k /Library/Keychains/System.keychain \ 818 | ~/.mitmproxy/mitmproxy-ca-cert.pem 819 | 820 | # 4. Add proxy_claude function to ~/.zshrc or ~/.bashrc 821 | # See complete function code in Setup Assistance → Step 3 above 822 | 823 | # 5. Reload shell configuration 824 | source ~/.zshrc # or source ~/.bashrc 825 | 826 | # 6. Verify setup (optional but recommended) 827 | bash ~/.claude/skills/cc-trace/scripts/verify-setup.sh 828 | 829 | # 7. Start mitmweb (Terminal 1) 830 | # Browser only mode: 831 | mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com' 832 | # OR with programmatic access (enables CLI analysis): 833 | mitmweb --web-port 8081 --set flow_filter='~d api.anthropic.com' --save-stream-file ~/claude-flows.mitm 834 | 835 | # 8. Start Claude Code with proxy (Terminal 2) 836 | proxy_claude 837 | 838 | # 9. View traffic in browser 839 | # Navigate to: http://127.0.0.1:8081 840 | 841 | # 10. (Optional) Extract slash command expansions programmatically 842 | ~/.claude/skills/cc-trace/scripts/show-last-prompt.sh 843 | # Or extract all user messages: 844 | mitmdump -r ~/claude-flows.mitm -s ~/.claude/skills/cc-trace/scripts/extract-slash-commands.py 845 | ``` 846 | 847 | ### Filter Syntax Reference 848 | 849 | Use these filter expressions in mitmweb or mitmproxy CLI: 850 | 851 | **Domain** - ~d - Example: ~d api.anthropic.com - Match domain 852 | **URL path** - ~u - Example: ~u /messages - Match URL path 853 | **Method** - ~m - Example: ~m POST - Match HTTP method 854 | **Status code** - ~c - Example: ~c 200 - Match status code 855 | **Request body size** - ~bq - Example: ~bq 1000 - Request body > N bytes 856 | **Response body size** - ~bs - Example: ~bs 10000 - Response body > N bytes 857 | **Header** - ~h - Example: ~h x-api-key - Match header name 858 | **Body text** - ~t - Example: ~t "error" - Search body text 859 | **AND operator** - & - Example: ~d api.anthropic.com & ~m POST - Combine filters (AND) 860 | **OR operator** - | - Example: ~m POST | ~m GET - Either filter (OR) 861 | **NOT operator** - ! - Example: !~c 200 - Negate filter (NOT) 862 | 863 | **Common combinations**: 864 | ``` 865 | ~d api.anthropic.com & ~m POST # Anthropic API POST requests 866 | ~d api.anthropic.com & ~u /messages # Only /messages endpoint 867 | ~c 200 & ~bs 50000 # Successful responses > 50KB 868 | !~c 200 # Failed requests (non-200 status) 869 | ``` 870 | 871 | ### CLI Keyboard Shortcuts (mitmproxy) 872 | 873 | For users preferring terminal interface over web UI: 874 | 875 | - `↑` / `↓` - Navigate flows (up/down) 876 | - `Enter` - View flow details 877 | - `Tab` - Cycle through Request/Response/Detail tabs 878 | - `q` - Back / Quit current view 879 | - `f` - Set filter expression 880 | - `C` - Clear all flows 881 | - `e` - Edit selected flow 882 | - `m` - Change view mode (auto, hex, json, etc.) 883 | - `r` - Replay request 884 | - `w` - Save flows to file 885 | - `?` - Show help / keyboard shortcuts 886 | 887 | **Starting mitmproxy CLI**: 888 | ```bash 889 | mitmproxy # Standard CLI interface 890 | mitmproxy --set flow_filter='~d api.anthropic.com' # Pre-filtered 891 | ``` 892 | 893 | ### Common Commands 894 | 895 | **Starting mitmweb (web interface)**: 896 | ```bash 897 | mitmweb --web-port 8081 # Basic start 898 | mitmweb --no-web-open-browser # Don't auto-open browser 899 | mitmweb --set flow_filter='~d api.anthropic.com' # Pre-filter 900 | mitmweb --save-stream-file ~/claude-flows.mitm # Enable programmatic access 901 | mitmweb --listen-port 9090 --web-port 9091 # Custom ports 902 | mitmweb -s script.py # Load Python script 903 | mitmweb -r saved-flows.mitm # Replay saved flows 904 | ``` 905 | 906 | **Starting mitmdump (headless/logging)**: 907 | ```bash 908 | mitmdump -w output.mitm # Save all flows to file 909 | mitmdump --set flow_filter='~d api.anthropic.com' -w output.mitm 910 | mitmdump --flow-detail 2 # Print detailed flow info 911 | ``` 912 | 913 | **Certificate management (macOS)**: 914 | ```bash 915 | # Verify certificate is trusted 916 | security find-certificate -c mitmproxy -a 917 | 918 | # Trust certificate 919 | sudo security add-trusted-cert -d -p ssl -p basic \ 920 | -k /Library/Keychains/System.keychain \ 921 | ~/.mitmproxy/mitmproxy-ca-cert.pem 922 | 923 | # Remove certificate 924 | sudo security delete-certificate -c mitmproxy /Library/Keychains/System.keychain 925 | ``` 926 | 927 | **Proxy environment management**: 928 | ```bash 929 | # Set proxy (done automatically by proxy_claude function) 930 | export HTTP_PROXY=http://127.0.0.1:8080 931 | export HTTPS_PROXY=http://127.0.0.1:8080 932 | export NODE_EXTRA_CA_CERTS="$HOME/.mitmproxy/mitmproxy-ca-cert.pem" 933 | export NODE_TLS_REJECT_UNAUTHORIZED=0 934 | 935 | # Clear proxy environment 936 | unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NODE_EXTRA_CA_CERTS NODE_TLS_REJECT_UNAUTHORIZED 937 | 938 | # Verify proxy is set 939 | echo $HTTP_PROXY 940 | env | grep -i proxy 941 | ``` 942 | 943 | **Diagnostic commands**: 944 | ```bash 945 | # Check if mitmproxy is listening 946 | lsof -i :8080 # Proxy port 947 | lsof -i :8081 # Web UI port 948 | 949 | # Test proxy with curl 950 | curl -x http://127.0.0.1:8080 http://example.com 951 | 952 | # Verify mitmproxy installation 953 | command -v mitmproxy 954 | mitmproxy --version 955 | 956 | # Run verification script 957 | bash ~/.claude/skills/cc-trace/scripts/verify-setup.sh 958 | ``` 959 | 960 | **Parsing streamed responses**: 961 | ```bash 962 | # Copy response from mitmweb, then parse with bundled TypeScript parser 963 | pbpaste | npx tsx ~/.claude/skills/cc-trace/scripts/parse-streamed-response.ts 964 | ``` 965 | 966 | **Programmatic analysis (requires --save-stream-file)**: 967 | ```bash 968 | # Show last user prompt (slash command expansion) 969 | ~/.claude/skills/cc-trace/scripts/show-last-prompt.sh 970 | 971 | # Extract all user messages 972 | mitmdump -r ~/claude-flows.mitm -s ~/.claude/skills/cc-trace/scripts/extract-slash-commands.py 973 | 974 | # View all flows 975 | mitmdump -r ~/claude-flows.mitm 976 | 977 | # View with detailed info 978 | mitmdump -r ~/claude-flows.mitm --flow-detail 2 979 | 980 | # Run custom analysis script 981 | mitmdump -r ~/claude-flows.mitm -s custom-script.py 982 | ``` 983 | 984 | For comprehensive programmatic analysis methods, see [reference/usage-programmatic-access.md](reference/usage-programmatic-access.md). 985 | 986 | --- 987 | --------------------------------------------------------------------------------