LLM Interceptor (LLI)

🔍 Proxy-layer microscope for LLM traffic analysis

A cross-platform command-line tool that intercepts, analyzes, and logs communications between AI coding tools/agents (Claude Code, Cursor, Codex, OpenCode, etc.) and their backend LLM APIs.

✨ Features

• Watch Mode - Interactive continuous capture with session management
• One-Shot Capture (lli run) - Wrap any command (claude -p, codex exec, ...) with fully automated, non-interactive capture — ideal for scripted agent experiments
• Transparent Inspection - See exactly what prompts are sent and what responses are received
• Streaming Support - Captures both streaming (SSE) and non-streaming API responses
• Multi-Provider - Works with Anthropic, OpenAI (Chat Completions and Responses API), Google, Groq, Together, Mistral, and more
• Automatic Masking - Protects API keys and sensitive data in logs
• Auto Processing - Automatically merges and splits session data
• Cross-Platform - Works on Windows, macOS, and Linux

📦 Installation

For AI coding agents (install the agent skill first)

If you are an AI agent (OpenCode, Claude Code, Codex, Cursor, ...) reading this README: install the bundled agent skill first. It teaches you how to capture traffic with lli run and analyze existing traces/ directories (token usage, latency, tool calls, prompts) — including bootstrapping lli itself when it is not installed yet.

npx skills add chouzz/llm-interceptor

This uses the open skills CLI and works with 70+ agents. Non-interactive examples:

# Install for OpenCode into the current project
npx skills add chouzz/llm-interceptor --skill lli-trace-analysis -a opencode -y

# Install globally for Claude Code
npx skills add chouzz/llm-interceptor --skill lli-trace-analysis -a claude-code -g -y

See Agent Skill for what the skill covers. The human-oriented CLI installation continues below.

Using uv (recommended)

uv tool install llm-interceptor

Using pip

pip install llm-interceptor

From source

git clone https://github.com/chouzz/llm-interceptor.git
cd llm-interceptor
uv sync --dev
uv run lli-dev-setup

Development setup

Git does not copy hooks from .git/hooks when you clone a repository, so each new clone must install the project's pre-commit hook once:

uv sync --dev
uv run lli-dev-setup

If you prefer pip:

pip install -e .[dev]
lli-dev-setup

🚀 Quick Start

Scripting or agent experiments? You can skip this interactive workflow entirely — see Automated Capture: lli run to capture claude -p "..."-style commands with zero interaction.

1. Install Certificate (For HTTPS Capture Only)

If you're only capturing HTTP traffic, you can skip this step. Only install the certificate if you need to capture HTTPS requests.

# Generate certificate
lli watch &
sleep 2
kill %1

Then install the certificate:

macOS:

open ~/.mitmproxy/mitmproxy-ca-cert.pem
# Double-click to add to Keychain
# In Keychain Access, find "mitmproxy" → Double-click → Trust → "Always Trust"

Linux (Ubuntu/Debian):

sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt
sudo update-ca-certificates

Windows: Navigate to %USERPROFILE%\.mitmproxy\. Double-click mitmproxy-ca-cert.p12 (or mitmproxy-ca-cert.cer) to open the certificate import wizard → Install Certificate → Local Machine → place in Trusted Root Certification Authorities → Finish.

2. Start Watch Mode and Record Sessions

lli watch

If you need to capture traffic to a custom or self-hosted API , use --include with a glob pattern, for example:

lli watch --include "*api.example.com*"

In watch mode:

• Press Enter to start recording a session
• Press Enter again to stop recording and automatically process the session
• Press Esc while recording to cancel the current session (no output generated)
• Ctrl+C to exit watch mode

3. Configure Your Application and Start Dialogue (New Terminal)

export HTTP_PROXY=http://127.0.0.1:9090
export HTTPS_PROXY=http://127.0.0.1:9090
export NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem
# Optional: bypass proxy for some hosts (e.g. localhost). Configure in lli.toml as no_proxy or run: lli config --proxy-help

