Skip to content
Back to search

ccproxy

Build mods for Claude Code: Hook any request, modify any response, /model "with-your-custom-model", intelligent model routing using your logic or ours

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/starbaser--ccproxy/badge.svg)](/listings/starbaser--ccproxy)

HTML

<a href="/listings/starbaser--ccproxy"><img src="/api/listings/starbaser--ccproxy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Platform support

| Platform | Reverse proxy (`ccproxy start`) | WireGuard namespace jail (`ccproxy run --capture`) | |----------|---|---| | Linux | ✅ | ✅ | | Windows (WSL2) | ✅ | ✅ | | macOS | ✅ | ❌ — requires Linux namespaces |

WSL2 is fully supported because it *is* Linux. Native Windows is not — use WSL2. On macOS, the reverse proxy listener (`ccproxy start` + SDK use) works fine, but the namespace jail (`ccproxy run --capture`) requires Linux kernel features (unprivileged user/net namespaces, `slirp4netns`, `iptables` NAT) that have no macOS equivalent.

Windows via WSL2

The recommended Windows install is the `ccproxy.wsl` distro artifact. It is built on NixOS-WSL and includes ccproxy plus the Linux namespace tools required by `ccproxy run --capture`.

# Requires Store WSL 2.4.4 or newer.
wsl --update
wsl --version
wsl --install --from-file ccproxy.wsl
wsl -d ccproxy

Inside the distro:

ccproxy init
ccproxy start
ccproxy namespace status --json
ccproxy namespace doctor --json

Tier 1 Windows support is Windows 11 22H2+ with Store-distributed WSL2, systemd enabled, and mirrored networking recommended. Windows 10 and older WSL networking are best-effort. WSL1 and native Windows without WSL are unsupported.

Advanced users can still use Ubuntu on WSL2 with systemd and Nix, but the release artifact is the primary out-of-box path.

Linux

The WireGuard namespace jail needs a small set of system tools on `PATH`: `slirp4netns`, `wireguard-tools` (`wg`), `iproute2` (`ip`), `iptables`, `util-linux` (`unshare`, `nsenter`), and `procps` (`sysctl`).

# Debian / Ubuntu
sudo apt update
sudo apt install -y slirp4netns wireguard-tools iproute2 iptables procps

# Fedora
sudo dnf install -y slirp4netns wireguard-tools iproute iptables-nft procps-ng

# Arch
sudo pacman -S slirp4netns wireguard-tools iproute2 iptables procps-ng

# NixOS — provided via the project devShell (`nix develop`)

Then install ccproxy:

# Recommended: uv tool (isolated venv, console scripts on PATH)
uv tool install ai-ccproxy

# Alternative: pip
pip install ai-ccproxy

On Ubuntu 24.04+, unprivileged user namespaces are restricted by AppArmor by default. Either run once:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

…or add a path-scoped AppArmor profile (see [rootless-containers/rootlesskit][rk-apparmor]).

[rk-apparmor]: https://github.com/rootless-containers/rootlesskit/blob/main/docs/getting-started.md#ubuntu-2310-and-later

macOS

Only the reverse proxy is supported. No system packages are required.

uv tool install ai-ccproxy
# or
pip install ai-ccproxy

`ccproxy start` and SDK use (`ANTHROPIC_BASE_URL=http://localhost:4000`) work the same as on Linux. `ccproxy run --capture` will fail fast with a clear error listing the missing Linux-only tools.

Verify

