Answers, straight
from the docs.

Token Trail is a free, open-source desktop dashboard for Linux that helps you understand your local OpenAI Codex usage. It presents six routes:

• Overview: your primary quota window with used and remaining percentages, reset time, countdown, and last-updated freshness.
• Quota Windows: every bucket Codex reports, grouped and sorted in deterministic attention order.
• Usage: aggregate token activity over date ranges, with a daily chart, calendar heatmap, accessible table, and statistics.
• Credits: balance, unlimited state, spending limits, and reset-credit expiry.
• Learn: built-in explanations linked contextually from the metrics.
• Settings & Diagnostics: themes, refresh choices, redacted diagnostics export, and clear-data.

It is strictly read-only: it observes account-level data reported by your own Codex CLI installation. It cannot start tasks, change your account, or redeem credits.

Token Trail is free and open source under GPL-3.0-only. There is no Token Trail account, paid tier, or subscription. Codex access is separate. Bundled third-party components retain their own licenses.

Project license

Linux desktop environments, for x64 (amd64) and arm64 (aarch64) machines. Four package formats ship: AppImage, deb (Debian, Ubuntu, Mint), rpm (Fedora, openSUSE), and Pacman (Arch, CachyOS, Manjaro).

Honest caveat from the support record: XWayland sessions have recorded evidence, while GNOME Wayland, Cinnamon, Xfce, and native X11 sessions are listed as untested so far. Untested does not mean unsupported; it means nobody has captured proof yet. arm64 artifacts build correctly but have not yet been executed on real hardware.

Compatibility and support matrix

Token Trail 2.0.0 includes improvements to usage date ranges, automatic refresh, recovery, calculations, diagnostics, and accessibility fixes. Release 2.0.0 is available now. It includes four Linux formats for x64 and arm64, checksums, provenance, a CycloneDX SBOM, and detailed changelog notes. Artifacts remain unsigned. arm64 execution, native package installation cycles, and human screen-reader validation remain unverified.

Changelog

You need an installed Codex CLI that Token Trail can find on its inherited PATH. Sign in through Codex to access the data available to that authentication mode. Token Trail has no separate account or subscription and does not guarantee that every Codex account exposes every metric. It starts an owned local app-server and uses your existing Codex authentication.

For people who use Codex on their own Linux machine and want an honest picture of their capacity without opening a terminal or guessing from error messages: how much of each quota window remains, when windows reset, how much token activity happened across days, and what credits look like right now.

No. It is an independent GPL-licensed project that talks to the locally installed Codex CLI through its documented app-server interface. All network activity belonging to your Codex usage stays inside Codex's own processes under its own terms; Token Trail adds nothing on top.

No. Token Trail does not query API billing endpoints or provide an invoice view. It displays what its approved Codex reads supply. Quotas, aggregate tokens, and credits are separate measurements and are not added into a single billing total.

"Token Trail" (with a space) is the user-facing product name shown in the interface. "tokentrail" is the machine-safe identifier used where spaces and capitalization cause trouble: the repository, package name, executable slug, desktop entry, and protocol identifiers. The application keeps these roles strictly separated.

The application does not request conversation or workspace content. Its data-request allowlist contains account/read, account/rateLimits/read, and account/usage/read. Credits are normalized from the approved responses. A startup handshake establishes the connection, and rate-limit update notifications can trigger another approved read.

Incoming responses are validated and normalized before display. Account email is excluded from the validated account shape. These are boundaries in the shipped implementation, not a guarantee against every possible compromise of your machine or its software.

Approved reads and notifications

Token Trail keeps usage snapshots and session observations in process memory; it does not write a usage-history database. This does not promise secure memory erasure or control how the operating system handles swap or process dumps.

Display settings are saved to preferences.json in the application user-data directory, normally ~/.config/Token Trail/ on Linux. A custom configuration location can change this path. Saves use a temporary file, and recovery may retain a quarantined file. Electron can also create runtime files, and an explicitly exported diagnostics document is saved at the destination you choose.

When preferences are first loaded, Token Trail validates the document. Proven malformed content is renamed to a recovery file before defaults are saved. If reading or quarantining fails, the operation reports an error rather than overwriting recoverable settings. The 2.0.0 schema is unchanged from 1.0.0; compatibility with every future version is not promised.

