Model Meter

A local-first usage console for OpenAI Codex, Claude Code, and Grok CLI sessions. Model Meter reads the providers' local session files, aggregates token usage and sub-agent activity, and presents an API-cost equivalent in a responsive browser workspace.

No runtime dependencies, database, cloud service, or provider API keys are required.

Standalone mobile meter

Features

• Monitor OpenAI Codex, Claude Code, and Grok CLI from one local page.
• Pin each meter independently to a project, root session, and billing plan.
• Aggregate descendant Codex and Claude sub-agent usage into the root session.
• Compare recorded usage with a retail API-rate estimate.
• Open standalone, bookmarkable meter tabs for focused monitoring.
• Keep workspace choices in browser localStorage; no server-side database is used.
• Run entirely on the Node.js standard library.

Quick start

Requires Node.js 18 or newer.

git clone git@github.com:clearmud/model-meter.git
cd model-meter
npm start

Open http://127.0.0.1:4321.

Use another port with either form:

PORT=4400 npm start
node server.js 4400

How it works

Model Meter reads the local session stores already written by each CLI:

Provider	Default source	Override
OpenAI Codex	~/.codex/sessions	CODEX_SESSIONS or CODEX_HOME
Claude Code	~/.claude/projects	CLAUDE_PROJECTS or CLAUDE_HOME
Grok CLI	~/.grok/sessions	GROK_SESSIONS or GROK_HOME

The local server normalizes those files into three read-only JSON endpoints per provider:

/api/:provider/projects
/api/:provider/sessions
/api/:provider/state

The browser polls the selected state every eight seconds. A short in-memory cache avoids reparsing unchanged session files.

Sub-agent accounting

• Codex: follows parent_thread_id from each rollout to its root and totals the descendant tree, including children that change working directory.
• Claude Code: totals the root transcript and the session's subagents/*.jsonl files. Streaming snapshots are deduplicated by assistant message ID.
• Grok: the current local format does not expose an equivalent descendant relationship, so Model Meter labels agent tracking as unavailable.

Security and privacy

Model Meter is designed for trusted, local use:

• The server binds to 127.0.0.1 by default.
• API responses do not include prompts, completions, tool inputs, OAuth tokens, API keys, refresh tokens, or authentication files.
• Cross-origin browser requests are rejected and no permissive CORS header is sent.
• Loopback mode validates the request host, accepts only GET and HEAD, and serves files only from public/.
• Browser security headers include a restrictive Content Security Policy, frame denial, MIME sniffing protection, and a no-referrer policy.
• Environment files, private-key formats, auth files, local CLI state, dependencies, and internal prototypes are excluded by .gitignore.

For plan auto-detection, the process may read the OpenAI ID-token payload in ~/.codex/auth.json or the Claude account tier in ~/.claude.json. It returns only an allowlisted plan label such as pro or business; credentials and token contents never leave the server process. The test suite includes a sentinel-token regression test for this boundary.

Project paths, short session IDs, token totals, model names, timestamps, and estimated costs are sent to the local browser because they are required by the UI. Selected project and session values are stored in that browser's localStorage.

Setting HOST to a non-loopback address is an explicit remote-access opt-in. Do not expose the server to an untrusted network without adding authentication and transport security in front of it.

Accuracy and pricing

The large dollar figure is a retail API-rate equivalent, not the amount charged by a flat ChatGPT, Claude, or SuperGrok subscription.

• Codex uses recorded token-usage events and preserves cache-read/cache-write totals.
• Claude uses the final usage snapshot for each unique assistant message.
• Grok input uses recorded stream context totals; output is estimated from visible completion and tool-call text because local reasoning bodies may be encrypted.
• Provider tool-call fees, priority processing, data residency, batch discounts, and per-request long-context multipliers are not included.
• Claude cache creation is valued at the standard five-minute cache-write rate when the local record does not identify cache duration.
• Unknown model IDs fall back to the first current rate for that provider, so review the table when providers change names or pricing.

Pricing constants in server.js were checked on July 24, 2026 against the official OpenAI model pages, Claude pricing documentation, and xAI pricing documentation. Claude Sonnet 5's introductory rate automatically changes to its published standard rate on September 1, 2026.

Standalone meters

Standalone views use URL parameters and can be bookmarked:

http://127.0.0.1:4321/?provider=openai
http://127.0.0.1:4321/?provider=claude&project=/path/to/project
http://127.0.0.1:4321/?provider=grok&project=/path&session=abc123

Supported parameters are provider, project, session, and plan.

Development

npm run check
npm test
npm run dev

npm run check validates the server and browser JavaScript syntax. npm test starts isolated loopback servers with empty temporary stores and verifies request restrictions, security headers, static-file containment, and credential non-disclosure.

License

MIT. See LICENSE.