Gauge
Monitors OpenAI Codex usage by reading existing local Codex session logs — no API key or model calls required. Computes cache-reuse percentages (whole-chat, latest model call, latest prompt), tracks completed model-call history, and estimates credits split into fresh input, cached input, and output using bundled per-model pricing, presented in an embedded MCP dashboard bound to a specific chat.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gauge Show my token usage and prompt-cache reuse for this chat"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gauge
Tokens · Cache · Credits. A local Codex usage monitor with an embedded MCP dashboard. See whole-chat, latest-model-call and latest-prompt cache reuse, recent call history, and estimated credits split into fresh input, cached input and output.
Gauge reads existing local logs. Collection and dashboard refresh make no model calls and need no OpenAI API key, hosted backend or separate browser dashboard. This is an independent project, not an OpenAI product or official-directory listing.
UI screenshots
The current dashboard in dark and light themes, rendered with synthetic sample usage. These previews show the app content; desktop-host placement varies.
Dark theme | Light theme |
|
|
To reproduce the sample previews, run node scripts/screenshot_preview.mjs after npm ci, then capture .release-test/screenshot-preview/dark.html and light.html in a browser at 1200 × 1300 pixels. The preview uses the production UI with a simulated MCP host and does not read local chat logs.
Related MCP server: tokenchit
Requirements and platform support
Python 3.11+, uv, and a local Codex installation that writes compatible session logs.
A desktop host supporting MCP Apps for the embedded panel. Other MCP clients can use the text tools; UI placement depends on the host.
Git for GitHub marketplace installation. Node.js is only needed to change/rebuild the UI, not to run a release.
Automated accounting, packaging and MCP launch/refresh checks pass on Windows, macOS and Linux with Python 3.11 and 3.13. Windows desktop rendering has been exercised during development; native desktop rendering on macOS/Linux is not yet verified. See validation details.
Install uv using its official instructions and make sure uv --version works. Restart the desktop app after installation so its process inherits the updated PATH. First launch may download dependencies from the package registry; subsequent refreshes stay local.
If Gauge's tools are unavailable
A missing uv executable prevents the MCP server from starting, so the chat may only report that Gauge's tools are unavailable. That message alone does not mean the plugin needs reconnecting or reinstalling.
This plugin includes a Gauge skill and a setup entry that guide startup diagnosis without needing its MCP server. In a host that loads the bundled skill, ask "Diagnose Gauge startup", or run the plugin's setup action. The skill checks for uv and distinguishes an executable missing from PATH from a dependency/setup failure. Skill discovery and setup availability depend on the host; they do not replace the runtime requirement.
On macOS/Linux, first check uv --version. If uv is not installed, use Astral's official installer:
curl -LsSf https://astral.sh/uv/install.sh | shFully quit and reopen the desktop app after installation, then ask to open Gauge again. If uv already works in a terminal, the desktop app may have inherited a different PATH; inspect Gauge's MCP startup error before reinstalling anything.
Install through the custom marketplace
Add the marketplace and install Gauge:
codex plugin marketplace add alstomli/Gauge
codex plugin add gauge@gauge-toolsUse a compatible Codex CLI that supports these commands. If your host exposes marketplace sources in its plugin directory, select Gauge under that source and install it there. This repository is a custom marketplace, separate from OpenAI's universal public directory. See OpenAI's marketplace documentation.
Reload/restart the desktop host as needed to discover the newly installed MCP tools, then ask:
Open Gauge for this chat.
To pin a release instead of following the default branch, add the marketplace with --ref v0.1.0. Do not enable both the plugin and a separately configured copy of the same MCP server. Existing installations can keep the cache-monitor connection key and tool names.
Install directly from source
These commands work in PowerShell and a macOS/Linux terminal once Python, Git and uv are available:
git clone https://github.com/alstomli/Gauge.git
cd Gauge
uv sync --locked
uv run --locked gauge --versionRegister the server using your absolute checkout path so it works from any project:
codex mcp add cache-monitor -- uv run --locked --no-dev --project "/absolute/path/to/Gauge" gauge mcpOn Windows, replace the example path with a path such as C:/Tools/Gauge. Alternatively, configure the equivalent stdio command in your MCP client's settings. uv run --locked gauge config prints JSON settings using that environment's Python interpreter for clients accepting JSON configuration. Launching gauge mcp in a terminal waits for MCP messages on stdin; it is not an interactive web server.
For an already-downloaded release ZIP, extract it, open a terminal in that folder, run uv sync --locked, then use the same registration command. A Python wheel can be installed with python -m pip install /path/to/codex_cache_monitor-0.1.0-py3-none-any.whl; the gauge and legacy cache-monitor entry points are equivalent. Dependencies still need to be downloadable unless already cached.
Use the dashboard
The dashboard is bound to the opening chat's explicit ID. It never silently chooses a recently active unrelated chat. If no records exist yet, it waits for that chat. Automatic refresh runs every two seconds while visible; the collector waits approximately one second between scans.
Whole chat: token-weighted reuse across every distinct recorded completed call, including attempts replaced by editing a prompt.
Latest model call: cached/input for the newest completed call.
Latest prompt: token-weighted reuse across calls attributed to the newest prompt with recorded usage. One prompt can cause several model calls.
Estimated credits: fresh input (
input - cached), cached input and output at bundled per-model Standard-speed rates. Rates are dated in the panel. Estimates exclude speed/context surcharges and other charges, and are not billed usage or remaining plan allowance. Unknown rates are explicitly unpriced.
The panel offers an automatic percentage axis, history range, dark/light appearance and info icons. Credit amounts animate without changing their original colors and respect reduced-motion preferences. The host owns the side-panel placement and close controls.
Local data and configuration
Setting | Default / override |
Log directory |
|
Usage index |
|
Network use | Dependency installation and opening the optional pricing link; no Gauge telemetry or refresh requests to a hosted service |
Data lives outside plugin/package files, so updates do not erase it. An older explicit --database path, including .monitor/usage.sqlite3, remains supported; Gauge does not automatically move that existing database. Stop Gauge before copying an old SQLite database, or let a new default index rebuild from the retained logs.
Gauge indexes all readable local chats in the configured directory. The opened dashboard returns only its selected chat, while the separate list tool can return other indexed summaries. Numeric usage, IDs, timestamps, model/source metadata and local paths are persisted. Prompt text, responses, tool output and credentials are not intentionally stored. Metadata requested through tools is shared with the MCP host/model. Read PRIVACY.md before sharing diagnostics.
Accounting limits
Cache reuse is sum(cached input) / sum(input); cached input is already included in input. Output does not enter this percentage. Zero input is unavailable, and unfinished calls have no reported usage yet.
Response records are deduplicated by chat and response ID. Each log is checked against its own resume-checkpoint lineage, including nested segment references after edits. Missing proof stays unverified; actual counter mismatches are marked degraded. Completed calls omitted from the surviving conversation branch still count toward spent usage. Child-agent and internal-review usage remains separate from the parent chat. For snapshot-only logs, the first cumulative value is a baseline and history is explicitly partial.
Only compatible, retained local logs are covered. Archives, other devices, cloud-only calls and separate agent chats are excluded from this chat's totals. Codex's internal log format can change. This monitor is not an account-wide billing record.
Tools
Tool | Purpose |
| Open the embedded dashboard for an explicit current chat ID |
| App-only passive refresh |
| List indexed chats; internal reviews hidden by default |
| Whole-chat, latest-call and latest-prompt readings |
| Completed call history and prompt groups |
The package retains cache_monitor, distribution name codex-cache-monitor, resource URI ui://cache-monitor/dashboard.html, and existing tool/connection names for compatibility. Gauge is the displayed product name.
Update and uninstall
For a marketplace installation, refresh its source and update/reinstall Gauge through your host. CLI equivalents on supported versions are:
codex plugin marketplace upgrade gauge-tools
codex plugin add gauge@gauge-toolsA tag-pinned source stays pinned until you change its reference. For a direct checkout, stop/reload the connection, pull the desired release, and run uv sync --locked before reconnecting.
For a marketplace uninstall, remove Gauge in the plugin UI or run codex plugin remove gauge@gauge-tools. For a separately registered MCP connection, run codex mcp remove cache-monitor. Remove the custom marketplace source separately with codex plugin marketplace remove gauge-tools if desired. These operations retain usage data. See PRIVACY.md for deliberate deletion of Gauge's database; never delete the entire Codex home.
Development and releases
See CONTRIBUTING.md for checks, CHANGELOG.md for changes, SECURITY.md for reporting, and the release checklist for building and reviewing artifacts.
npm ci
npm run check
npm test
npm run build
uv run --locked python -m unittest discover -s tests -v
uv build
uv run --locked python scripts/build_release.pyBuild the UI before Python resource tests. Release ZIPs use an explicit file allowlist and include a per-file hash manifest; dist/SHA256SUMS covers the generated artifacts. Never publish your development folder wholesale. Current rates are an estimate; compare accounting changes against synthetic fixtures and the target host's logs.
License
MIT. Dependencies retain their own licenses; see THIRD_PARTY_NOTICES.md.
Available Tools
5 toolsget_cache_historyBRead-only
Get completed model-call history and per-prompt token-weighted totals for one chat.
Inputs: session_id (required), limit.
get_cache_summaryBRead-only
Get whole-chat, latest-call and latest-prompt cache reuse for a specified chat.
Inputs: session_id (required), limit.
list_cache_sessionsBRead-only
List locally recorded chats and token-weighted cache summaries. Conversation text is excluded.
Inputs: include_internal.
refresh_cache_dashboardRefresh cache dashboardBRead-only
Refresh Gauge for the current chat without a model call.
Inputs: session_id (required), limit.
show_cache_dashboardOpen GaugeARead-only
Open Gauge, a local dashboard for token usage, prompt-cache reuse and estimated credits, fixed to the current chat. Always pass the current chat ID. Usage reflects completed recorded model calls.
Inputs: session_id (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: opening/refreshing the dashboard, listing chats, fetching per-call history, and fetching aggregate reuse metrics. The main potential confusion is between get_cache_history and get_cache_summary, both of which return per-chat token/cache data, though the descriptions differentiate per-prompt history vs whole-chat/latest-call reuse.
All five tools follow a consistent snake_case verb_noun pattern (show_, refresh_, list_, get_ + object). The verbs accurately reflect the read/open semantics of each tool.
Five tools is a tight, well-scoped surface for a cache dashboard domain. show_cache_dashboard and refresh_cache_dashboard are close enough that a single parameterized tool could suffice, but the split is defensible since refresh explicitly avoids a model call.
The surface covers the core read-only lifecycle: open the dashboard, refresh it, enumerate chats, and inspect both detailed history and aggregated summaries. Minor gaps exist around cache management actions (e.g. clearing or exporting data) and credit-level breakdowns, but agents can work around these for inspection tasks.
Maintenance
Related MCP Connectors
Query your app's logs, metrics and incidents from your AI assistant.
Track API spend, credit balances and runway across OpenAI, Anthropic, OpenRouter and 25 more.
Your versioned prompt library: search, read, save and version prompts from Claude Code.
Exact Claude API cost calc with real cache economics, plus a tiktoken-misuse scanner.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceReads local Codex rollout logs to expose context-window usage snapshots, remaining-token estimates, and log-event freshness through a read-only MCP tool.MIT
- AlicenseNot gradedqualityAmaintenanceReads the Claude Code, Codex and OpenCode usage logs already on your machine and reports token totals, per-day and per-hour activity, a per-agent and per-model breakdown, and a year-in-review recap. It makes no network request at all — a test fails if any source file in the package can open a socket.414MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents such as Claude Code, Cursor, Codex, and OpenCode to query local token usage, costs, quotas, projects, and models through six strictly read-only tools. All data stays on the local machine, drawn from passively parsed session logs rather than uploaded telemetry.MIT
- AlicenseAqualityBmaintenanceReports OpenAI Codex token use, API-equivalent cost and the ChatGPT plan's 5-hour and weekly limits from Codex's local session logs. Tools for usage summaries, plan limits, quota forensics, sessions, daily totals and budgets.6101 PyPIMIT

