Token Trail
GitHub

Free & open source · GPL-3.0 · Linux

Your Codex usage,
in plain sight.

Token Trail is a read-only desktop dashboard that shows your local OpenAI Codex usage clearly: quota windows, token activity, reset times, and credits. It reads only what it must, keeps everything in memory, and never sends your data anywhere.

Get Token Trail See features

v2.0.0 · available for Linux

Token Trail Overview screen showing a Codex quota window at 63% remaining, with used percentage, reset date, countdown, and last-updated time.
The Overview screen: capacity remaining, reset times, and freshness in one calm view.

Read-only by design

Exactly three approved reads plus one update notification, allowlisted before they ever reach Codex. No task control, no account changes, ever.

Memory-only data

Usage snapshots live only in RAM while Token Trail runs. Close the app and they are gone: no history file, no cache, nothing to sync.

No telemetry

Token Trail has no telemetry, analytics, or automatic update checks. Its packaged interface uses local assets. Codex manages its own connections.

  • 6dashboard routes
  • 3approved data reads
  • 1preferences document
  • 0telemetry endpoints
  • 4package formats
  • 2CPU architectures

These counts describe Token Trail. Codex manages its own authentication and network traffic; temporary preference files, exports, and runtime files are outside the preferences count.

Six routes. One honest picture.

Every value states where it came from, whether that is reported by Codex, observed locally, or calculated by Token Trail. Missing values stay visibly unavailable instead of pretending to be zero.

Overview

Quota windows with used/remaining percentages, reset times, countdowns, provenance labels, and freshness states on one calm screen.

Quota Windows

Grouping, sorting, raw-safe details, a reset timeline, attention ordering, and session-change observations kept in memory only.

Usage

Date ranges with a daily chart, calendar heatmap distinguishing real zeros from missing days, accessible tables, statistics, and coverage reporting.

Credits

Balance, unlimited state, spending limits, reached state, and reset-credit expiry using the exact seven-day display rule.

Learn

Built-in explanations of quotas, tokens, credits, provenance, privacy, and statistics, linked contextually from the metrics themselves.

Settings & Diagnostics

Light/dark/system themes, working automatic refresh intervals, and a fully previewed redacted diagnostics export. Clear-data wipes your preferences after confirmation.

Token Trail Usage screen with lifetime token totals, a daily activity bar chart, and a calendar heatmap section.
The Usage screen: daily activity, lifetime totals, peak day, and streaks.

Local reads.
Clear boundaries.

Approved reads, validated responses, and a sandboxed interface.

Local data flow

From Codex to your dashboard

Read requests go to Codex. Validated results come back to Token Trail.

Local process

Your Codex CLI

An app-server started and stopped by Token Trail. Codex handles authentication and its own network traffic.

Token Trail

Read & validate

Allowlist outgoing data requests. Validate responses and keep approved display fields.

Interface

Your dashboard

Quota windows, aggregate usage, and credits. Usage snapshots stay in memory while the app runs.

Token Trail requests account information, rate limits, and aggregate usage after the startup handshake. Refresh actions, enabled timers, and rate-limit notifications trigger approved reads. Preferences and optional diagnostics exports are separate from this usage-data path.

Reads exactly three things

Account information, rate-limit windows, and aggregate usage. The startup handshake establishes the connection; data requests are allowlisted and responses are validated before display.

Preferences, not usage history

Display choices live in a preferences document with no usage values. Saves may use temporary or recovery files; diagnostics are written only when you choose to export them.

No credential access

Authentication belongs entirely to Codex. Token Trail does not ask for login credentials or read Codex credential files. Codex handles authentication.

Prompts stay yours

The approved data reads do not request prompt text, responses, tasks, repository contents, tool calls, transcripts, or browser sessions.

Sanitized diagnostics

The support export comes from a fixed allowlist of fields, structurally excludes identifiers and paths, and you preview it fully before saving.

Hardened shell

Sandboxed renderer, context isolation, strict self-hosted CSP, deny-by-default navigation and permissions, single-instance lock, Electron fuses.

Read the full privacy guide

What is new in 2.0.0

Choose a date range, refresh on your schedule, and read clearer usage and diagnostics.

Choose your date range

Inclusive start and end dates filter the daily chart, table, heatmap, statistics, comparisons, and coverage together. Reset to all supplied dates at any time.

Refresh and recover reliably

Automatic refresh follows your settings. Rapid preference edits save in order, late replies cannot replace newer data, and recoverable preferences survive read failures.

Trust the displayed values

Signed changes, large token tooltips, calendar dates, missing-day coverage, and credit controls now preserve their intended meaning. Stale values are labeled across data screens.

Clearer support and access

Diagnostics describe observed capabilities and completed refreshes. Learn search keeps keyboard focus, reduced motion is respected, and website copy failures have honest feedback.

Read the full 2.0.0 changelog

Install on Linux

Four package formats, two architectures (x64 and arm64). Artifacts are unsigned, so checksums are the integrity mechanism: download from GitHub Releases and verify before running anything.

  1. Check your architecture

    uname -m

    x86_64 → x64 builds (amd64) · aarch64 → arm64 builds

  2. Download & verify

    Grab an artifact and SHA256SUMS.txt from the Releases page, then:

    sha256sum -c SHA256SUMS.txt --ignore-missing

    Every file you downloaded must print OK.

  3. Prerequisite: Codex CLI

    Token Trail needs a working, signed-in OpenAI Codex CLI on your PATH:

    codex --version && codex login

deb

x64 download · arm64 download

Debian · Ubuntu · Mint

sudo apt install ./tokentrail-*-linux-amd64.deb

Runtime libraries resolved automatically by apt.

rpm

x64 download · arm64 download

Fedora · openSUSE

sudo dnf install ./tokentrail-*-linux-x86_64.rpm

On openSUSE use sudo zypper install … instead.

Pacman

x64 download · arm64 download

Arch · CachyOS · Manjaro

sudo pacman -U tokentrail-2.0.0-linux-x64.pacman

Installed via pacman's local-package mode.

Download from GitHub Releases

Note: "Source code (zip / tar.gz)" links on release pages are repository snapshots, not runnable builds.

Not ready to install? Browse the FAQ first →

Where the project stands

Token Trail 2.0.0 is the current release. It adds working usage date ranges and automatic refresh scheduling, improves Codex process cleanup and preference recovery, and corrects token calculations, credit states, diagnostics, and accessible navigation. Release 2.0.0 is available now. It includes four Linux package formats for x64 and arm64, SHA-256 checksums, build provenance, a CycloneDX SBOM, and detailed notes for every audited fix. Usage remains read-only and in memory. Artifacts remain unsigned; arm64 execution and native package installation campaigns remain unverified.

  • v2.0.0: released
  • Manual upgrades
  • Extracted package checks
  • Signing: gated
  • Telemetry: never

Documentation

Everything about how Token Trail works is written down and versioned with the code.

User guides

Architecture

Project

See your usage clearly.

Free, open source, and local-only. Download an artifact, verify its checksum, and meet your quota windows on your own desktop.

Download from Releases View the source