# Run Claude and start your conversation
claude
# Now start your dialogue - all prompts and responses will be captured

4. (Optional) Corporate network: upstream CA certificate

If you capture traffic behind a corporate proxy or on a network where upstream servers use a company-signed certificate, you may see TLS errors because the proxy only trusts the system CAs, not your company’s CA. Configure the upstream trust CA so LLI (mitmproxy) can verify connections to the corporate proxy or target hosts:

• Client → LLI: Your app must trust the mitmproxy CA (install ~/.mitmproxy/mitmproxy-ca-cert.pem as in step 1).
• LLI → upstream (corporate proxy / target): LLI must trust the company CA. Set the path to your company’s root or intermediate CA (PEM file):

# Option A: CLI
lli watch --upstream-ca-cert /path/to/corporate-ca.pem

Use lli config --show to confirm the upstream CA path. If the file does not exist at startup, LLI will exit with an error.

5. Visualize with Web UI

The web interface should be launched in http://127.0.0.1:48080 to analyze captured conversations:

In the UI, you can:

• Browse captured sessions in the sidebar
• View conversation flow between requests and responses
• Inspect detailed API payloads and metadata
• Search and filter through captured data
• Copy formatted content for further analysis

Tip: prefer a permanent UI? Run lli serve once and keep it running — it shows sessions from both lli watch and lli run and picks up new ones automatically (see Automated Capture).

🤖 Automated Capture: lli run

For scripting and agent experiments you can skip watch mode entirely. lli run wraps a single command with a private ephemeral proxy and captures its LLM traffic end-to-end — no keypresses, no env setup, no manual merge:

lli run -- claude -p "fix the failing test"

lli run --label codex -- codex exec "review src/"

How it works:

1. Starts a throwaway proxy on a random loopback port (nothing else on your machine is affected)
2. Spawns the command with HTTP(S)_PROXY and CA trust (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE) already injected — Claude Code, Codex, and curl work out of the box
3. When the command exits, waits for in-flight streaming responses to drain, then automatically processes the session (merge + split into per-exchange request/response JSON) and writes run_meta.json
4. Exits with the command's own exit code, so it composes with scripts and CI

Each run's session lands directly in the traces directory alongside watch-mode sessions (microsecond IDs keep concurrent runs collision-free), so it shows up in the web UI automatically:

traces/
├── all_captured_20260101_120000_123456.jsonl   # raw records for this run (replayable)
└── session_20260101_120000_123456/             # this run's session
    ├── session_meta.json
    ├── run_meta.json                           # command, label, exit code, duration, ...
    ├── 001_request_2026-01-01_12-00-00.json
    ├── 001_response_2026-01-01_12-00-00.json
    └── ...

--label is recorded in run_meta.json (not in directory names), so run sessions are easy to find programmatically:

ls traces/session_*/run_meta.json

This makes it easy to batch-analyze how different agents (Claude Code, Codex, ...) solve the same tasks — every exchange, tool call, and token count lands in plain JSON files ready for scripting:

for task in "fix the login bug" "add dark mode" "write tests for api.py"; do
  lli run --label "claude-$task" -- claude -p "$task"
done
# Then inspect traces/session_*/00N_{request,response}_*.json
# (run sessions are the ones containing run_meta.json)

Note: the mitmproxy CA file (~/.mitmproxy/mitmproxy-ca-cert.pem) must exist — it is generated the first time any LLI proxy starts. System-wide certificate installation (Quick Start step 1) is not required for lli run, since CA trust is injected into the child process directly.

See lli run CLI reference for all options (--label, --output-dir, --include, --exclude, --drain-timeout).

🤖 Agent Skill: Let Your Coding Agent Analyze Traces

This repo ships an agent skill at .agents/skills/lli-trace-analysis/ that teaches coding agents (OpenCode, and any tool that reads the .agents/skills convention) to work with LLI captures:

