handlecusion/tokcat

What the repo is

Tokcat is a macOS menu-bar desktop app for tracking AI coding token usage and cost. Architecturally it is a local-first Tauri 2 application: a Rust native shell handles data collection and macOS integration, while a React/Vite frontend renders the dashboard.

Top-level runtime split

The repo is organized around two execution worlds:

• src-tauri/: the native backend, packaging, tray/menu-bar behavior, update checks, and local data access.

• src/: the frontend UI for the popover dashboard, settings, graphs, and summary cards.

This boundary is the main architecture seam: Rust produces structured usage/state data; React consumes and visualizes it.

Local usage ingestion

The backend reads local session logs from supported AI clients rather than sending data to Tokcat services. The ingest layer appears to live in modules such as agent_usage.rs, usage_tail.rs, and usage_graph.rs, with state.rs likely holding shared cached state. The README describes the backend as scanning local client stores, deduplicating, normalizing token fields, and estimating cost when needed.

Live activity pipeline

There is a separate live/session tailing path that tracks recent log growth and turns it into a short-window throughput signal (tokens per minute). That live signal feeds both the menu-bar title/animation and the Live session card in the UI. This is distinct from historical usage aggregation, which is more batch-like and dashboard-oriented.

Vendor quota lookups are a separate boundary

Tokcat also queries direct vendor endpoints for agent-limit/quota data when local OAuth credentials exist. The README calls out Codex and Claude usage windows specifically. This means the app has two data sources:

• local logs for historical usage/cost

• external vendor APIs for quota/limit cards

These are separate from each other and from any analytics/telemetry, which the app does not appear to have.

UI composition

The frontend is a dashboard built from composable cards and controls in src/components/. Key visible areas include:

• overview/client tabs

• 2D token graphs

• 3D contribution graph

• streak summaries

• live trace rows

• agent-limit cards

• settings panel

The main app shell is in src/App.tsx, with shared styling in src/styles.css.

Frontend data/model layer

src/lib/ contains the frontend’s data and presentation logic: formatting, stats, streaks, themes, runtime/settings helpers, usage transformations, and updater integration. src/hooks/ (useAgentUsage.ts, useGraphStream.ts) likely bridges the backend data stream into React state. This is the UI-side counterpart to the Rust ingestion/cache layer.

Shared state and settings

Settings are persisted locally and influence both backend and frontend behavior: menu-bar title mode, animation style, launch-at-login, theme, live trace splitting, and update checks. The presence of src/lib/settings.ts and backend state.rs indicates a cross-layer configuration/state model, with the backend likely providing authoritative app state and the UI reflecting it.

Update and release flow

Tokcat includes an in-app updater that checks signed release metadata on launch and periodically thereafter. This is backed by GitHub Releases and a release pipeline in .github/workflows/. The update mechanism is part of the product architecture because it is a runtime network dependency separate from usage collection.

Development and mock data path

The repo supports a web/dev mode with server.js and Vite. The README notes that the frontend can run in a browser against a mock graph payload, while pnpm tauri:dev connects the UI to the native backend for real local log reading. That means there are two dev experiences: browser-only UI development and full desktop integration testing.

Docs, marketing, and generated assets

docs/, public/, design/, and remotion/ support the project’s documentation and landing/media pipeline. The remotion/ folder plus scripts like render_docs_gifs.py and regenerate_* indicate generated visual assets for screenshots, gifs, and motion clips. These are not core runtime subsystems, but they matter for the repo’s packaging and release surface.

Platform and packaging boundaries

The app targets macOS 11+ on Apple Silicon and Intel. Packaging is handled through Tauri’s macOS build output, DMGs, and a Homebrew cask workflow. The architecture therefore has a clear native-app boundary: local desktop runtime, signed releases, and no server-side product backend.

High-level data flow

The end-to-end flow is:

local AI client logs and credentials → Rust backend scans/normalizes/caches usage and live signals → optional vendor quota calls and update checks → React UI renders dashboards, graphs, streaks, and settings → tray/menu-bar surfaces summary state for glanceable use.