Skip to content
Skills Library
AI & agents · Analysis

using-ccproxy-inspector

/using-ccproxy-inspector

Operates the ccproxy inspector MITM system for intercepting, inspecting, and transforming LLM API traffic. Covers running CLI tools through the reverse proxy or permissive WireGuard namespace capture path, checking namespace status and doctor output, inspecting flows with client-vs-forwarded request comparison, understanding the inbound/transform/outbound pipeline, capturing and auditing shape artifacts, applying the privacy guide, and diagnosing flow issues. Use when running CLI applications through ccproxy, inspecting intercepted flows, comparing client request vs forwarded request, checking

Repository
ccproxy ↗
Licence
AGPL-3.0
Last repository change
09.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
3
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 09.08.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/inspect_flow.py, scripts/list_flows.py, scripts/shaping_status.py

What it does and when to use it

Operates the ccproxy inspector MITM system for intercepting, inspecting, and transforming LLM API traffic. Covers running CLI tools through the reverse proxy or permissive WireGuard namespace capture path, checking namespace status and doctor output, inspecting flows with client-vs-forwarded request comparison, understanding the inbound/transform/outbound pipeline, capturing and auditing shape artifacts, applying the privacy guide, and diagnosing flow issues. Use when running CLI applications through ccproxy, inspecting intercepted flows, comparing client request vs forwarded request, checking

Original author description

Operates the ccproxy inspector MITM system for intercepting, inspecting, and transforming LLM API traffic. Covers running CLI tools through the reverse proxy or permissive WireGuard namespace capture path, checking namespace status and doctor output, inspecting flows with client-vs-forwarded request comparison, understanding the inbound/transform/outbound pipeline, capturing and auditing shape artifacts, applying the privacy guide, and diagnosing flow issues. Use when running CLI applications through ccproxy, inspecting intercepted flows, comparing client request vs forwarded request, checking

How it works

  1. Inspect First
  2. Running Tools Through ccproxy
  3. Choosing A Capture Mode
  4. Understanding Flow State
  5. Pipeline Map
  6. Inspecting Flows
  7. Shape Artifacts
  8. Diagnosing Problems
  9. Reference Files
Original SKILL.md headings · 302 lines, 1,364 words
SKILL.md preview
---
name: using-ccproxy-inspector
description: >-
  Operates the ccproxy inspector MITM system for intercepting, inspecting, and
  transforming LLM API traffic. Covers running CLI tools through the reverse
  proxy or permissive WireGuard namespace capture path, checking namespace
  status and doctor output, inspecting flows with client-vs-forwarded request
  comparison, understanding the inbound/transform/outbound pipeline, capturing
  and auditing shape artifacts, applying the privacy guide, and diagnosing flow
  issues. Use when running CLI applications through ccproxy, inspecting
  intercepted flows, comparing client request vs forwarded request, checking
  shaping profile status, using WireGuard namespace capture, explaining privacy
  behavior, or debugging the hook pipeline.
---

# Using the ccproxy Inspector

The inspector intercepts LLM API traffic through mitmproxy and routes accepted
flows through the ccproxy addon chain:

```
InspectorAddon -> FingerprintCaptureAddon -> MultiHARSaver -> ShapeCaptureAddon
               -> inbound DAG -> transform router -> outbound DAG
               -> TransportOverrideAddon -> AuthAddon -> GeminiAddon
               -> PerplexityAddon -> EgressSanitizerAddon
```

Use the `using-ccproxy-api` skill for provider auth, sentinel keys, SDK base URL
configuration, native `ccproxy.yaml` setup, and sibling `config.yaml` model
routing when applicable.

The ccproxy plugin does not install or register the ccproxy FastMCP server for
the user. If an MCP-aware client should use ccproxy's flow-inspection tools,
the user must add their own MCP server config pointing at the running daemon's
`http://127.0.0.1:<mcp-port>/mcp` endpoint and supply its bearer token when
configured. Keep plugin installation separate from MCP server registration.

## Inspect First

Before debugging a flow, establish which process and config directory are in
play:

```bash
ccproxy status
ccproxy status --json
ccproxy status --proxy --inspect --mcp
```

For namespace work, also inspect the transparent capture path:

```bash
ccproxy namespace status
ccproxy namespace status --json
ccproxy namespace doctor
ccproxy namespace doctor --json
```

Interpretation:

- `namespace status` reports implementation facts: permissive mode, generated
  WireGuard config presence, slirp4netns topology, and required tool paths.
- `privacy_claim: false` is intentional. ccproxy reports observable runtime
  behavior; it does not claim that the namespace is a restrictive privacy
  firewall.
- `namespace doctor` runs a live probe through the same namespace execution path
  used by `ccproxy run --capture`.
