Codex Context Lens

Understand your Codex usage without leaving VS Code.

Local token counters, context insights, visible-content breakdowns and quota snapshots — with no API key or telemetry.

Status: early preview · Windows validated · MIT · Marketplace publication pending.

Independent community tool. Not affiliated with or endorsed by OpenAI.

中文说明 · Privacy · Support

See where your context goes

• Live dashboard: context gauge, input/output totals, cached input and request history.
• Visible content breakdown: history, file reads, tool output and other logged text.
• Quota snapshots: usage windows and reset times when Codex includes them in local logs.
• Local by design: session statistics stay local. Live quota uses your signed-in Codex to query the account service; no model calls or extension telemetry. Disable codexContextLens.liveQuota for local-only operation.

The Explorer sidebar view updates existing numbers and chart elements. The status-bar hover automatically synchronizes changed data in a fixed five-second window. Identical content is not republished. Stable VS Code APIs do not expose a status-bar mouse-enter event: this is background synchronization, not an on-hover read. Native tooltip replacement may still redraw; the live sidebar updates individual elements. Set codexContextLens.autoRefreshHover to false only if you prefer a manual snapshot.

Illustrative data only. English interface shown; Chinese screenshots are available in the Chinese README.

Get started

1. Build a VSIX from this repository using the development commands below, then run Extensions: Install from VSIX… in desktop VS Code. This repository has not yet been published to Marketplace.
2. Click Codex Context Lens in the bottom status bar to open the Explorer sidebar view.
3. For the larger dashboard, run Codex Context Lens: Open Usage Dashboard from the command palette.
4. Use the session picker to pin a conversation when working with several chats.

Codex must have written local session logs. Startup reads existing logs; no new model request is needed. Automatic selection prefers the current workspace. If there is no matching conversation, the latest main conversation is shown with a source notice. It does not follow the official Codex chat selection. Background subagent sessions are excluded from automatic selection.

The interface supports English and Simplified Chinese. It follows the VS Code display language by default; other display languages use English. Set codexContextLens.language to en or zh-CN to override dashboard, picker and hover language. Command and settings labels follow the VS Code display language. Session titles and log content are never translated.

Upgrading from an earlier preview? Follow the installation and migration guide to avoid duplicate entries.

What the numbers mean

Hidden instructions, images, server-side trimming and unlogged content cannot be reconstructed. Cumulative tokens are consumed across requests and are not the size of the current context. Log formats can change between Codex releases. See accuracy notes.

Configuration

Only the selected log is parsed fully. File notifications are coalesced and reads are incremental. Archived sessions are not currently included. Select Auto to release a pinned session.

Compatibility

• Desktop VS Code 1.96 or later; no proposed API flags required.
• Windows: automated parser, lifecycle, filesystem and headless UI checks have been run. The maintainer has accepted the current preview experience, including the documented native-hover redraw limitation.
• macOS, Linux, WSL and SSH: designed for the remote/local extension-host filesystem, but not yet validated on real installations. Browser-only VS Code is not supported.
• In remote windows, install the extension on the remote host and configure the remote Codex home.

Troubleshooting

No data? Check the selected session, Codex home and the dashboard's diagnostics. This extension only sees local logs available to its extension host. Hide/show the bottom status bar through VS Code Appearance settings. After a local VSIX upgrade, use Developer: Reload Window.

No seven-day window? It must be present in the log. Window duration determines the label; primary and secondary are not hard-coded to five hours and seven days. Expired snapshots do not become a guessed fresh allowance.

More help: Troubleshooting · Report a bug · Request a feature.

Privacy and license

Session text is processed locally to compute statistics. The extension may display titles and paths; do not include those in public screenshots. It does not read auth.json, send requests to a model or alter Codex logs. See PRIVACY.md.

MIT license. OpenAI and Codex names identify the product this community extension observes.

Development

Node.js 22+ is recommended for development. Runtime has no third-party dependencies.

npm ci --ignore-scripts
npm test
npm run package:local

The package identity is ruoyu-li.codex-context-lens. Building does not publish or install the extension. See the contributor guide, release checklist and changelog. The repository name is CodexContextLens; the product name is Codex Context Lens.

Source and tool analysis

The top-level chart groups visible text into instructions, conversation/summaries, reads/retrieval, execution feedback, tool-call content and unattributed output. File-purpose tags remain in the file rankings. Output-type and read-path coverage have separate denominators. Same-cycle and cross-compaction repeats are separate, not assumed waste.

The dashboard includes large tool returns and argument payloads, explicit write/edit calls, known-outcome failure rates, paired call-to-return intervals and cumulative token deltas by recorded turn. Initial snapshots establish baselines; unknown data stays unknown. Character shares are not per-file token costs.