X-ray vision for AI agent sessions. A zero-config HTTP proxy that records every API call between Claude Code and Anthropic, with a real-time dashboard to inspect what's actually happening inside your agent.
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.
npx ccxray claudeThat's it. Proxy starts, Claude Code launches through it, and the dashboard opens automatically in your browser. Run it in multiple terminals — they automatically share one dashboard.
ccxray # Proxy + dashboard only
ccxray claude --continue # All claude args pass through
ccxray --port 8080 claude # Custom port (independent, no hub sharing)
ccxray claude --no-browser # Skip auto-open browser
ccxray status # Show hub info and connected clients
ANTHROPIC_BASE_URL=http://localhost:5577 claude # Point existing claude session at a running ccxray hubRunning ccxray claude in multiple terminals automatically shares a single proxy and dashboard — no configuration needed.
# Terminal 1
cd ~/project-a && ccxray claude # Starts hub + claude
# Terminal 2
cd ~/project-b && ccxray claude # Connects to existing hub
# Both projects visible in one dashboard at http://localhost:5577If the hub process crashes, connected clients automatically recover within seconds.
$ ccxray status
Hub: http://localhost:5577 (pid 12345, uptime 3600s, v1.6.0)
Connected clients (2):
[1] pid 23456 — ~/dev/project-a
[2] pid 34567 — ~/dev/project-bUse --port to opt out and run an independent server instead.
Watch your agent think in real-time. Every turn renders as a five-line card: cost on line 1, cache warmth (with inter-turn gap timing to catch cache misses), tool-fail risk, hit:0% red warnings, and tools surfaced above the title. Scan a whole session's health without expanding a single card.
Track your real spending. Session heatmap, burn rate, ROI calculator — know exactly where your tokens go.
Automatic version detection with diff viewer. Browse prompts across 12 recognized agent types — Orchestrator, General Purpose, Plan, Explore, Web Search, Codex Rescue, Claude Code Guide, Summarizer, Title Generator, Name Generator, Translator, SDK Agent — and see exactly what changed between updates. Precision-verified against 12,730 captured prompts: 100% of classifications are correct, uncertain prompts are honestly marked unknown.
Drive the whole dashboard with your keyboard. Every screen shows a context-sensitive hint bar at the bottom — the currently valid shortcuts, live-updated as you move. Press ? for the full cheatsheet. Navigate projects → sessions → turns → sections → timeline → individual diff hunks without touching the mouse.
Session cards show Claude Code's generated titles (e.g. Fix login button on mobile) instead of raw hashes, with a live cache TTL countdown (cache 4m left) that pulses red under 1 minute. When any session nears expiry, the browser tab alternates between ccxray and ⚠ ccxray. Opt-in browser notification fires at a plan-aware lead time — 5 minutes for Max, 60 seconds for Pro/API key. Titles fall back to the short hash for direct-API traffic or sessions still in flight.
ccxray auto-detects your subscription plan (Pro vs Max 5x vs Max 20x) by reading Anthropic's cache_creation usage fields — no configuration needed. Topbar shows Plan: Max 5x · TTL 1h (auto). ROI calculations and quota panel use the detected plan. Override with CCXRAY_PLAN if auto-detection gets it wrong.
- Session Detection — Automatically groups turns by Claude Code session, with project/cwd extraction
- Token Accounting — Per-turn breakdown: input/output/cache-read/cache-create tokens, cost in USD, context window usage bar
Claude Code ──► ccxray (:5577) ──► api.anthropic.com (or ANTHROPIC_BASE_URL)
│
▼
~/.ccxray/logs/ (JSON)
│
▼
Dashboard (same port)
ccxray is a transparent HTTP proxy. It forwards requests to Anthropic, records both request and response as JSON files, and serves a web dashboard on the same port. No API key needed — it passes through whatever Claude Code sends.
| Flag | Description |
|---|---|
--port <number> |
Port for proxy + dashboard (default: 5577). Opts out of hub sharing. |
--no-browser |
Don't auto-open the dashboard in your browser |
| Variable | Default | Description |
|---|---|---|
PROXY_PORT |
5577 |
Port for proxy + dashboard (overridden by --port) |
BROWSER |
— | Set to none to disable auto-open |
AUTH_TOKEN |
(none) | API key for access control (disabled when unset) |
CCXRAY_HOME |
~/.ccxray |
Base directory for hub lockfile, logs, and hub.log |
CCXRAY_MAX_ENTRIES |
5000 |
Max in-memory entries (oldest evicted; disk logs unaffected) |
CCXRAY_PLAN |
(auto) | Override plan detection: pro, max5x, max20x, api-key |
CCXRAY_DISABLE_TITLES |
(unset) | Set to 1 to disable session title extraction (sessions fall back to short hash) |
CCXRAY_MODEL_PREFIX |
(unset) | Prepend a string to the model name before forwarding (e.g. databricks-). Useful when the upstream requires a vendor-prefixed model name but Claude Code only accepts standard names. |
HTTPS_PROXY / https_proxy |
(unset) | Route outbound HTTPS traffic through a corporate proxy via HTTP CONNECT tunnel. |
ANTHROPIC_BASE_URL |
— | Custom upstream Anthropic endpoint (e.g. a corporate gateway). Supports base paths — https://host/serving-endpoints/anthropic works as-is. ANTHROPIC_TEST_* take precedence when set. |
Logs are stored in ~/.ccxray/logs/ as {timestamp}_req.json and {timestamp}_res.json. Upgrading from v1.0? Logs previously in ./logs/ are automatically migrated on first run.
docker build -t ccxray .
docker run -p 5577:5577 ccxray- Node.js 18+
- SourceAtlas — Your map to any codebase
- AskRoundtable — Make your AI think like Munger, Feynman, or Paul Graham
- Follow @lis186 on X for updates
MIT