Torven — Local-first LLM usage tracker

Situation

Torven started as a local-first tracker for LLM plan and API usage, derived from the claudebar / ai-usagebar lineage, with an initial focus on Linux Waybar and a terminal TUI. The problem was practical: developers using multiple AI providers need to track usage windows, weekly quotas, credits, and reset times in different places, often through undocumented or unstable endpoints.

The first phase of the project already supported Anthropic Claude, OpenAI Codex/ChatGPT, Z.AI, and OpenRouter, exposing data as Waybar-compatible JSON and as a tabulated TUI. The technical complexity wasn't just in the UI: Anthropic, OpenAI, and Z.AI relied on undocumented endpoints, local OAuth, or credentials configured outside the repository, requiring session renewal, atomic caching, and resilient behavior when the network or schema failed.

Following this foundation, the project underwent a strategic pivot toward native macOS. Competitive research revealed a market saturated with menu bar apps for monitoring LLM usage. The product decision was to reposition Torven as a local-first tool with an auditable Rust core, native macOS UI, and a future differentiator of AI Insights with an evaluation pipeline, rather than competing as just another quota counter.

Task

My role was to lead the product's technical modeling, the separation between core and interfaces, and the transition from a Linux/TUI widget to a foundation prepared for a native macOS app. The expected success was maintaining multi-vendor monitoring reliability while giving the project a clearer architecture for the product, portfolio, and future AI engineering features.

The delivery involved architectural decisions, Rust implementation, workspace configuration, macOS pivot planning, product documentation, and preservation of existing behavior.

Action

Architecture

The ongoing architecture separates the project into a Cargo workspace with two main crates and a separate Apple project. crates/torven-core handles fetchers, domain types, configuration, caching, structured formatting, pacing, and the FFI surface. crates/torven-tui maintains the terminal interface with Ratatui as a diagnostic and cross-platform fallback tool. The macOS layer resides in apple/, consuming the Rust core via UniFFI.

flowchart LR
  SwiftUI["SwiftUI macOS app"] --> FFI["UniFFI bridge"]
  TUI["Ratatui terminal UI"] --> Core["torven-core"]
  FFI --> Core
  Core --> Anthropic["Anthropic / Claude"]
  Core --> OpenAI["OpenAI / Codex"]
  Core --> ZAI["Z.AI"]
  Core --> OpenRouter["OpenRouter"]
  Core --> Cache["Atomic local cache"]
  Core --> Config["TOML config / env credentials"]

Decisions

The first decision was to separate torven-core and torven-tui instead of maintaining a flat crate. This reduced coupling between vendor logic and the interface, prepared the FFI for Swift, and kept the TUI as a real consumer of the core.

The second decision was to use SwiftUI + Rust FFI via UniFFI, discarding the Tauri direction documented in a previous ADR. The trade-off was accepting two build systems, Cargo and Xcode, to gain a native macOS UI while preserving the Rust core as the primary asset.

pub struct UsageSnapshot {
    pub vendor: Vendor,
    pub used_percent: f32,
    pub resets_at: Option<String>,
    pub source: SnapshotSource,
}
 
pub trait UsageFetcher {
    async fn fetch_usage(&self) -> Result<UsageSnapshot, FetchError>;
}

The third decision was to treat undocumented endpoints as an explicit operational risk. The project includes make smoke with live tests ignored by default to detect schema drift with real credentials, without mixing this validation into routine testing.

It was also important to preserve resilient behavior for Waybar: user-facing command failures should still produce fallback JSON and a 0 exit code, as Waybar hides modules that fail.

Result

Metrics

The project evolved from being just a Rust port of a widget into a stronger product thesis: local-first LLM usage monitoring with an auditable Rust core, separate interfaces, and a path toward evaluable AI Insights.

The migration to a workspace also made the code more demonstrable. An evaluator can open crates/torven-core to understand fetchers, types, cache, and FFI; open crates/torven-tui to see a terminal interface consuming the same core; and open apple/ to follow the native UI progress.

Adoption, real-world usage, measured performance, and financial impact metrics do not yet appear in the current artifacts. They are intended to remain as part of the roadmap or success criteria, rather than published results.