Torven — Local-first LLM usage tracker

Situation

Torven comecou como um tracker local-first de uso de planos e APIs de LLMs, derivado da linhagem claudebar / ai-usagebar, com foco inicial em Waybar no Linux e uma TUI terminal. O problema era pratico: desenvolvedores que usam multiplos provedores de IA precisam acompanhar janelas de uso, cotas semanais, creditos e reset times em lugares diferentes, frequentemente em endpoints nao documentados ou pouco estaveis.

A primeira fase do projeto ja suportava Anthropic Claude, OpenAI Codex/ChatGPT, Z.AI e OpenRouter, expondo os dados como JSON compativel com Waybar e como uma TUI tabulada. A complexidade tecnica nao estava so na UI: Anthropic, OpenAI e Z.AI dependiam de endpoints nao documentados, OAuth local ou credenciais configuradas fora do repositorio, renovacao de sessao, cache atomico e comportamento resiliente quando a rede ou o schema falhasse.

Depois dessa base, o projeto passou por um pivot estrategico para macOS nativo. A pesquisa competitiva mostrou um mercado saturado de apps de menu bar para monitorar uso de LLMs. A decisao de produto foi reposicionar Torven como uma ferramenta local-first com Rust core auditavel, UI macOS nativa e diferencial futuro de AI Insights com pipeline de avaliacao, em vez de competir apenas como mais um contador de quota.

Task

Meu papel foi liderar a modelagem tecnica do produto, a separacao entre core e interfaces, e a transicao de um widget Linux/TUI para uma base preparada para app macOS nativo. O sucesso esperado era manter a confiabilidade do monitoramento multi-vendor enquanto o projeto ganhava uma arquitetura mais clara para produto, portfolio e futuras features de AI engineering.

A entrega envolvia decisoes de arquitetura, implementacao Rust, configuracao de workspace, planejamento do pivot macOS, documentacao de produto e preservacao de comportamento existente.

Action

Architecture

A arquitetura em andamento separa o projeto em um workspace Cargo com dois crates principais e um projeto Apple separado. crates/torven-core concentra fetchers, tipos de dominio, configuracao, cache, formatacao estruturada, pacing e a superficie FFI. crates/torven-tui mantem a interface terminal com Ratatui como ferramenta de diagnostico e fallback cross-platform. A camada macOS fica em apple/, consumindo o 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

A primeira decisao foi separar torven-core e torven-tui, em vez de manter um crate flat. Isso reduziu o acoplamento entre logica de vendor e interface, preparou a FFI para Swift e manteve a TUI como consumidor real do core.

A segunda decisao foi usar SwiftUI + Rust FFI via UniFFI, descartando a direcao Tauri documentada em ADR anterior. O trade-off foi aceitar dois sistemas de build, Cargo e Xcode, para ganhar UI nativa macOS e preservar o Rust core como ativo principal.

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>;
}

A terceira decisao foi tratar endpoints nao documentados como risco operacional explicito. O projeto inclui make smoke com testes live ignorados por padrao para detectar drift de schema com credenciais reais, sem misturar essa validacao ao teste rotineiro.

Tambem foi importante preservar comportamento resiliente para Waybar: falhas de comando user-facing ainda devem produzir JSON fallback e exit code 0, porque Waybar esconde modulos que falham.

Result

Metrics

O projeto deixou de ser apenas uma porta Rust de um widget e passou a ter uma tese de produto mais forte: monitoramento local-first de uso de LLMs com core Rust auditavel, interfaces separadas e caminho para AI Insights avaliaveis.

A migracao para workspace tambem tornou o codigo mais demonstravel. Um avaliador consegue abrir crates/torven-core para entender fetchers, tipos, cache e FFI, abrir crates/torven-tui para ver uma interface terminal consumindo o mesmo core, e abrir apple/ para acompanhar a UI nativa.

Metricas de adocao, uso real, performance medida e impacto financeiro ainda nao aparecem nos artefatos atuais. Elas devem permanecer como roadmap ou criterio de sucesso, nao como resultado publicado.