ccproxy --help
ccproxy init
ccproxy status --proxy --inspect    # exit 3 = both down (expected, nothing running yet)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 665 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # `ccproxy` — CLI Proxy [![Version](https://img.shields.io/badge/version-2.0.0-orange.svg)](https://github.com/starbaser/ccproxy)
  2. > [Discord](https://starbased.net/discord)
  3. ccproxy is a transparent network interceptor for LLM tooling and AI harnesses,
  4. built on mitmproxy and WireGuard with full TLS inspection and Wireshark keylog
  5. export. Originally purpose-built for Claude Code, ccproxy now works with any LLM
  6. client: Aider, Cursor, OpenAI SDK, or anything else that speaks HTTP. It jails a
  7. process inside a rootless WireGuard namespace, intercepts at the network layer,
  8. and feeds it through a DAG-driven pipeline that can decompose, transform, and
  9. re-route traffic between providers.
  10. Cross-provider request and response transformation is handled by `lightllm`, a
  11. surgical adapter and streaming-FSM layer inside ccproxy — no LiteLLM proxy
  12. subprocess, no gateway server.
  13. **New in 2.0**: Codex/OpenAI Responses support with packaged request shaping,
  14. plus DeepSeek V4 routing for Anthropic-format requests through DeepSeek's
  15. `/anthropic/v1/messages` endpoint. See [Configuration](#configuration) for
  16. the routing setup.
  17. The hook pipeline is your extension point for building mods and taking control
  18. of your LLM usage while respecting terms of service:
  19. - **Cross-provider routing**: redirect or transform requests between Anthropic,
  20. Gemini, OpenAI, DeepSeek, Perplexity Pro, and Anthropic-compatible forks.
  21. - **Compliance shaping**: replay packaged, sanitized SDK compliance envelopes
  22. for built-in providers while injecting your actual request content at runtime.
  23. - **MCP bridging**: add unsupported MCP features to any client:
  24. [sampling](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling)
  25. via sentinel key detection,
  26. [server notifications](https://modelcontextprotocol.io/specification/2025-11-25/basic/index#notifications)
  27. bridged into the LLM context via ccproxy’s `/mcp` endpoint, and experimental
  28. [tasks](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
  29. support.
  30. > Feedback and contributions welcome —
  31. > [open an issue](https://github.com/starbaser/ccproxy/issues) or submit a PR.
  32. ## Installation
  33. ### Platform support
  34. | Platform | Reverse proxy (`ccproxy start`) | WireGuard namespace jail (`ccproxy run --capture`) |
  35. |----------|---|---|
  36. | Linux | ✅ | ✅ |
  37. | Windows (WSL2) | ✅ | ✅ |
  38. | macOS | ✅ | ❌ — requires Linux namespaces |
  39. WSL2 is fully supported because it *is* Linux. Native Windows is not — use WSL2.
  40. On macOS, the reverse proxy listener (`ccproxy start` + SDK use) works fine, but
  41. the namespace jail (`ccproxy run --capture`) requires Linux kernel features
  42. (unprivileged user/net namespaces, `slirp4netns`, `iptables` NAT) that have no
  43. macOS equivalent.
  44. ### Windows via WSL2
  45. The recommended Windows install is the `ccproxy.wsl` distro artifact. It is
  46. built on NixOS-WSL and includes ccproxy plus the Linux namespace tools required
  47. by `ccproxy run --capture`.
  48. ```powershell
  49. # Requires Store WSL 2.4.4 or newer.
  50. wsl --update
  51. wsl --version
  52. wsl --install --from-file ccproxy.wsl
  53. wsl -d ccproxy
  54. ```
  55. Inside the distro:
  56. ```bash
  57. ccproxy init
  58. ccproxy start
  59. ccproxy namespace status --json
  60. ccproxy namespace doctor --json
  61. ```
  62. Tier 1 Windows support is Windows 11 22H2+ with Store-distributed WSL2,
  63. systemd enabled, and mirrored networking recommended. Windows 10 and older WSL
  64. networking are best-effort. WSL1 and native Windows without WSL are unsupported.
  65. Advanced users can still use Ubuntu on WSL2 with systemd and Nix, but the
  66. release artifact is the primary out-of-box path.
  67. ### Linux
  68. The WireGuard namespace jail needs a small set of system tools on `PATH`:
  69. `slirp4netns`, `wireguard-tools` (`wg`), `iproute2` (`ip`), `iptables`,
  70. `util-linux` (`unshare`, `nsenter`), and `procps` (`sysctl`).
  71. ```bash
  72. # Debian / Ubuntu
  73. sudo apt update
  74. sudo apt install -y slirp4netns wireguard-tools iproute2 iptables procps
  75. # Fedora
  76. sudo dnf install -y slirp4netns wireguard-tools iproute iptables-nft procps-ng
  77. # Arch
  78. sudo pacman -S slirp4netns wireguard-tools iproute2 iptables procps-ng
  79. # NixOS — provided via the project devShell (`nix develop`)
  80. ```
  81. Then install ccproxy:
  82. ```bash
  83. # Recommended: uv tool (isolated venv, console scripts on PATH)
  84. uv tool install ai-ccproxy
  85. # Alternative: pip
  86. pip install ai-ccproxy
  87. ```
  88. On Ubuntu 24.04+, unprivileged user namespaces are restricted by AppArmor by
  89. default. Either run once:
  90. ```bash
  91. sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
  92. ```
  93. …or add a path-scoped AppArmor profile (see
  94. [rootless-containers/rootlesskit][rk-apparmor]).
  95. [rk-apparmor]: https://github.com/rootless-containers/rootlesskit/blob/main/docs/getting-started.md#ubuntu-2310-and-later
  96. ### macOS
  97. Only the reverse proxy is supported. No system packages are required.
  98. ```bash
  99. uv tool install ai-ccproxy
  100. # or
  101. pip install ai-ccproxy
  102. ```
  103. `ccproxy start` and SDK use (`ANTHROPIC_BASE_URL=http://localhost:4000`) work
  104. the same as on Linux. `ccproxy run --capture` will fail fast with a clear error
  105. listing the missing Linux-only tools.
  106. ### Verify
  107. ```bash
  108. ccproxy --help
  109. ccproxy init
  110. ccproxy status --proxy --inspect # exit 3 = both down (expected, nothing running yet)
  111. ```
  112. ## Quick Start
  113. ```bash
  114. # Initialize ccproxy.yaml + LiteLLM-compatible config.yaml
  115. ccproxy init
  116. # Start the proxy and inspector stack (foreground)
  117. ccproxy start
  118. ```
  119. **SDK use**: point any OpenAI-compatible client at the reverse proxy listener:
  120. ```bash
  121. export ANTHROPIC_BASE_URL=http://localhost:4000
  122. claude -p "hello"
  123. ```
  124. **Transparent capture**: run a command inside the WireGuard namespace jail (all
  125. traffic intercepted):
  126. ```bash
  127. ccproxy run --capture -- claude -p "hello"
  128. ```
  129. ## Architecture
  130. Traffic enters through one of two listeners, passes through a fixed three-stage
  131. addon chain, and exits directly to the provider API.
  132. ```mermaid
  133. flowchart TD
  134. subgraph Listeners
  135. RP["Reverse Proxy :4000"]
  136. WG["WireGuard CLI"]
  137. end
  138. RP --> Chain
  139. WG --> Chain
  140. subgraph Chain["Addon Chain"]
  141. IN["inbound<br/>DAG hooks"] --> TX["transform<br/>lightllm"] --> OUT["outbound<br/>DAG hooks"]
  142. end
  143. Chain --> API["Provider API"]
  144. ```
  145. **Addon chain** (fixed order):
  146. `ReadySignal → InspectorAddon → FingerprintCaptureAddon → MultiHARSaver → ShapeCaptureAddon → inbound DAG → transform → outbound DAG → TransportOverrideAddon → AuthAddon → GeminiAddon → PerplexityAddon → EgressSanitizerAddon`
  147. `AuthAddon` and `GeminiAddon` sit after the outbound pipeline so they see
  148. ccproxy-finalized requests/responses. `AuthAddon` owns 401-detect → refresh →
  149. replay. `GeminiAddon` owns Gemini capacity fallback (sticky retry + fallback
  150. chain on 429/503) and cloudcode-pa envelope unwrapping.
  151. **lightllm** converts request and response bodies through ccproxy's own
  152. adapter layer and streaming FSMs. URL rewriting and auth injection are owned by
  153. the inspector route and `Provider` config, while `lightllm` owns wire-format
  154. conversion. LiteLLM itself is not a runtime dependency: sibling `config.yaml`
  155. model declarations are compiled into ccproxy-native bindings before requests
  156. enter this path.
  157. **SSE streaming**: `SSEPipeline` handles cross-provider streaming by parsing
  158. SSE events into ccproxy's response IR and rendering each chunk back to the
  159. listener's wire format.
  160. ## Configuration
  161. `ccproxy init` writes sibling `ccproxy.yaml` and `config.yaml` templates under
  162. `~/.config/ccproxy/`. Both are also discovered beneath
  163. `$CCPROXY_CONFIG_DIR`.
  164. - `ccproxy.yaml` owns native runtime services: providers, authentication,
  165. hooks, inspection, shaping, and explicit transform overrides.
  166. - `config.yaml` is a LiteLLM-compatible frontend for model definitions,
  167. aliases, endpoints, credentials, metadata, and supported request defaults.
  168. The frontend compiles into the existing `CCProxyConfig`/`Provider` runtime; it
  169. does not restore LiteLLM's proxy process or router. Routing precedence is
  170. explicit `lightllm.transforms`, exact then wildcard compiled model bindings,
  171. sentinel-selected providers, then no match. See
  172. [Configuration](docs/configuration.md) for the supported compatibility subset
  173. and trust-boundary rules.
  174. `ccproxy.yaml`:
  175. ```yaml
  176. ccproxy:
  177. port: 4000
  178. # Provider entries keyed by sentinel suffix. The sentinel key
  179. # sk-ant-oat-ccproxy-{name} resolves to providers[name] for token
  180. # injection and routing.
  181. providers:
  182. anthropic:
  183. auth:
  184. type: command
  185. command: "jq -r '.claudeAiOauth.accessToken' ~/.claude/.credentials.json"
  186. base_url: https://api.anthropic.com
  187. path: /v1/messages
  188. type: anthropic
  189. deepseek:
  190. auth:
  191. type: command
  192. command: "printenv DEEPSEEK_API_KEY"
  193. header: x-api-key
  194. base_url: https://api.deepseek.com
  195. path: /anthropic/v1/messages
  196. type: anthropic
  197. hooks:
  198. inbound:
  199. - ccproxy.hooks.inject_auth
  200. - ccproxy.hooks.extract_session_id
  201. outbound:
  202. - ccproxy.hooks.gemini_cli
  203. - ccproxy.hooks.pplx_stamp_headers
  204. - ccproxy.hooks.inject_mcp_notifications
  205. - ccproxy.hooks.verbose_mode
  206. - ccproxy.hooks.shape
  207. - ccproxy.hooks.commitbee_compat
  208. lightllm:
  209. # Optional regex-matched override rules layered on top of the
  210. # sentinel-driven providers map. Default is empty: most routing
  211. # comes from `providers` via inject_auth's sentinel detection.
  212. transforms:
  213. - match_path: ^/v1/chat/completions
  214. match_model: ^gpt-4o
  215. action: transform
  216. dest_provider: anthropic
  217. dest_model: claude-haiku-4-5-20251001
  218. ```
  219. **Transform matching**: `match_host` (optional regex, checked against
  220. `pretty_host` + Host header + X-Forwarded-Host), `match_path` (regex,
  221. default `.*`), `match_model` (regex, optional). First match wins.
  222. Three actions: `redirect` (default — rewrite destination, preserve body),
  223. `transform` (cross-format via lightllm), `passthrough` (forward unchanged).
  224. Auth resolves through `dest_provider` → `providers[name]`.
  225. ### Auth source types
  226. `Provider.auth` dispatches on `type:`. Two static loaders return whatever the
  227. underlying source holds; OAuth loaders own the refresh lifecycle in-process.
  228. | `type` | What it is | When to use |
  229. | --- | --- | --- |
  230. | `command` | Run a shell command, return stdout | Static API keys, opnix/SOPS secret commands, env-var injection |
  231. | `file` | Read a file, return contents | Static API keys stored in a managed secret file |
  232. | `anthropic_oauth` | In-process Anthropic OAuth refresh | Share `~/.claude/.credentials.json` with Claude Code CLI |
  233. | `google_oauth` | In-process Google/Gemini OAuth refresh | Share `~/.gemini/oauth_creds.json` with gemini-cli |
  234. | `codex_oauth` | In-process Codex OAuth refresh | Share `~/.codex/auth.json` with Codex CLI |
  235. `command` and `file` are not OAuth — they have no expiry awareness and never
  236. call out to a refresh endpoint. ccproxy reads them on every resolve; rotation
  237. happens out-of-band through whichever secret manager produced the value.
  238. `anthropic_oauth` and `google_oauth` extend the same form-encoded
  239. `AuthSource` base. `codex_oauth` follows Codex's ChatGPT auth-file schema: it
  240. reads `~/.codex/auth.json`, refreshes JWT access tokens through OpenAI's OAuth
  241. endpoint, atomically writes the updated token envelope, and stamps companion
  242. `ChatGPT-Account-ID` / `X-OpenAI-Fedramp` headers derived from the same file.
  243. A static API key for DeepSeek alongside an OAuth-refresh entry for Anthropic:
  244. ```yaml
  245. ccproxy:
  246. providers:
  247. anthropic:
  248. auth:
  249. type: anthropic_oauth
  250. file_path: ~/.claude/.credentials.json
  251. access_path: claudeAiOauth.accessToken
  252. refresh_path: claudeAiOauth.refreshToken
  253. expiry_path: claudeAiOauth.expiresAt
  254. header: authorization
  255. base_url: https://api.anthropic.com
  256. path: /v1/messages
  257. type: anthropic
  258. deepseek:
  259. auth:
  260. type: command
  261. command: "printenv DEEPSEEK_API_KEY"
  262. header: x-api-key
  263. base_url: https://api.deepseek.com
  264. path: /anthropic/v1/messages
  265. type: anthropic
  266. ```
  267. **Hook config**: hooks in each stage list are topologically sorted by
  268. `@hook(reads=..., writes=...)` dependency declarations and executed in parallel
  269. DAG order. Hooks can be parameterized:
  270. ```yaml
  271. hooks:
  272. outbound:
  273. - hook: ccproxy.hooks.some_hook
  274. params:
  275. key: value
  276. ```
  277. Per-request overrides via header: `x-ccproxy-hooks: +hook_name,-other_hook`.
  278. ### Sharing credentials with the Claude Code CLI
  279. If you also run the Claude Code CLI on the same machine, point ccproxy's
  280. `anthropic` provider at the CLI's own credential file. Both tools then read
  281. *and* write the same JSON, so a refresh from either side is visible to the
  282. other on the next read.
  283. ```yaml
  284. ccproxy:
  285. providers:
  286. anthropic:
  287. auth:
  288. type: anthropic_oauth
  289. file_path: ~/.claude/.credentials.json
  290. access_path: claudeAiOauth.accessToken
  291. refresh_path: claudeAiOauth.refreshToken
  292. expiry_path: claudeAiOauth.expiresAt
  293. header: authorization
  294. base_url: https://api.anthropic.com
  295. path: /v1/messages
  296. type: anthropic
  297. ```
  298. The four glom paths declare the file's schema (`{claudeAiOauth: {accessToken,
  299. refreshToken, expiresAt, ...}}`), so existing siblings the CLI maintains
  300. (`scopes`, `subscriptionType`, etc.) are preserved on write. The atomic
  301. write-back (tmpfile → fsync → rename → chmod 0600) keeps the file consistent
  302. even if both tools refresh concurrently.
  303. ## Hook Pipeline
  304. | Hook | Stage | Purpose |
  305. | --- | --- | --- |
  306. | `inject_auth` | inbound | Sentinel key (`sk-ant-oat-ccproxy-{provider}`) substitution from `providers` |
  307. | `extract_session_id` | inbound | Parses `metadata.user_id` → stores session_id on `ctx.metadata.session_id` |
  308. | `gemini_cli` | outbound | Single hook for Gemini sentinel-key traffic: `v1internal` envelope wrap, conditional UA masquerade, path rewrite to `cloudcode-pa`, and unwrap on the way back |
  309. | `pplx_stamp_headers` | outbound | Converts the Perplexity Pro sentinel token into the browser-shaped cookie/auth header bundle |
  310. | `inject_mcp_notifications` | outbound | Injects buffered MCP terminal events as synthetic tool_use/tool_result |
  311. | `verbose_mode` | outbound | Strips `redact-thinking-*` from `anthropic-beta` header |
  312. | `shape` | outbound | Replays a packaged or local shape and stamps content fields from the incoming request |
  313. | `commitbee_compat` | outbound | Last-mile compatibility shim for commitbee |
  314. ## Shape Replay
  315. Anthropic, Gemini, and Codex/OpenAI Responses traffic depend on shape replay.
  316. ccproxy ships sanitized packaged defaults for all three providers. For
  317. Anthropic, the shape is the only source of the Claude Code identity headers
  318. (user-agent, anthropic-beta, etc.) and the billing-header block — there is no
  319. synthetic-identity fallback hook anymore. For Codex, the packaged
  320. `openai_responses` shape carries only the public request envelope; account
  321. routing headers come from `codex_oauth` at runtime. Normal users do not need to
  322. capture a shape before using the packaged defaults. If a packaged shape goes
  323. stale for a future upstream SDK release, update ccproxy to a release with
  324. refreshed packaged defaults. If no fixed release is available yet, follow the
  325. manual rescue path in
  326. [Request Shaping](docs/shaping.md#manual-shaping-when-a-packaged-default-is-stale).
  327. Codex traffic is routed to ChatGPT's Codex backend, not the public OpenAI
  328. Responses endpoint. Use streaming Responses requests; ccproxy preserves the
  329. captured Codex instruction envelope, normalizes public SDK string input into
  330. Codex's verbose message form, and enforces `store: false`. Public Responses
  331. fields unsupported by the Codex backend, such as `max_output_tokens`, should be
  332. left unset for the default `codex` provider.
  333. ## CLI Reference
  334. ```bash
  335. ccproxy start # Start proxy and inspector stack (foreground)
  336. ccproxy run [--capture] -- <command> # Run command with proxy env vars / WireGuard namespace jail
  337. ccproxy status [--json] # Show running state
  338. ccproxy init [--force] # Initialize config in ~/.config/ccproxy/
  339. ccproxy logs [-f] [-n LINES] # View logs
  340. # Flow inspection (all commands accept repeatable --jq flow-set selectors)
  341. ccproxy flows list [--json] [--jq FILTER]... # List flow set
  342. ccproxy flows dump [--jq FILTER]... # Multi-page HAR of flow set
  343. ccproxy flows diff [--jq FILTER]... # Sliding-window diff across set
  344. ccproxy flows compare [--jq FILTER]... # Per-flow client-vs-forwarded diff
  345. ccproxy flows clear [--all] [--jq FILTER]... # Clear flow set (--all bypasses filters)
  346. # Shape artifacts
  347. ccproxy shapes audit [--directory PATH] # Audit packaged .mflow artifacts
  348. ccproxy shapes save PROVIDER [--jq FILTER]... # Advanced: write/update local shape patch
  349. ccproxy shapes save PROVIDER --mflow # Advanced: write request-only .mflow override
  350. ```
  351. `ccproxy run` (without `--capture`) sets `ANTHROPIC_BASE_URL`,
  352. `OPENAI_BASE_URL`, and `OPENAI_API_BASE` in the subprocess environment and
  353. routes traffic through the reverse proxy listener.
  354. `ccproxy run --capture` wraps the command in a rootless WireGuard network
  355. namespace jail — all outbound traffic is transparently intercepted regardless of
  356. SDK configuration.
  357. ## Inspecting Flows
  358. All `flows` subcommands operate on a resolved **set** of flows.
  359. The set is built by a pipeline:
  360. ```
  361. GET /flows → config default_jq_filters → CLI --jq filters → final set
  362. ```
  363. The `--jq` flag is repeatable.
  364. Each filter is a flow-set selector: it must consume a JSON array and produce one JSON array of flow
  365. objects.
  366. Multiple filters chain via jq’s `|` operator:
  367. ```bash
  368. # Only Anthropic API calls
  369. ccproxy flows list --jq 'map(select(.request.pretty_host == "api.anthropic.com"))'
  370. # Only POST /v1/messages
  371. ccproxy flows list --jq 'map(select(.request.path | startswith("/v1/messages")))'
  372. # Only paths containing /api/ws
  373. ccproxy flows list --jq 'map(select((.request.path // "") | contains("/api/ws")))'
  374. # Chain filters: Anthropic POSTs with 200 status
  375. ccproxy flows list \
  376. --jq 'map(select(.request.pretty_host == "api.anthropic.com"))' \
  377. --jq 'map(select(.request.method == "POST"))' \
  378. --jq 'map(select(.response.status_code == 200))'
  379. ```
  380. `--jq` is for selecting the flow objects that `list`, `dump`, `diff`, `compare`, `clear`, `repl`,
  381. and `shapes save` operate on. For arbitrary projections or reporting, emit JSON and pipe it to jq:
  382. ```bash
  383. ccproxy flows list --json | jq -r '.[].request.path | select(contains("/api/ws"))'
  384. ```
  385. Config-level defaults apply before CLI filters, so you can set a baseline in
  386. `ccproxy.yaml`:
  387. ```yaml
  388. flows:
  389. default_jq_filters:
  390. - 'map(select(.request.path | startswith("/v1/messages")))'
  391. ```
  392. ### Listing flows
  393. ```bash
  394. # Rich table (default)
  395. ccproxy flows list
  396. # Raw JSON
  397. ccproxy flows list --json
  398. # Filtered table
  399. ccproxy flows list --jq 'map(select(.request.path | startswith("/v1/messages")))'
  400. ```
  401. ```
  402. ┏━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
  403. ┃ ID ┃ Method ┃ Code ┃ Host ┃ Path ┃ UA ┃ Time ┃
  404. ┡━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━┩
  405. │ 3c9c224c │ POST │ 200 │ api.anth… │ /v1/mess… │ claude-… │ 42 seconds │
  406. │ │ │ │ │ │ (extern… │ ago │
  407. │ 6cc161e9 │ POST │ 200 │ api.anth… │ /v1/mess… │ claude-… │ 29 seconds │
  408. │ │ │ │ │ │ (extern… │ ago │
  409. └──────────┴─────────┴───────┴───────────┴───────────┴──────────┴──────────────┘
  410. ```
  411. ### Diffing consecutive requests
  412. `flows diff` performs a sliding-window unified diff over request bodies.
  413. For a set `[f0, f1, f2]`, it produces diffs `f0→f1` and `f1→f2`. Requires at
  414. least 2 flows.
  415. ```bash
  416. ccproxy flows diff --jq 'map(select(.request.path | startswith("/v1/messages")))'
  417. ```
  418. ```diff
  419. --- flow:3c9c224c
  420. +++ flow:6cc161e9
  421. @@ -26,7 +26,7 @@
  422. {
  423. "type": "text",
  424. - "text": "what's 2+2",
  425. + "text": "what's 3+3",
  426. "cache_control": {
  427. ```
  428. ### Comparing client vs forwarded requests
  429. `flows compare` diffs the pre-pipeline client request against the post-pipeline
  430. forwarded request for each flow.
  431. This shows what ccproxy’s hook pipeline and lightllm transform actually changed.
  432. Supports 1+ flows.
  433. ```bash
  434. ccproxy flows compare --jq 'map(select(.request.path | startswith("/v1/messages")))'
  435. ```
  436. When the pipeline rewrites the request (e.g. Anthropic → Gemini transform),
  437. you’ll see URL changes and body diffs:
  438. ```
  439. ╭──────── URL change — abc12345 ────────╮
  440. │ - https://api.anthropic.com/v1/messages│
  441. │ + https://generativelanguage.googleapi…│
  442. ╰───────────────────────────────────────╯
  443. ╭──────── Body diff — abc12345 ─────────╮
  444. │ --- client:abc12345 │
  445. │ +++ forwarded:abc12345 │
  446. │ @@ -1,5 +1,5 @@ │
  447. │ ... │
  448. ╰───────────────────────────────────────╯
  449. ```
  450. When no transform is applied (same-provider passthrough), the output confirms
  451. the bodies are identical:
  452. ```
  453. 3c9c224c: request bodies are identical.
  454. 6cc161e9: request bodies are identical.
  455. ```
  456. ### Dumping HAR
  457. `flows dump` exports the flow set as a multi-page HAR 1.2 file.
  458. Each flow becomes one page with two entries:
  459. | Entry | Content |
  460. | --- | --- |
  461. | `entries[2i]` | Forwarded request + upstream response |
  462. | `entries[2i+1]` | Client request (pre-pipeline snapshot) + upstream response |
  463. ```bash
  464. # Dump all flows to a HAR file (open in Chrome DevTools / Charles / Fiddler)
  465. ccproxy flows dump > all.har
  466. # Dump only LLM requests
  467. ccproxy flows dump --jq 'map(select(.request.path | startswith("/v1/messages")))' > llm.har
  468. # Query HAR with jq
  469. ccproxy flows dump | jq '.log.pages | length' # page count
  470. ccproxy flows dump | jq '.log.entries[0].request.url' # first forwarded URL
  471. ```
  472. ### Clearing flows
  473. ```bash
  474. # Clear only matching flows (respects --jq filters)
  475. ccproxy flows clear --jq 'map(select(.request.path | startswith("/v1/messages")))'
  476. # => Cleared 2 flow(s).
  477. # Clear everything (bypasses all filters)
  478. ccproxy flows clear --all
  479. ```
  480. ## Development
  481. ```bash
  482. git clone https://github.com/starbaser/ccproxy.git
  483. cd ccproxy
  484. direnv allow # activates the nix devShell
  485. just up # start dev services (process-compose, detached, port 4001)
  486. just down # stop dev services
  487. just test # uv run pytest
  488. just lint # uv run ruff check .
  489. just fmt # uv run ruff format .
  490. just typecheck # uv run mypy src/ccproxy
  491. ```
  492. The dev instance runs on port 4001 (production default: 4000). Inspector UI at
  493. port 8083. Config and cert store at `.ccproxy/` inside the project directory.
  494. ## Troubleshooting
  495. ### Inspector prerequisites
  496. See [Installation](#installation) for the per-distro system package list.
  497. `ccproxy run --capture` checks `slirp4netns`, `wg`, `unshare`, `nsenter`, `ip`
  498. on `PATH` and prints the missing ones with package hints. The reverse proxy
  499. (`ccproxy start`) does not require any of these and works on macOS too.
  500. ### Auth token errors
  501. Auth tokens are loaded at startup from each `providers[name].auth` source. If
  502. a token command fails or returns an empty string, the sentinel key substitution
  503. is skipped and the raw sentinel key is forwarded — which will be rejected by
  504. the provider.
  505. Verify your token command works standalone:
  506. ```bash
  507. jq -r '.claudeAiOauth.accessToken' ~/.claude/.credentials.json
  508. ```
  509. OAuth-source providers (`anthropic_oauth`, `google_oauth`) refresh in-process
  510. via `AuthSource.resolve()` whenever the cached access token is within 60s of
  511. expiry — this fires at startup (`_load_credentials()`) and on each header
  512. injection. On a 401 from upstream, `AuthAddon` re-resolves the credential
  513. source and replays the request with the new token. Static `command` / `file`
  514. loaders have no refresh capability — they read whatever's on disk every time
  515. and rely on whichever secret manager owns rotation. Fix your `providers`
  516. entries and restart `ccproxy start` if static tokens were stale at startup.
  517. ### TLS certificate errors in `ccproxy run`
  518. `ccproxy run` (without `--capture`) does not intercept TLS. It only sets env
  519. vars pointing at the reverse proxy HTTP listener.
  520. If the target tool performs its own TLS verification against the upstream API,
  521. no cert installation is needed.
  522. `ccproxy run --capture` intercepts all traffic including TLS. The mitmproxy CA
  523. is combined with system CAs and injected via `SSL_CERT_FILE`,
  524. `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, and `CURL_CA_BUNDLE` into the
  525. subprocess environment automatically.
  526. If a tool still fails certificate verification, ensure the mitmproxy CA
  527. (`~/.config/ccproxy/mitmproxy-ca-cert.pem`) is trusted by the tool’s runtime.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.