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 claude
# or
npx ccxray codexThat's it. Proxy starts, the selected CLI launches through it, and the dashboard opens automatically in your browser. Run it in multiple terminals — they automatically share one dashboard.
The launcher argument is provider-backed. Today claude and codex are supported; unknown provider commands fail fast instead of silently starting an unconfigured proxy.
ccxray # Proxy + dashboard only
ccxray claude --continue # All claude args pass through
ccxray codex exec "hello" # All codex 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)
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 multiple recognized agent types and see exactly what changed between updates. 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.
Inside the timeline, step-type jump shortcuts let you scan sessions instantly: e/E jumps to the next/previous error, s/S to Skill calls, a/A to subagent (Agent/Task) calls, m/M to MCP tool calls. Each jump is position-aware — it finds the nearest match forward or backward from wherever you are, and updates the address bar URL.
n/N jumps to the next/previous starred item anywhere in the dashboard — across projects, sessions, turns, and individual timeline steps. The command bar shows the shortcut only when starred items are reachable from the current view.
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.
Pause requests before they reach Anthropic. Toggle intercept on a session and the next request from Claude Code is held in the dashboard — edit the system prompt, messages, tools, or sampling parameters, then approve (forwards your edited copy) or reject (returns an error to Claude Code). Useful for prompt engineering, sandboxing risky tool calls, and running experiments without forking the agent.
Optional context-stats footer appended to Claude's responses inside Claude Code itself: 📊 Context: 28% (290k/1M) | 1k in + 800 out | Cache 99% hit | $0.15. Enabled by default; toggle from the dashboard topbar.
Why a toggle? When the parent agent calls sub-agents (Agent / Task tool), the appended block can truncate the sub-agent's response before it's returned to the parent — causing silent data loss in multi-agent workflows. Turn the HUD off when running sub-agent-heavy sessions. State persists in ~/.ccxray/settings.json.
Click the star on a turn, session, or project card to mark it for permanent retention. Starred items survive LOG_RETENTION_DAYS auto-prune; state lives in ~/.ccxray/settings.json, server-side and persistent across browsers. A starred turn protects every turn in its session; a starred session protects every turn under it; a starred project protects everything beneath. Catch-all buckets (direct-api, (unknown), (quota-check)) refuse stars at the bucket level — star individual turns inside instead.
Individual timeline steps can also be starred (★/☆ toggle on each step row). A starred step protects its parent turn and session identically to a direct turn star.
When a parent inherits protection from a starred descendant, the badge becomes ☆ [N] instead of ★. Click the chip to open a popover listing exactly which descendants are keeping it retained. Each row's star is its own toggle; clicking the row body navigates straight to that turn / session.
- Deep Link Navigation — Every selection (project / session / turn / step) is reflected in the address bar URL. Paste a URL into a new tab and the dashboard navigates directly to the same view.
- 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) |
LOG_RETENTION_DAYS |
14 |
Auto-prune log files older than N days on startup. Starred turns / sessions / projects (and everything beneath them) are protected, as are files referenced by restored entries. Set to 0 to disable. |
RESTORE_DAYS |
0 |
Limit which days of logs to load on startup (0 = all, subject to CCXRAY_MAX_ENTRIES). Useful for very large log directories. |
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.
Set STORAGE_BACKEND=s3 to write logs to S3-compatible storage (AWS S3, Cloudflare R2, MinIO) instead of local disk. Requires @aws-sdk/client-s3 to be installed.
| Variable | Default | Description |
|---|---|---|
STORAGE_BACKEND |
local |
local or s3 |
S3_BUCKET |
(required) | Bucket name |
S3_REGION |
auto |
Region (use auto for R2) |
S3_ENDPOINT |
(unset) | Custom endpoint URL (R2 / MinIO) |
S3_PREFIX |
logs/ |
Key prefix inside the bucket |
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