- `namespace doctor` fails for DNS, public IPv4, or ccproxy-localhost
  reachability failures. IPv6 is reported but is not a failure.
- `ccproxy namespace wireguard-config` prints raw WireGuard client config and
  can expose private key material. Do not print or share it casually.

When the task concerns privacy, security language, namespace guarantees,
keylogs, flow exports, or sharing diagnostics, read `docs/privacy.md`.

## Running Tools Through ccproxy

### Reverse proxy: `ccproxy run`

Use this when the client honors SDK base URL environment variables:

```bash
ccproxy run -- claude
ccproxy run -- aider
ccproxy run -- python my_agent.py
```

This sets `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, and `OPENAI_API_BASE` to the
configured ccproxy reverse proxy listener. Only traffic addressed to ccproxy is
intercepted.

Use for lightweight SDK debugging and normal OpenAI/Anthropic-compatible
clients.

### WireGuard namespace capture: `ccproxy run --capture`

Use this when the tool hardcodes provider endpoints, when base URL injection is
not enough, or when you need reference traffic from a real provider CLI:

```bash
ccproxy start
ccproxy run --capture -- claude -p "hello"
ccproxy run --capture -- aider --model claude-sonnet-4-5-20250929
ccproxy run --capture -- python my_agent.py
```

The subprocess runs in a rootless Linux user+network namespace. ccproxy
configures a WireGuard client inside that namespace, routes the namespace
default route through mitmproxy, and injects a combined CA bundle via:

```bash
SSL_CERT_FILE
NODE_EXTRA_CA_CERTS
REQUESTS_CA_BUNDLE
CURL_CA_BUNDLE
```

Important behavior:

- The namespace path is permissive by default because ccproxy is a development
  tool.
- Unmatched WireGuard traffic passes through to its original destination.
- Namespace localhost is DNATed through the slirp4netns gateway so tools with
  hardcoded `127.0.0.1:4000` can still reach ccproxy.
- A port-forwarding monitor uses the slirp4netns API to expose namespace
  listeners back to the host, which supports OAuth callback workflows.
- Do not describe this path as a default deny privacy sandbox.

## Choosing A Capture Mode

| Scenario | Prefer |
| --- | --- |
| SDK client supports configurable base URL | `ccproxy run` |
| CLI hardcodes provider endpoints | `ccproxy run --capture` |
| Need native provider CLI reference traffic | `ccproxy run --capture` |
| Need minimum moving parts | `ccproxy run` |
| Need full local network capture for a tool | `ccproxy run --capture` |
| Need to explain privacy behavior | `docs/privacy.md` + `ccproxy namespace status --json` |

## Understanding Flow State

Every accepted reverse-proxy or WireGuard flow is `direction="inbound"`. The
pipeline stage names `inbound`, `transform`, and `outbound` describe processing
order, not traffic direction.

`InspectorAddon` stamps source metadata:

| Source | Meaning |
| --- | --- |
| `reverse` | Request entered through the reverse proxy listener |
| `wireguard` | Request entered through mitmproxy's WireGuard listener |
| `unknown` | Default before source is stamped |

Every flow has these useful views:

- **Client request**: pre-pipeline snapshot of what the client sent.
- **Forwarded request**: post-pipeline request ccproxy intended to send
  upstream.
- **Provider response**: raw provider response before response-side transform
  when captured.

Use these views to distinguish client behavior from ccproxy behavior.

## Pipeline Map

```
Client request snapshot
  |
  v
Inbound DAG
  inject_auth: sentinel key -> configured provider credential
  extract_session_id: body metadata -> ctx.metadata.session_id
  provider-specific inbound hooks
  |
  v
Transform router
  passthrough: keep destination/body
  redirect: rewrite destination/auth, preserve wire format
  transform: rewrite destination/auth and body via lightllm
  |
  v
Outbound DAG
  gemini_cli: cloudcode-pa envelope/path/header handling
  inject_mcp_notifications: buffered MCP events -> synthetic messages
  verbose_mode: strip redact-thinking beta header
  shape: replay packaged/local request shape and inner-DAG hooks
  commitbee_compat: compatibility shim
  |
  v
TransportOverrideAddon
  optional curl-cffi sidecar for configured fingerprint profiles
  |
  v
AuthAddon
  401 detect -> credential re-resolve -> replay when token changed
  |
  v
GeminiAddon / PerplexityAddon / EgressSanitizerAddon
  provider-specific response handling and ccproxy header cleanup
```

## Inspecting Flows

All `ccproxy flows` commands operate on a resolved flow set:

```
GET /flows -> config.flows.default_jq_filters -> CLI --jq filters -> final set
```

Use repeatable `--jq` filters. Each filter must consume and produce a JSON
array.

```bash
ccproxy flows list
ccproxy flows list --json
ccproxy flows list --jq 'map(select(.request.pretty_host == "api.anthropic.com"))'

