ccxray
X-ray vision for AI agent sessions — a zero-config proxy that records every Claude Code / Codex API call, turning the black box into a glass box.
- Source repo
- lis186/ccxray
- Stars
- ★ 295
- Last updated
- 2d ago
- License
- NOASSERTION
- Primary language
- JavaScript
- FA score
- 73/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude Code · Claude APICodex · OpenAI API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer who wants to know why Claude Code thinks for 30 seconds, what each tool call costs, and how system prompts change between versions
- Not a fit if
- Teams needing commercial use — the PolyForm Noncommercial licence forbids it
- Teams that need logs in remote object storage like S3/R2 — local filesystem only
- Teams needing fully reliable Codex turn detail — Codex support is Beta
- Source review
- 73/100 · Some gaps
What does this agent do, and when should you use it?
ccxray is a zero-config local HTTP proxy and real-time dashboard that intercepts and records every request and response between Claude Code, Codex, Grok CLI and their upstream APIs. Running npx ccxray claude starts a proxy on port 5577, routes CLI traffic through it, writes JSON logs into ~/.ccxray/logs/, and serves a dashboard on the same port with a workflow timeline, cost tracking, and system-prompt version diffing. Multiple terminals automatically share one hub, and clients recover within seconds if the hub crashes. It also supports intercepting and editing requests before they reach the API, an in-CLI context HUD, cache TTL countdown alerts, and star-based permanent retention. Licensed under PolyForm Noncommercial 1.0.0 — noncommercial use only.
ccxray runs as a transparent HTTP proxy: launchers like npx ccxray claude / codex / grok route traffic through :5577 to api.anthropic.com, api.openai.com/ChatGPT, or cli-chat-proxy.grok.com, while writing each exchange as {timestamp}_req.json / {timestamp}_res.json under ~/.ccxray/logs/. The dashboard on the same port provides a Workflow Timeline with per-agent parallel lanes, per-turn cost and token breakdowns, system-prompt version diffs with an uncertain-prompt unknown marker, cache TTL countdown alerts, per-account 5-hour/weekly quota cards, and CLI analytics via ccxray usage --. An intercept mode can pause a request before it reaches the upstream, letting you edit the system prompt, messages, tools, or sampling parameters, then approve or reject. Logs auto-prune after 14 days (LOG_RETENTION_DAYS); starred items are kept forever.
- A developer who wants to know why Claude Code thinks for 30 seconds, what each tool call costs, and how system prompts change between versions
- A team lead who needs per-account visibility into Claude/Codex 5-hour and weekly quota usage and real spending
- A prompt engineer who wants to modify the system prompt or tool definitions of a live request before it hits the API
- A developer running sessions in multiple terminals across projects who wants everything in one shared dashboard
- A heavy multi-agent user who wants to see the concurrency structure of orchestrator and subagent turns as parallel lanes
How do you install or deploy this agent?
Requires Node.js 18+; no separate install step — run via npx:
bash
npx ccxray claudeThe first run creates ~/.ccxray/ (logs, settings, and the local-secret auth key). Alternatively use Docker:
bash
docker build -t ccxray .
docker run -p 5577:5577 ccxrayFor Herdr integration:
bash
herdr plugin install lis186/ccxray/plugins/herdrHow do you use this agent?
bash
npx ccxray claude # start proxy and auto-open dashboard
npx ccxray codex exec "hello" # any codex args pass through
npx ccxray --port 8080 claude # independent server, no hub sharing
ccxray status # show hub info and connected clients
ccxray usage -- --last 7d # agent-facing JSON usage report
ccxray usage --session costliest --open # jump to costliest sessionThe dashboard opens automatically at http://localhost:5577. Multiple terminals share one hub automatically. Tune behavior with env vars such as CCXRAY_PLAN, ANTHROPIC_BASE_URL, and LOG_RETENTION_DAYS; toggle Intercept mode or the Context HUD from the dashboard topbar.
What are this agent's strengths and limitations?
- Zero-config: a single npx command yields proxy, logging, and a live dashboard with no env changes
- Parallel lane visualization with a sequential-vs-concurrent interleave tracker — a rare session-structure view
- Requests can be intercepted and edited before reaching the API, useful for prompt experiments and sandboxing risky tool calls
- The ccxray usage CLI reads index.nd directly and produces an agent-facing JSON report (< 4KB) in 0.6 seconds without a server
- Star mechanism protects key turns/sessions/projects from the 14-day auto-prune, persisted server-side
- PolyForm Noncommercial 1.0.0 license prohibits commercial use
- Codex support is Beta: per-frame WebSocket decoding stores some large events only as timing anchors, so turn detail can trail the Claude path
- Logs are local-filesystem only; remote object storage (S3/R2) is not supported yet
- Proxying Grok calls cli-chat-proxy.grok.com/v1/billing with the CLI's auth token to populate the Usage card — an extra upstream call
- The Context HUD can truncate a sub-agent's response before it returns to the parent, causing silent data loss in multi-agent workflows unless toggled off
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| ccxray This agent | 73 · Some gaps | CLIFree + model costs | ★ 295 | 2d ago | JavaScript | Claude Code · Claude API |
| ccusage | 67 · Some gaps | — | ★ 19k | today | Rust | Codex · Claude Code |
| Claude Tap Local Trace Viewer | 53 · Major gaps | CLIFree | ★ 3.3k | 5d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| ccglass | 74 · Some gaps | CLIFree + model costs | ★ 851 | 14d ago | JavaScript | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: local loopback proxy, one runtime dependency (ws), unknown provider commands fail fast, auth via one-time bootstrap tokens plus HttpOnly/SameSite=Strict cookies, with tests covering replay and cross-site rejection. Deducted for: loopback trusted without auth by default (SECURITY.md itself states this is not an authentication boundary), plaintext JSON logs of full prompts and upstream traffic, an extra billing-API call reusing the same Grok auth token (disclosed but still an extra external effect), no version rollback path, and retention pruning that relies on opt-in stars to preserve data.
Evidence shows: CI runs a Node 20/22 matrix with isolated CCXRAY_HOME, the count_tokens false-entry fix has an e2e regression test, the auth module has thorough rejection-path tests, and unknown providers fail fast. Deducted for: hub crash auto-recovery is asserted only in the README with no supporting source or test in evidence; referenced docs (usage.md, CHANGELOG, CLAUDE.md) are absent from the evidence set.
Evidence shows: a clearly defined audience (developers debugging Claude Code/Codex/Grok), multi-project hub sharing, Docker, corporate proxy, and custom upstreams. Deducted for: Codex support is self-labeled Beta with lower fidelity than the Claude path; the weather feature ships disabled due to a known defect; only three provider commands are registered.
Evidence shows: trilingual README, full PolyForm Noncommercial license text consistent with package., version 2.3.1 matching both sides, complete install and configuration tables, and a SECURITY.md with reporting channels that candidly states single-maintainer status. Deducted for: a CHANGELOG is referenced but not present in evidence, so changelog quality cannot be verified; no formal governance or multi-maintainer mechanism.
Evidence shows: the product is itself a transparency layer addressing the real gap of Claude Code's black box, with timeline, cost accounting, a usage CLI (with a <4KB JSON contract and schema doc), keyboard navigation, and deep links. Deducted for: the Context HUD can truncate sub-agent responses in multi-agent workflows (acknowledged in docs), and the proxy adds a hop plus local storage overhead whose cost the user must weigh.
Evidence shows: tests map directly to the #486 fix, count_tokens noise suppression, and an auth bootstrap regression; the split audit job is explained by a concrete incident; uncertain items are honestly labeled (unknown prompts, Beta scope). Deducted for: performance and behavior claims (0.6s analysis, hub recovery) rest on documents not attached, and a static review cannot execute verification.
- The proxy records full prompts, tool calls, and upstream responses as plaintext JSON in ~/.ccxray/logs/ — potentially sensitive commercial content; ensure disk encryption and be aware of the default 14-day LOG_RETENTION_DAYS pruning.
- Loopback connections are trusted without auth by default; on shared or high-risk machines set CCXRAY_LOOPBACK_REQUIRE_AUTH=1 (SECURITY.md itself recommends this).
- The Grok path reuses the CLI's auth token to call a billing endpoint; if this extra egress is unwanted, evaluate XAI_BASE_URL or avoid proxying Grok traffic.
- Codex support is Beta with lower fidelity than the Claude path; the weather feature ships disabled due to a known defect and requires ?weather=on.
- The Context HUD can truncate sub-agent responses in sub-agent-heavy workflows; disable the HUD in those scenarios.
- License is PolyForm Noncommercial 1.0.0 — commercial use is prohibited; obtain legal review before enterprise adoption; publisher identity is unverified by the curated registry.
- This is a static source review (low confidence) with no executed verification; referenced documents such as CHANGELOG and usage.md were not in the evidence set.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v2.5.0-rc.3 Pre-release
Release notes excerpt
Release candidate for 2.5.0 — published to npm under the next dist-tag; latest stays on 2.3.1. Install: npm install -g [email protected] SHA256 (ccxray-2.5.0-rc.3.tgz): 138684b90f94e64de8d95525bf97de5edbd29f7dbe2866c78e0d6a91eea717b7 204 non-merge commits since 2.3.1. Three headlines: ccxray adds optional GCS summary export and one-step setup; session, cost, and context data become more accurate and diagnosable; and launcher reliability, status reporting, and agentflow usage reports improve. Added …View on GitHub ↗ -
v2.3.1 v2.3.1 — Weather display toggle
Release notes excerpt
Changed - Weather display off by default (#484, PR #488). The tool-failure signals (stuck, error_cluster, error_cumulative, tool_failure) are unreliable across all data paths — cumulative inflation on Anthropic proxy, absent fields on imported data, decoder defects on OpenAI wire. Weather computation and persistence continue running; only the six render sites are hidden behind a localStorage tri-state toggle (default OFF). Append ?weather=on to inspect. See docs/weather.md § Display toggle for details. …View on GitHub ↗ -
v2.0.0 v2.0.0 — Workflow timeline, enforced auth, per-session entry cap
Release notes excerpt
Two domain shifts in one release: enforced auth on all endpoints (breaking for direct /v1/* callers), and a full workflow-timeline view that visualizes agent concurrency, sequential interleaving, and multi-model sessions. Highlights Workflow Timeline (new) - Sequential-interleave tracker with R1/R2 pre-numbering - Parallel-lane inference: orchestrator + Fork/Teammate lanes - Lane identity routing via coreHash + convId - WCAG ≥3:1 lane color pool (light + dark) - Birdseye overview mode (magnified minimap) - Adaptive overview height (viewport-proportional) …View on GitHub ↗