ctxray

Universal context inspection and routing diagnostics for agentic LLM clients.

ctxray is a schema-first toolkit for answering one question with evidence:

What exactly did this agent request send, why did it route that way, and where did the context budget go?

The project starts with contracts before runtime code. The first milestone is a shared envelope that can represent:

• proxy/router requests from Claude Code Router, LiteLLM-compatible gateways, and custom model routers
• CLI transcripts from agentic coding clients
• repository context packs
• MCP and plugin tool catalogs
• model catalogs and route policies
• redacted analysis reports safe enough to attach to tickets

Current Status

The local runtime is implemented: capture adapters, the five analyzers, redaction, model-fit simulation, and a ctxray CLI that renders text / JSON / ticket-safe markdown. Schemas remain the contracts; everything is local-first and adds no runtime dependencies.

Quick Start

node src/cli/ctxray.mjs help   # list commands, options, and exit codes

npm test          # run the test suite
npm run validate  # parse schemas and example fixtures

# Inspect a raw capture (router request, transcript, tool catalog, repo pack)
# into a normalized, metadata-only envelope:
node src/cli/ctxray.mjs inspect <capture.json> > envelope.json

# Diagnose an envelope (budget, tools, route, privacy, composition):
node src/cli/ctxray.mjs doctor envelope.json --models examples/model-catalog.json

# Other commands:
node src/cli/ctxray.mjs redact <capture.json> --policy examples/redaction-policy.json --out safe.json
node src/cli/ctxray.mjs route simulate envelope.json --models examples/model-catalog.json
node src/cli/ctxray.mjs tools top envelope.json
node src/cli/ctxray.mjs report analysis-report.json --format markdown

Exit codes: 0 ok · 1 blocking findings · 2 invalid input · 3 unsafe output without redaction · 4 adapter detection failed.

Recipes

Audit how much context your MCP tools eat

A connected MCP server injects every tool's name, description, and input schema into the model's context on every turn. To see the weight, save the server's tools/list response as { "tools": [ { "name", "description", "inputSchema" }, … ] } (under the gitignored captures/), then:

node src/cli/ctxray.mjs inspect captures/tools.json > captures/tools.envelope.json
node src/cli/ctxray.mjs doctor captures/tools.envelope.json

doctor reports per-tool token estimates and flags composition.tool_schema_dominant when schemas dominate the context — the signal for trimming or lazy-loading tools. The envelope is metadata-only (no descriptions or schema literals are stored), so it is safe to share. Token counts are a char_heuristic estimate, not a real tokenizer — treat them as relative weights, not exact counts.

Key Documents

• Product brief
• Architecture
• Unified schema
• Adapter contracts
• CLI contract
• Privacy and redaction
• Evaluation strategy
• Roadmap
• Agent instructions

Design Center

ctxray should be boringly inspectable:

1. Capture final payloads and derived context envelopes.
2. Explain token, tool, route, and model-budget decisions.
3. Redact before writing or sharing.
4. Simulate alternatives without mutating user state.
5. Keep adapters small and schemas stable.

Non-Goals For The First Runtime

• It will not be another repo packer.
• It will not require a hosted service.
• It will not upload prompts by default.
• It will not make routing changes automatically.
• It will not depend on a single agent client.