Clear data removes the owned preference, recovery, and temporary files and keeps defaults in memory. A later settings save or fresh launch may create preferences again.

Preference storage and recovery

Token Trail has no telemetry, analytics, crash-reporting service, or automatic update checks. Its packaged interface loads local assets and does not use a remote dashboard service. The development server is local to development.

Codex is a separate process and manages its own authentication and network requests. Starting a Codex app-server does not make Codex offline. The website loads its own files; following a GitHub or documentation link opens that external service.

Sign-in and credential storage belong to Codex. Token Trail does not ask you to paste a key or read Codex credential files. If Codex reports a signed-out state, sign in through Codex and refresh Token Trail. The app receives approved account information, not a login form or a credential-management workflow.

The shipped app does not offer task control, credit redemption, or account changes. Its Codex data-request allowlist permits reads only. It does write local preferences and optional diagnostic exports; read-only describes its Codex operations, not every filesystem operation.

The Electron shell applies defense in depth: a sandboxed renderer with context isolation and no Node integration, a strict self-hosted Content Security Policy in production, deny-by-default handlers for navigation, redirects, popups, webviews, permission requests, and downloads, single-instance enforcement so a second launch focuses the running window instead, and Electron fuses that disable risky runtime behaviors. Automated tests exercise renderer isolation and packaged identity, including native Wayland and XWayland on the reference desktop. These tests do not establish security or compatibility on every environment.

Security boundaries guide

The export uses a fixed schema for application/runtime versions, platform information, preferences, observed connection capabilities, and sanitized refresh, coverage, and session counters. It excludes prompt text, account identifiers, file paths, and raw protocol messages.

Open the Diagnostics tab in Settings & Diagnostics and review the preview before exporting through the native save dialog. The document still describes your environment and activity in coarse terms, so share it only when you are comfortable with those details.

Every value is labeled with its source: Codex-reported values come from the local app-server, calculated values are derived locally from those reported values, and locally observed values describe what this running process saw, such as when something was last refreshed. Provenance exists so honest numbers and honest gaps look different at a glance, and contextual links take you straight to an explanation whenever a metric surprises you.

The project does not currently sign its Linux packages. Download from the official release and compare the package with its checksum manifest:

Each downloaded package must report OK. The manifest covers the eight package files, not the source archives or metadata attachments. A matching checksum detects a difference from the manifest; it is not a code signature or an independent proof of publisher identity. Provenance and the SBOM provide additional build and dependency information.

First check that the file matches your CPU architecture and has executable permission. If the error specifically mentions FUSE, use the instructions for your distribution in the official AppImage FUSE guide. Package names vary; for example, Ubuntu 24.04 uses libfuse2t64.

After verifying the download, this x64 example uses the runtime fallback without FUSE:

For arm64, use the linux-arm64.AppImage filename instead. Other launch errors may have a different cause; include the error and your distribution when asking for help.

No. The automatic zip and tar.gz snapshots contain source files and assets, not a runnable build, and they are absent from SHA256SUMS.txt. Install only the tokentrail-* artifacts matching your architecture, named like tokentrail-2.0.0-linux-amd64.deb. Architecture suffixes map as: deb uses amd64/arm64, rpm uses x86_64/aarch64; Pacman filenames use x64/aarch64.

Native packages carry the application under /opt/Token Trail/, a desktop entry at /usr/share/applications/tokentrail.desktop, hicolor icons, and AppStream metadata at /usr/share/metainfo/com.tokentrail.app.metainfo.xml. Window identity is configured to match the desktop entry, though integration can vary by desktop.

The AppImage is portable and does not install a native package. FUSE-free extraction creates runtime files, and desktop-menu integration depends on your environment. AppImage does not embed the native packages' AppStream metadata.

No. Token Trail installs no tray icon, no autostart entry, no background service, and no daemon. Closing the window quits Token Trail and initiates cleanup of its owned Codex child. This does not close other Codex processes you started separately.

Open Settings & Diagnostics and expand the diagnostics preview: the application version appears alongside the Electron and Chromium versions it runs on. For package installs you can also ask your package manager directly:

Upgrades are manual. Verify the new package, close Token Trail, then install over the old native package or replace the AppImage. There is no automatic updater. Single-instance behavior prevents another active window; it does not stop a package manager from replacing files underneath a running app.

