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.
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.
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. / {timestamp}_res. 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
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 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.