• summarize sessions (models, normalized token usage incl. cache, latency, tool calls, failed/orphan requests) via the bundled zero-dependency lli_report.py
• look up exact JSON field paths per capture format (Anthropic Messages, OpenAI Chat Completions, OpenAI Responses) with ready-made jq snippets
• set up lli and run capture experiments (lli run) even when lli is not installed yet

OpenCode discovers it automatically when you work inside this repository. To install it into any other project (or globally), use the open skills CLI:

# Interactive: pick agents and scope (project or global)
npx skills add chouzz/llm-interceptor

# Non-interactive: current project, OpenCode only
npx skills add chouzz/llm-interceptor --skill lli-trace-analysis -a opencode -y

# Global install for Claude Code (available across all projects)
npx skills add chouzz/llm-interceptor --skill lli-trace-analysis -a claude-code -g -y

# Direct link to the skill inside this repo
npx skills add https://github.com/chouzz/llm-interceptor/tree/main/.agents/skills/lli-trace-analysis

Once installed, just ask your agent to e.g. "summarize token usage in traces/" or "run lli run -- claude -p "..." and analyze the capture" — the skill handles the rest (including installing lli if needed). Alternatively, copy the .agents/skills/lli-trace-analysis/ directory into your project's .agents/skills/ manually.

🎬 How Watch Mode Works

Watch mode uses a state machine with three states:

Example Session

$ lli watch

╭─────────────────────────╮
│   LLI Watch Mode        │
│ Continuous Capture      │
╰─────────────────────────╯

  Proxy Port:    9090
  Output Dir:    ./traces (or OS-specific logs directory)
  Global Log:    traces/all_captured_20251203_220000.jsonl

Configure your application:
  export HTTP_PROXY=http://127.0.0.1:9090
  export HTTPS_PROXY=http://127.0.0.1:9090
  export NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem

● [IDLE] Monitoring on :9090... Logging to all_captured_20251203_220000.jsonl
  Press [Enter] to START Session 1
<Enter>

◉ [REC] Session 01_session_20251203_223010 is recording...
  Press [Enter] to STOP & PROCESS, [Esc] to CANCEL
<Enter>

⏳ [BUSY] Processing Session 01_session_20251203_223010...
  ✔ Saved to traces/01_session_20251203_223010/

● [IDLE] Monitoring on :9090... Logging to all_captured_20251203_220000.jsonl
  Press [Enter] to START Session 2

Output Structure

./traces/                                    # Root output directory
├── all_captured_20251203_220000.jsonl       # Global log (all traffic)
│
├── 01_session_20251203_223010/              # Session 01 folder
│   ├── raw.jsonl                            # Clean session data
│   ├── merged.jsonl                         # Merged conversations
│   └── split_output/                        # Individual files
│       ├── 001_request_2025-12-03_22-30-10.json
│       └── 001_response_2025-12-03_22-30-10.json
│
├── 02_session_20251203_224500/              # Session 02 folder
└── ...

📋 CLI Reference

lli watch

Start watch mode for continuous session capture (recommended).

lli watch [OPTIONS]

Options:
  -p, --port INTEGER           Proxy server port (default: 9090)
  -o, --output-dir, --log-dir PATH  Root output directory (default: ./traces or OS log dir)
  -i, --include TEXT           Additional URL patterns to include (glob pattern)
  --upstream-ca-cert PATH      Path to PEM or CA bundle for trusting upstream (e.g. corporate proxy) certificates
  --debug                  Enable debug mode with verbose logging

Examples:

# Basic watch mode
lli watch

# Custom port and output directory
lli watch --port 8888 --output-dir ./my_traces

# Include custom API endpoint (glob pattern)
lli watch --include "*my-custom-api.com*"

# Corporate network: trust company CA so upstream TLS (proxy/target) is verified
lli watch --upstream-ca-cert /path/to/corporate-ca.pem