Valid 1.0.0 preferences are compatible with 2.0.0 and stay in the user-data directory. Session observations restart with the app. Upgrade instructions.

Downgrading is not a supported path. Preferences written by a newer version may carry fields an older build does not understand; an older build may reject or reset them, so back up settings you need before trying a downgrade. Published releases are immutable: files never change under the same name, and corrections ship as new versions.

Delete the AppImage, or remove the native package with the package manager used to install it. Package removal does not normally remove your user preferences or diagnostic files you exported elsewhere.

To reset owned preferences before uninstalling, use Clear data in Settings & Diagnostics. To remove remaining application runtime files, close the app and remove its verified user-data directory, normally ~/.config/Token Trail/. Check for a custom configuration location first. Do not remove Codex's own settings as part of a Token Trail uninstall.

Uninstalling guide

A quota window is a period for which Codex reports a used percentage, duration, and reset time, when available. Token Trail displays those reported fields and calculates remaining capacity and countdowns. It does not infer whether a quota follows a continuously sliding or fixed-reset policy. Different buckets can report different periods and reset times.

A reached state appears on screen only when Codex reports it, and it applies to the specific bucket Codex named. Token Trail never predicts that you will be blocked and never assigns one bucket's reached state to another window. If a limit hits, the Quota Windows route surfaces reached-state reports first in its attention ordering so you see them without hunting.

No. Countdowns are calculated from the reported reset timestamp against your local clock, but when a reset time passes, Token Trail waits for a fresh snapshot from Codex rather than assuming the reset actually occurred. Refresh, or interact with Codex, and the next approved read updates the display with reality instead of an assumption.

Every metric carries its origin with it:

• Codex-reported: read directly from Codex.
• Locally observed: measured locally by Token Trail, such as when a value was last refreshed.
• Calculated by Token Trail: derived from reported source ranges.
• Unavailable: not present, invalid, or unsupported by your Codex version, shown with a reason instead of an invented number.

Summaries over incomplete date ranges are additionally flagged as partial, with the covered dates shown, so a calculated total never quietly pretends to cover days it does not have.

Zero is a supplied measurement. Unavailable means the field was absent, invalid, unsupported, or could not be read successfully. Token Trail does not invent a zero for an unknown value. A newer compatible Codex CLI may help with unsupported methods, but an upgrade does not guarantee that an account or endpoint will expose a missing metric.

They are related but not convertible, so Token Trail never converts one into the other. Token totals describe the aggregate token activity Codex reports; quota percentages are reported separately by Codex for its own capacity windows. Blending them into a single number would invent meaning, so the interface displays them separately.

Statistics use the valid supplied days in the selected range. Missing dates are not inserted as zeros, so the daily average divides by supplied days. Complete 7-day and 30-day comparisons require both consecutive periods to be fully supplied and unambiguous; otherwise an explanation replaces the comparison values.

Coverage identifies gaps between the selected range's supplied bounds. It cannot establish coverage beyond those bounds. Heatmap cells distinguish positive, reported-zero, and missing dates.

Quota percentages, credit strings, spending controls, and reset-credit counts use different units reported through different mechanisms. Combining them into one score would invent meaning that no source stated, so Token Trail shows them side by side with their origins labeled instead. This is the same principle behind keeping token totals and quota percentages separate.

Codex may supply historical daily buckets again when you reopen the app. Token Trail does not archive them itself. Changes observed during the current app session are held in memory and restart when the process exits.

Quota resets rebase observations for the new window. An explicit sign-out or observed account-kind change resets the session baseline. Switching between accounts of the same kind without a visible sign-out cannot always be identified.

Token Trail reads data at startup, when you press Refresh, and after a rate-limit update notification. In Settings & Diagnostics, you can also enable automatic refresh. It is off by default, with a saved default interval of five minutes; supported intervals are whole numbers from 5 to 120 minutes.

The timer runs while the app is open and stops at shutdown. Notifications received during a read schedule a coalesced follow-up, so overlapping triggers do not start an unlimited number of concurrent reads.

Refresh defaults and interval limits

The dashboard distinguishes loading, ready data, signed-out, and unavailable states. Partial data means only some requested information is usable. A failed refresh can leave the last successful snapshot visible with a stale-data warning and its last successful refresh time. Visible data is not necessarily fresh data.

