ccxray

ccxray

English | 正體中文 | 日本語

X-ray vision for AI agent sessions. A zero-config HTTP proxy that records every API call between Claude Code, Codex, and their upstream APIs, with a real-time dashboard and workflow timeline to inspect what's actually happening inside your agent.

Why

Claude Code is a black box. You can't see:
- What system prompts it sends (and how they change between versions)
- How much each tool call costs
- Why it's thinking for 30 seconds
- What context is eating your 200K token window

ccxray makes it a glass box.

Quick Start

The proxy starts, the selected CLI launches through it, and the dashboard opens automatically. On macOS and Linux, agent launches without --port share one hub and dashboard. Windows runs each launch as its own standalone server; see the example below.

If ccxray cannot load the proxy or attach to a hub, it starts the agent directly and that session is not recorded. The hub attach budget is 3000 ms by default; an unresolved attach falls back when the budget expires, and an earlier failure can fall back sooner. Set CCXRAY_ATTACH_TIMEOUT_MS to change the budget. ccxray attempts to append a fallback record to /fail-open.log (default ~/.ccxray/fail-open.log), but writing that file is best effort. Set CCXRAY_FAIL_CLOSED=1 to stop instead of falling back. Claude --bg / --background launches bypass the proxy by design.

For a persistent install with Claude's shell wrapper (local recording only):

Plain ccxray setup writes no export settings and needs no bucket, domains, or gcloud credentials. Summary export to GCS is opt-in with --export. Before using it, install Claude Code and make sure its logged-in account email is available to ccxray. The --domains list must include that account's domain. Export setup also requires readable…