cc-trace

🥈Silver

Intercept, debug, and analyze Claude Code API requests using mitmproxy. Ideal for operations teams to troubleshoot and optimize API interactions. Connects to Claude Code CLI for debugging workflows.

153150Updated 1mo ago

Intermediate30min to implementautomation

Saves ~105 min per use

Quick InstallView Source

git clone https://github.com/alexfazio/cc-trace.git

Works with:

Claude

Overview

About This Skill

The cc-trace skill is a powerful tool designed for developers and AI practitioners who need to intercept, debug, analyze, and review Claude Code API requests. Utilizing mitmproxy, this interactive assistant allows users to gain insights into API interactions, making it easier to identify issues and optimize workflows. By streamlining the debugging process, cc-trace enhances the development experience and promotes efficient troubleshooting. One of the key benefits of using cc-trace is its ability to save time during the debugging phase of API development. Although specific time savings are currently unknown, the skill's intermediate complexity suggests that it can significantly reduce the time spent on manual debugging tasks. By automating the interception and analysis of API requests, developers can focus on building robust applications rather than getting bogged down in troubleshooting. This skill is particularly suited for developers and product managers who are involved in API development and integration. As organizations increasingly adopt AI automation and workflow automation strategies, having tools like cc-trace becomes essential for maintaining high-quality code and efficient development processes. Practical use cases include debugging API calls during the development of AI agents or ensuring the reliability of data pipelines in data engineering projects. Implementing cc-trace is straightforward, with an estimated time of 30 minutes to set up. While the skill is categorized as intermediate in difficulty, it requires no specific department or role expertise, making it accessible to a wide range of users. By incorporating cc-trace into your AI-first workflows, you can enhance your debugging capabilities and ensure that your Claude Code applications run smoothly.

How to Use

1. **Install and Configure mitmproxy**: Run `pip install mitmproxy` and ensure it's added to your PATH. Start mitmproxy with `mitmproxy --listen-port 8080`. 2. **Set Up cc-trace**: Configure Claude Code CLI to route API requests through mitmproxy by setting the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to `http://localhost:8080`. 3. **Reproduce the Issue**: Execute the Claude Code commands or workflows that trigger the API interactions you want to debug. For example, run `claude code --project AcmeCorpInventory --task "update-inventory"`. 4. **Analyze the Traffic**: Use mitmproxy's interface to inspect the intercepted requests and responses. Filter by endpoint or status code (e.g., `~u /api/v2/update-stock` or `~s 422`). 5. **Export and Share Findings**: Save the session data with `mitmproxy --save-stream-file debug_session.mitm` and share the file with your team for further analysis. Use the `cc-trace` skill to generate a summary of the findings.

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/alexfazio/cc-trace

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Use cc-trace with mitmproxy to intercept and analyze the Claude Code API requests for [PROJECT_NAME]. Focus on debugging [SPECIFIC_ISSUE] such as [EXAMPLE_ISSUE]. After capturing the requests, identify the root cause of the issue and suggest optimizations for the API interactions. Provide a summary of the findings including request/response payloads and timing details.

Example Output

After setting up cc-trace with mitmproxy for the 'Acme Corp Inventory' project, we intercepted 47 API requests over a 15-minute debugging session. The primary issue was identified in the `/api/v2/update-stock` endpoint, where the `PATCH` request consistently returned a 422 Unprocessable Entity error due to a missing `location_id` field in the payload. The request body was:
```json
{
  "product_id": "PRD-4567",
  "quantity_change": -5,
  "reason": "damaged"
}
```
The response from the API was:
```json
{
  "error": "Missing required field: location_id",
  "status": 422
}
```
Further analysis revealed that the `location_id` was being omitted because the frontend application was not passing it from the user's selected warehouse dropdown. The timing data showed that the request took an average of 1.2 seconds to fail, with no retries configured. To resolve this, we recommended:
1. Adding client-side validation to ensure `location_id` is included before sending the request.
2. Implementing a fallback mechanism to default to the user's primary warehouse if no location is selected.
3. Adding retry logic for 422 errors with exponential backoff.

The optimized request payload now includes:
```json
{
  "product_id": "PRD-4567",
  "quantity_change": -5,
  "reason": "damaged",
  "location_id": "WH-001"
}
```
This change reduced the error rate from 100% to 0% in subsequent tests.