ccproxy flows compare
ccproxy flows compare --jq 'map(.[-1])'

ccproxy flows diff
ccproxy flows diff --jq 'map(select(.response.status_code >= 400))'

ccproxy flows dump > all.har
ccproxy flows dump --jq 'map(.[-1])' > latest.har

ccproxy flows clear --all
ccproxy flows clear --jq 'map(select(.response.status_code >= 400))'
```

Privacy note: HAR dumps, request/response bodies, flow JSON, and packet
captures are sensitive. Prefer `flows compare` for local debugging and read
`docs/privacy.md` before sharing artifacts.

## Shape Artifacts

Shape replay uses provider-specific `.mflow` or patch artifacts to reproduce
known-good SDK request envelopes while injecting live request content.

Capture shape source traffic from a real CLI run:

```bash
ccproxy start
ccproxy run --capture -- claude -p "shape capture"
ccproxy flows list
ccproxy shapes save anthropic
ccproxy shapes save anthropic --mflow
```

Audit packaged shape invariants:

```bash
uv run ccproxy shapes audit
```

Shape guidance:

- Packaged `.mflow` files must be minimal request-only artifacts.
- Do not include responses, auth tokens, cookies, flow records, provider
  responses, client snapshots, or captured TLS fingerprint metadata in packaged
  defaults.
- Anthropic and Gemini packaged defaults are distribution artifacts; normal
  users should not need to capture their own shapes unless a provider SDK
  behavior changed before a fixed release exists.
- See `docs/shaping.md` for canonical shape behavior.

## Diagnosing Problems

```
Problem?
|
+- ccproxy not capturing?
|  -> ccproxy status --json
|  -> For transparent capture: ccproxy namespace status --json
|  -> For transparent capture: ccproxy namespace doctor --json
|  -> Check same CCPROXY_CONFIG_DIR for start/run/status
|
+- Provider returns 401/403?
|  -> ccproxy flows compare --jq 'map(.[-1])'
|  -> Check sentinel key: sk-ant-oat-ccproxy-{provider}
|  -> Check providers.{name}.auth resolves manually
|  -> Check ctx.metadata.auth_provider / auth_injected
|  -> Check ccproxy logs for AuthAddon refresh/replay
|
+- Request not transformed?
|  -> ccproxy flows list --json
|  -> Check lightllm.transforms match_host/match_path/match_model
|  -> Check sentinel key resolved to a Provider
|  -> ccproxy flows compare --jq 'map(.[-1])'
|
+- Shape not applied?
|  -> Check hooks.outbound contains ccproxy.hooks.shape
|  -> Check ccproxy shapes audit
|  -> Check transform metadata exists for the flow
|  -> Check flow source: reverse or auth-injected flows consume shapes
|
+- Gemini fails?
|  -> Check gemini_cli outbound hook
|  -> Check Google auth source refresh behavior
|  -> Check GeminiAddon capacity fallback logs
|  -> Inspect forwarded body for cloudcode-pa envelope fields
|
+- Privacy or artifact-sharing question?
   -> Read docs/privacy.md
   -> Prefer ccproxy namespace status --json over raw WireGuard config
   -> Treat tls.keylog, wg.keylog, HAR files, and .mflow captures as sensitive
```

## Reference Files

- `docs/privacy.md` - privacy model, sensitive artifacts, sharing guidance
- `docs/inspect.md` - inspector stack architecture
- `docs/shaping.md` - request shaping system
- `docs/lightllm.md` - request/response transformation internals
- `skills/using-ccproxy-inspector/reference/flow-api-reference.md` - mitmweb
  REST API endpoints, flow data model, content views, authentication
Files in this package (5)
  • SKILL.md 11 KB
  • reference/flow-api-reference.md 4 KB
  • scripts/inspect_flow.py 13 KB
  • scripts/list_flows.py 7 KB
  • scripts/shaping_status.py 8 KB

Versions

The database has no other skills named using-ccproxy-inspector.

Database snapshot: 13.11.2026 · package version 67fe63786425 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100client-smoke
    Drive a locally built server with a real client: the Inspector CLI (scripted), the Inspector web UI (by hand) and an LLM client. Use when smoke-testing a server change; when calling a tool, reading a resource or getting a prompt from the command line; when choosing a protocol…
  • 100geoskills-cli
    Agent-native command surface for discovering, inspecting, and validating the geo-skills toolkit. Use when an operator or coding agent needs to run geoskills doctor, enumerate bundled skills or prompts, validate the full repository contract, validate an owner-intent handoff for…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.