{"slug": "ctxray-see-and-lock-what-codex-loads-before-a-task", "title": "CtxRay – see and lock what Codex loads before a task", "summary": "CtxRay, a local-first observability and control layer for OpenAI Codex, launched with benchmark results showing a 73.3% reduction in estimated model-visible prompt and a 29.1% reduction in exact aggregate turn tokens across 10 paired tasks. The tool, which requires no API key and has no telemetry, provides commands for auditing context, compiling profiles, detecting drift, and generating usage receipts. A second maintainer run measured a 28.5% exact aggregate reduction across nine pairs, though the project notes these are bounded microbenchmark results, not universal claims.", "body_md": "**The local-first observability and control layer for OpenAI Codex.**\n\nAudit context, compile intentional profiles, catch configuration drift, and attach honest usage receipts.\n\n[ Install](#quick-start) ·\n\n[·](/FramY2/ctxray/blob/main/benchmarks/demo/ctxray-demo.mp4)\n\n**20-second demo**[·](/FramY2/ctxray/blob/main/benchmarks/results/2026-08-09-v1/report.md)\n\n**Benchmark evidence**\n\n**Reproduce it** CtxRay is a local-first CLI and Codex plugin for context diagnostics, safe profile compilation, drift detection, reproducibility lockfiles, and honest post-turn usage receipts. It calls no model of its own, requires no API key, and has no telemetry.\n\nCommunity project. Not affiliated with or endorsed by OpenAI.\n\nThe demo uses the public benchmark and the shipped CLI behavior. Click it for\nthe compact MP4, or use the [square social cut](/FramY2/ctxray/blob/main/benchmarks/demo/ctxray-demo-square.mp4).\n\n| You should not have to... | CtxRay gives you... |\n|---|---|\n| Guess which skills, instructions, plugins, or MCPs load | A private audit and bounded context map |\n| Hand-edit model profiles and hope the change is reversible | Reviewable YAML, native Codex TOML, dry-runs, and automatic backups |\n| Discover context changes only after a worse or costlier run | A redacted lockfile plus a CI-ready drift check |\n| Confuse token estimates, subscription quota, and API bills | Receipts that label exact, estimated, comparison, and unknown data |\n\nThe first public microbenchmark ran 10 paired tasks across requested GPT-5.6\nLuna, Terra, and Sol profiles: **20/20 answers passed the same exact validator**.\nRemoving irrelevant discovered context reduced the estimated model-visible\nprompt by **73.3%** and exact aggregate turn tokens by **29.1%**. Every pair\nholds task, requested model, effort, sandbox, commit, and quality gate constant.\n\nThese are bounded microbenchmark results, not a universal productivity claim.\nThe runtime stream records the requested profile but does not independently\nattest the served model, and prompt size remains a character-based estimate.\nRead the [method and limitations](/FramY2/ctxray/blob/main/benchmarks/results/2026-08-09-v1/report.md),\ninspect the [machine-readable summary](/FramY2/ctxray/blob/main/benchmarks/results/2026-08-09-v1/summary.json),\nor watch the [20-second MP4](/FramY2/ctxray/blob/main/benchmarks/demo/ctxray-demo.mp4).\n\nA second maintainer run measured a conservative **28.5%** exact aggregate\nreduction across nine comparable pairs and exposed a stale package-name\nvalidator. The raw [repeat run and erratum](/FramY2/ctxray/blob/main/benchmarks/results/2026-08-09-v2/ERRATUM.md)\nare public; it is evidence of repeatability and fixture hardening, not an\nindependent community reproduction.\n\nCodex already exposes excellent runtime primitives such as `/status`\n\n, `/usage`\n\n,\n`/statusline`\n\n, `codex exec --json`\n\n, profile files, and the app-server. The hard\npart is connecting them into one answer:\n\n- Which instructions, skills, plugins, agents, and MCP declarations are active?\n- Is a large context intentional or accidental?\n- Which model/subagent profile should this task use?\n- Can another developer reproduce the same capability surface safely?\n- Was a dollar amount actually billed, or is it merely an API comparison?\n\nCtxRay does that glue work without becoming another chat wrapper.\n\n| Command | What it does | Network/model call |\n|---|---|---|\n`ctxray audit` |\nInventories Codex config layers, guidance, skills, plugins, agents, and MCP declarations | None |\n`ctxray map` |\nRenders a bounded Mermaid map of context sources and discovery overhead | None |\n`ctxray xray` |\nSummarizes model-visible prompt JSON without echoing its text | None |\n`ctxray profile` |\nCompiles YAML into native `~/.codex/<name>.config.toml` , with dry-run and backups |\nNone |\n`ctxray lock` |\nHashes a redacted capability surface for reproducibility | None |\n`ctxray drift` |\nCompares a capability lock with a file or live setup; can fail CI on drift | None |\n`ctxray quota` |\nReads the current plan and quota window through local Codex app-server | Codex account read only |\n`ctxray receipt` |\nCalculates a receipt from saved `codex exec --json` usage |\nNone |\n`ctxray run` |\nRuns Codex and appends exact usage plus an optional pre-turn prompt X-Ray | The requested Codex turn |\n\nThe dollar display is deliberately asymmetric:\n\n| Authentication | Default display | Dollar meaning |\n|---|---|---|\n| OpenAI API key | Exact runtime tokens + dated API estimate | Estimated billable API charge |\n| ChatGPT Plus/Pro/Business | Tokens + credit equivalent + quota snapshot | No dollar amount |\nSubscription with `--api-equivalent` |\nSame data + API comparison | Comparison only; not charged |\n\nCtxRay never calls included subscription usage “money spent”. OpenAI states\nthat ChatGPT credits have no cash value, so CtxRay does not invent a universal\ncredit-to-dollar conversion. See [Cost semantics](/FramY2/ctxray/blob/main/docs/cost-semantics.md).\n\nRequires Node.js 20 or newer and a working Codex CLI installation.\n\n```\nnpm install --global @framy2/ctxray\nctxray doctor\nctxray audit\nctxray map --out ctxray-context.mmd\nctxray lock\nctxray drift --fail-on-drift\n```\n\nIf `ctxray doctor`\n\nreports that Codex is unavailable, install the official CLI\nwith `npm install --global @openai/codex`\n\n. On Windows, do not rely on directly\nexecuting the private binary inside the packaged desktop app. CtxRay detects the\npublic npm launcher automatically.\n\nGitHub renders the generated Mermaid file locally. Labels contain only the\nmetadata already returned by `audit`\n\n, not prompt text or config values. The\nheadline is a **known startup estimate**: `AGENTS.md`\n\ntext and skill discovery\nmetadata are counted; configuration files are marked as metadata, not falsely\ntreated as prompt text.\n\n```\nctxray run --receipt --prompt-xray --model gpt-5.6-terra \"Review the current diff\"\n```\n\nExample output:\n\n```\nFake answer...\nCtxRay receipt · prompt ≈ 1,003 / 1,050,000 (0.1%) · 10,000 input (8,000 cached) + 500 output · credit equivalent ≈ 0.29 · quota 37% used · rates 2026-08-08\n```\n\nFor a subscription-only API comparison, opt in explicitly:\n\n```\nctxray run --receipt --prompt-xray --api-equivalent --model gpt-5.6-terra \"Review the current diff\"\n```\n\n`--prompt-xray`\n\nasks Codex's experimental local debug command to render the\nmodel-visible input before the turn; CtxRay converts its character count into\nan explicitly estimated token value. The consumed input/output counters come\nseparately from `turn.completed`\n\nand may aggregate several model calls. The\nfooter itself is rendered locally after completion and consumes no model\ntokens.\n\nCapture the experimental Codex diagnostic, then analyze the saved JSON:\n\n```\ncodex debug prompt-input \"Review this repository\" > prompt-input.json\nctxray xray prompt-input.json\n```\n\nCtxRay reports role counts, characters, and explicitly estimated tokens. It does not include prompt text in its report.\n\n```\nctxray profile examples/ctxray.yaml --dry-run\nctxray profile examples/ctxray.yaml\n```\n\nThe second command stages files under `.ctxray/profiles`\n\n. Installing into\n`CODEX_HOME`\n\nis a separate, explicit action:\n\n```\nctxray profile examples/ctxray.yaml --install\n```\n\nExisting profiles are copied to `~/.codex/.ctxray-backups/<timestamp>/`\n\nfirst.\n\nCreate a private, redacted baseline, then compare it with the live setup:\n\n```\nctxray lock\nctxray drift\nctxray drift --fail-on-drift\n```\n\nThe last command exits with status `2`\n\nwhen a skill, instruction, profile, or\nplugin surface was added, removed, or changed, making it suitable for CI. For a\nfully offline comparison between saved files, use\n`ctxray drift baseline.json --current current.json`\n\n.\n\n```\nctxray lock --out ctxray.lock.json\n```\n\nThe lockfile contains hashes and relative paths, not prompt history. Secret-like config values and all MCP environment values are redacted before hashing.\n\nThe repository includes a validated marketplace and plugin bundle:\n\n```\ncodex plugin marketplace add .\n```\n\nRestart the ChatGPT desktop app, open the Plugins Directory, select the CtxRay\nmarketplace, and install CtxRay. After the repository is public, the same\nmarketplace can be added using its GitHub `owner/repository`\n\nshorthand.\n\nThe bundled `$ctxray`\n\nskill has implicit invocation disabled. Its instructions\nare loaded only when the user explicitly invokes it.\n\n``` php\nflowchart LR\n  A[\"Codex config, AGENTS.md, skills, plugins\"] --> B[\"Audit + X-Ray\"]\n  P[\"CtxRay YAML policy\"] --> C[\"Profile compiler\"]\n  J[\"codex exec --json\"] --> D[\"Exact usage parser\"]\n  S[\"Codex app-server\"] --> E[\"Plan + quota snapshot\"]\n  R[\"Dated OpenAI rate catalog\"] --> F[\"Receipt policy\"]\n  D --> F\n  E --> F\n  B --> O[\"Local reports\"]\n  C --> O\n  F --> O\n  O --> L[\"Redacted capability lock\"]\n  L --> G[\"Drift guard\"]\n```\n\nSee [Architecture](/FramY2/ctxray/blob/main/docs/architecture.md) and [Privacy and security](/FramY2/ctxray/blob/main/docs/privacy-security.md).\n\n**Exact**: returned by the Codex runtime or account surface.** Estimated**: derived from a declared character proxy or dated rate card.** Unknown**: unavailable. CtxRay never replaces it with zero.\n\nClaims about savings require comparable tasks that pass the same quality gate. CtxRay does not translate token estimates into a weekly allowance when Codex does not expose that conversion.\n\n- A literal inline footer is available through\n`ctxray run`\n\n. Codex does not currently document a plugin API that mutates a native desktop assistant message after generation, so the desktop plugin uses a separate result. `codex debug prompt-input`\n\nand app-server are version-sensitive surfaces. CtxRay fails closed to`unknown`\n\nwhen data is unavailable.`turn.completed.input_tokens`\n\nis aggregate consumption, not current context occupancy. Without`--prompt-xray`\n\n, CtxRay prints`prompt context unknown`\n\ninstead of dividing that aggregate by the model window.- Runtime MCP tool schemas and built-in tool schemas are not included in the static audit estimate; the audit reports that gap explicitly.\n- The bundled 2026-08-08 catalog covers GPT-5.6 Sol, Terra, and Luna. Supply a\nreviewed catalog with\n`--pricing`\n\nfor other models or newer prices. - Token-derived dollar estimates exclude unobserved tool-call fees and cache write classes.\n\n```\nnpm ci\nnpm run check\nnpm run build\nnpm run validate:plugin\nnpm pack --dry-run\n```\n\nThe test suite includes unit, integration, and process-level CLI tests. Coverage\nthresholds are at least 80% for statements, branches, functions, and lines. See\nthe [v0.1 TDD evidence](/FramY2/ctxray/blob/main/docs/testing/v0.1.tdd.md).\n\nRead [CONTRIBUTING.md](/FramY2/ctxray/blob/main/CONTRIBUTING.md), [SECURITY.md](/FramY2/ctxray/blob/main/SECURITY.md), and the\n[roadmap](/FramY2/ctxray/blob/main/docs/roadmap.md) before opening a substantial change. Efficiency\nclaims follow the public [evaluation plan](/FramY2/ctxray/blob/main/docs/evaluation-plan.md).", "url": "https://wpnews.pro/news/ctxray-see-and-lock-what-codex-loads-before-a-task", "canonical_source": "https://github.com/FramY2/ctxray", "published_at": "2026-08-10 01:26:38+00:00", "updated_at": "2026-08-10 01:35:41.449802+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["CtxRay", "OpenAI Codex"], "alternates": {"html": "https://wpnews.pro/news/ctxray-see-and-lock-what-codex-loads-before-a-task", "markdown": "https://wpnews.pro/news/ctxray-see-and-lock-what-codex-loads-before-a-task.md", "text": "https://wpnews.pro/news/ctxray-see-and-lock-what-codex-loads-before-a-task.txt", "jsonld": "https://wpnews.pro/news/ctxray-see-and-lock-what-codex-loads-before-a-task.jsonld"}}