Gauge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CODEX_HOME | No | Codex home directory used to derive the default log directory and usage index path. Defaults to ~/.codex. | |
| GAUGE_DATABASE | No | Override the usage index path. Defaults to $CODEX_HOME/gauge/usage.sqlite3, otherwise ~/.codex/gauge/usage.sqlite3. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Gauge is a read-only local Codex token, prompt-cache and estimated-credit monitor. Use the chat ID supplied by the user or current chat context; never silently select the most recently active unrelated chat. No model calls are needed for dashboard refresh.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| resources | {} |
| extensions | {
"io.modelcontextprotocol/ui": {
"mimeTypes": [
"text/html;profile=mcp-app"
]
}
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| show_cache_dashboardA | 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. |
| refresh_cache_dashboardB | Refresh Gauge for the current chat without a model call. |
| list_cache_sessionsB | List locally recorded chats and token-weighted cache summaries. Conversation text is excluded. |
| get_cache_historyB | Get completed model-call history and per-prompt token-weighted totals for one chat. |
| get_cache_summaryB | Get whole-chat, latest-call and latest-prompt cache reuse for a specified chat. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Gauge dashboard | Self-contained dashboard; all data refreshes go through MCP tools. |
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.