ccxray

English | 正體中文 | 日本語

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.

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

npx ccxray claude

That'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.

Other ways to run

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   # Manual setup (existing sessions)

Multi-project

Running 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:5577

If the hub process crashes, connected clients automatically recover within seconds.

$ ccxray status
Hub: http://localhost:5577 (pid 12345, uptime 3600s, v1.1.0)
Connected clients (2):
  [1] pid 23456 — ~/dev/project-a
  [2] pid 34567 — ~/dev/project-b

Use --port to opt out and run an independent server instead.

Features

Timeline

Watch your agent think in real-time. Every turn broken down into thinking blocks (with duration), tool calls with inline previews, and assistant responses.

Usage & Cost

Track your real spending. Session heatmap, burn rate, ROI calculator — know exactly where your tokens go.

System Prompt Tracking

Automatic version detection with diff viewer. Browse system prompts across all agent types — main agent, subagents (Explore, Web Search, etc.) — and see exactly what changed between updates.

More

• 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

How It Works

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 unchanged, 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.

Configuration

CLI flags

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

Environment variables

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)
ANTHROPIC_BASE_URL	—	Custom upstream Anthropic endpoint (e.g. a corporate gateway). ccxray reads this at startup and forwards to it instead of api.anthropic.com. 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

docker build -t ccxray .
docker run -p 5577:5577 ccxray

Requirements

• Node.js 18+

Also by the author

• SourceAtlas — Your map to any codebase
• AskRoundtable — Make your AI think like Munger, Feynman, or Paul Graham
• Follow @lis186 on X for updates

License

MIT