# Match all subdomains of a domain
lli watch --include "*api.example.com*"

Glob Pattern Syntax:

lli config

Display configuration and setup help.

lli config --cert-help    # Certificate installation instructions
lli config --proxy-help   # Proxy configuration instructions
lli config --show         # Show current configuration

lli run

Run a command with automatic, fully non-interactive LLM traffic capture — ideal for scripted agent experiments (claude -p, codex exec, ...).

lli run starts a private ephemeral proxy, spawns the command with HTTP(S)_PROXY / CA environment variables injected, and when the command exits it drains in-flight responses, processes the session (merge + split into per-exchange request/response JSON files), and writes run metadata. lli exits with the command's exit code, so it can be composed in scripts and CI.

lli run -- claude -p "fix the failing test"

lli run --label codex -- codex exec "review src/"

# Custom provider + output location
lli run --include "*my-llm.example.com*" --output-dir ./experiments -- curl -s https://api.example.com/health

Each run's session is created directly in the traces directory alongside watch-mode sessions (microsecond IDs keep concurrent runs collision-free), and run_meta.json inside it records the command, label, exit code, and duration:

traces/session_20260101_120000_123456/
├── session_meta.json
├── run_meta.json              # command, label, exit code, duration, ...
├── all_captured_*.jsonl       # raw captured records (replayable, at traces root)
├── 001_request_2026-01-01_12-00-00.json
├── 001_response_2026-01-01_12-00-00.json
└── ...

Notes:

• The mitmproxy CA certificate (~/.mitmproxy/mitmproxy-ca-cert.pem) is exported to the child via NODE_EXTRA_CA_CERTS / SSL_CERT_FILE / REQUESTS_CA_BUNDLE, so Node- and OpenSSL-based agents work out of the box.
• After the command exits, LLI waits up to --drain-timeout (default 15s) for in-flight streaming responses to complete before finalizing.

lli serve

Start the web UI as a standalone, long-running server. Serves all captured sessions (from lli watch and lli run) and picks up new ones automatically — keep it running in one terminal and capture from any other:

lli serve                          # http://127.0.0.1:48080, default traces dir

lli serve --port 48080 --output-dir ./traces

lli watch still embeds its own UI; when its port is already taken by a standalone lli serve instance, it reuses that server.

lli stats

Display statistics for a captured trace file.

lli stats traces/01_session_xxx/raw.jsonl

🔧 Supported LLM Providers

LLI is pre-configured to capture traffic from:

Add custom providers with --include (using glob patterns):

lli watch --include "*my-custom-api.com*"

🐛 Troubleshooting

SSL Certificate Error

Problem: SSL: CERTIFICATE_VERIFY_FAILED

Solution: Install the mitmproxy CA certificate. Run lli config --cert-help for instructions.

Node.js Apps Not Working

Problem: Requests hang or timeout when using Claude Code, Cursor, etc.

Solution: Set the NODE_EXTRA_CA_CERTS environment variable:

export NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem

TLS / handshake errors behind corporate proxy

Problem: Upstream TLS handshake failures when capturing company URLs (e.g. traffic goes through a corporate proxy that uses a company CA).

Solution: Configure the upstream trust CA so LLI can verify the corporate proxy or target server certificate. Use --upstream-ca-cert, or set proxy.upstream_ca_cert in lli.toml, or LLI_UPSTREAM_CA_CERT. See the "Corporate network: upstream CA certificate" section above.

No Traffic Captured

Problem: Watch mode is running but no requests are logged

Solution:

1. Verify proxy environment variables are set correctly
2. Make sure the URL matches the default patterns (or add --include)
3. Check lli config --show to see current filter patterns

📜 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Before committing from a fresh clone, run lli-dev-setup once to install the repository's pre-commit hook locally.

📞 Support

• GitHub Issues: Report a bug
• Documentation: Read the docs