How I Built a Privacy-First Codex Usage Dashboard on macOS

zhaoqi wu — Mon, 20 Jul 2026 12:16:39 +0000

A Codex usage dashboard can answer more than “how many tokens did I use?” The harder question is how to inspect usage across sessions without turning a local analytics tool into another place that stores prompts, responses, terminal output, and private paths.

I ran into that problem while building UsageCove Local, a macOS dashboard for selected metadata from supported Codex session logs. This article explains the design decisions behind it: stream the logs, retain only an explicit allowlist of fields, keep the service on loopback, and state clearly what the resulting numbers cannot prove.

Start with a narrow threat model

Local session logs may contain much more than token counts. Depending on the event, a raw line can include conversation text, tool arguments, terminal output, working directories, repository details, or authentication-related data.

For a usage dashboard, most of that content is unnecessary. The useful inputs are much smaller:

token counts and timestamps;
model names;
session identifiers;
the final component of a working-directory label;
quota-window observations found in supported events;
timing and explicit failure status.

That became the core rule: if a field is not required for a visible aggregate, it should not survive the scan.

Stream Codex session logs instead of loading them wholesale

The scanner uses a line stream for the JSONL files. Each line is parsed long enough to inspect supported event fields, then only selected metadata is added to the aggregate state.

The data flow is intentionally short:

Codex JSONL files (read-only)
        ↓
line-by-line parser
        ↓
allowlisted metadata extractor
        ↓
aggregate cache
        ↓
127.0.0.1 dashboard → optional user-triggered CSV

This approach has two benefits. First, memory use does not grow with the full history in the same way as reading every file into one large structure. Second, it creates a clear retention boundary: raw log lines and conversation text are not written into the cache.

The cache still contains data and should not be described as anonymous. It includes token totals, timestamps, session identifiers, model names, display labels, failure flags, and quota observations. The goal is data minimization, not magic disappearance.

Treat local HTTP as a security boundary

“It only runs locally” is not enough by itself. Browsers, other local processes, and unexpected Host values can still reach a careless local server.

The dashboard therefore:

binds to a random port on 127.0.0.1;
creates a random session token;
exchanges the initial token for an HttpOnly, SameSite=Strict cookie;
rejects unexpected Host values;
does not enable cross-origin access;
sends no telemetry and makes no automatic request to analytics, pricing, licensing, or update services.

These controls do not make every local threat disappear, but they keep the attack surface aligned with the product’s job: read local usage metadata and show it to the current user.

Export less, and export only on demand

CSV export is useful for comparing sessions or doing a longer review, but it also creates a new file that users may share.

For that reason, export happens only after an explicit click. The CSV contains filtered aggregate rows rather than prompts, responses, tool arguments, terminal output, credentials, full working-directory paths, or raw JSONL lines.

Even aggregate labels can be sensitive. A final directory name may reveal a client or project name, so the interface tells users to review the CSV before sharing it. “No prompt text” does not mean “safe to publish without checking.”

Separate observation from attribution

A local Codex usage dashboard can show when token usage increased. It can also rank high-usage sessions and models inside a selected time range.

Those are two separate views. They do not, by themselves, prove that a particular session caused a particular spike. Making that causal claim would require event-level correlation and stronger evidence than a range ranking provides.

The same restraint applies to quota and cost:

quota values are delayed observations found in local logs, not official real-time status;
cost values are API-equivalent reference estimates, not a ChatGPT or Codex subscription bill;
explicit failure events are not the same thing as a complete failure rate.

Clear limitations make an analytics tool more useful because users know which decisions the data can support.

Build support diagnostics around omission

Support is another place where private data can leak. Asking a user to email a raw session log would defeat the product’s privacy boundary.

The support command therefore reports runtime and aggregate diagnostics designed to omit session content and private paths. Release packaging also checks for logs, authentication files, credential patterns, and private paths before creating the customer archive.

The broader lesson is simple: privacy should cover debugging and distribution, not only the main dashboard.

What I would change next

The current Early Access build still has meaningful friction: macOS 14 or later, Node.js 20 or later, and Terminal are required. The dashboard UI is Simplified Chinese, although the documentation is bilingual. It is not yet a signed, double-click native Mac app.

My next priorities are reducing installation friction and improving how the dashboard explains the difference between a timestamped spike and a session ranking. An English interface would also make external technical feedback much easier.

Try the synthetic-data workflow

Disclosure: I am the developer of UsageCove Local. The product page and free synthetic-data Demo let you inspect the interface and CSV workflow without scanning local session logs. The full Early Access build is US$6.99 or more.

UsageCove Local is independent and unofficial, with no affiliation or endorsement by OpenAI. Development includes AI-assisted code, as disclosed on the product page.

That is the boundary I want this Codex usage dashboard to keep as it evolves.

If you build local developer analytics, which aggregate fields would you retain—and which would you refuse to store?

DEV Community: zhaoqi wu