The automated keyboard workflows cover the primary routes and settings; press Tab after loading to reach the skip-to-content link, every route moves focus to its heading after you navigate: including Usage, whose chart loads lazily: and all routes maintain visible focus. Verified structural contracts back this up: one stable landmark inventory with a single heading per route, named regions for signed-out and error guidance, polite status semantics for connection updates, and an accessible name on every interactive control. Automated axe-core audits run against the built application alongside these semantic suites and keyboard-only end-to-end workflows in real Electron sessions. One honest gap from the support record: a full human-operated Orca screen-reader session has not yet been performed, since that requires operator judgment beyond automated checks.

Use Start date and End date on Usage. Both boundaries are inclusive; a blank boundary is unrestricted. All supplied dates clears the filter. The daily chart, table, heatmap, statistics, comparisons, and coverage use the same selection, which stays selected through refreshes. Lifetime and other Codex-reported summary values still describe the full source response, not just your selection.

To keep very long or sparse ranges responsive, the heatmap displays at most the latest 366 calendar dates within the supplied span. A note explains when it is truncated. The selected-range table and statistics still use the supplied records for that range. Missing dates are not treated as zero.

Chart geometry is capped at the largest safely representable JavaScript integer. When a value exceeds that bound, a note explains the cap. Tooltips and the table retain exact token totals, so use those values rather than comparing capped bar heights.

Stale values are the last successfully read snapshot after a newer refresh failed. Check the last successful refresh time, try Refresh, and review Diagnostics if the failure continues. A countdown or a visible chart does not prove the data was just refreshed.

No. It removes Token Trail's owned preference files and resets display choices to defaults. It does not delete Codex usage, clear your Codex login, or remove diagnostic exports saved elsewhere. A running dashboard may continue to show its in-memory snapshot, and a later refresh can read data from Codex again.

Token Trail 2.0.0 does not have a validated CLI-version field in its handshake, so it reports the version as unknown instead of guessing. Run codex --version in your terminal if you need that detail. Executable discovery and endpoint capabilities are separate observations and can still be reported.

Clipboard permission can be denied, or the browser may not expose the clipboard API. The button then shows manual-copy guidance. Select the full command and copy it yourself, or retry after adjusting browser permissions. Check the architecture in installation commands before using them.

A common cause is that the desktop launcher inherits a different PATH from your interactive shell. Confirm which executable the shell finds:

Make the directory containing that executable available in the desktop session's PATH, then restart Token Trail. If a symlink is appropriate for your installation, it must point to the executable, not just its directory. An unavailable state can also indicate a launch or protocol failure; consult Diagnostics for the observed result.

Codex itself has no authenticated session visible to Token Trail. Fix it through Codex directly:

Then refresh. Token Trail never asks for credentials itself, so there is nothing to re-enter inside the application.

For a native package, check whether /usr/share/applications/tokentrail.desktop exists and consult your package manager if it is missing. AppImage menu integration depends on a separate integration tool or your desktop.

The application and desktop entry use the tokentrail identity. xprop WM_CLASS can inspect X11 or XWayland windows; it does not inspect native Wayland windows. Desktop association behavior can vary, so report your package format and desktop session if the icon is still wrong.

One field can be missing even when other data is valid. A usage method may be unsupported by the installed Codex CLI, or the response may omit that metric. Check Diagnostics and the visible reason, then try Refresh. Updating Codex may help with compatibility but does not guarantee a missing field will appear. Broader connection failures can also mark preserved data stale or make a section unavailable.

Token Trail enforces single-instance behavior: a second launch requests focus for the already-running window, then the new process exits, a contract verified by automated lifecycle tests that observe the losing instance exit cleanly while the survivor keeps responding. This is intentional. It does not prevent a package manager from replacing application files, so close the running app before upgrading.

Export the redacted diagnostics document from Settings & Diagnostics (it previews everything before saving and is designed to exclude sensitive content), review it, then open an issue at github.com/amanalip/tokentrail/issues with the file attached. The troubleshooting guide covers most other cases, and the known-limitations page lists honestly what currently lacks evidence, such as unsigned artifacts and environments awaiting their first verified session.

Issue tracker · Known limitations