Agentusage Architecture

Local-first ingestion, normalization, storage, and usage delivery

Agentusage Architecture Local-first ingestion, normalization, storage, and usage delivery agentusage normalization core Local Agent History · JSONL · logs · local DBs · Architecture component · Codex · Claude · OpenCode · Copilot Local Agent History JSONL · logs · local DBs Codex · Claude · OpenCode · Copilot Telemetry Hooks · agent event payloads · Architecture component · optional live path Telemetry Hooks agent event payloads optional live path Provider Readers · format-specific adapters · Architecture component · incremental cursors Provider Readers format-specific adapters incremental cursors Hook Adapters · shared event envelope · Architecture component · Codex · Claude · OpenCode Hook Adapters shared event envelope Codex · Claude · OpenCode Ingestion Pipeline · parse · classify · dedupe · agentusage normalization core · idempotent batches Ingestion Pipeline parse · classify · dedupe idempotent batches Normalized Event Model · usage · raw · metrics · cursors · agentusage normalization core · provider-independent Normalized Event Model usage · raw · metrics · cursors provider-independent SQLite · one DB per provider · Architecture component · default · local SQLite one DB per provider default · local PostgreSQL · shared backend · Architecture component · explicit opt-in PostgreSQL shared backend explicit opt-in Query & Summary Engine · windows · trends · latest quota · Architecture component · read-only serving path Query & Summary Engine windows · trends · latest quota read-only serving path Browser Dashboard · embedded HTML · charts · PNG · Architecture component · 127.0.0.1:8787 Browser Dashboard embedded HTML · charts · PNG 127.0.0.1:8787 Terminal & Reports · TUI · daily · range · Architecture component · agentusage / au Terminal & Reports TUI · daily · range agentusage / au Local JSON API · providers · summary · trend · Architecture component · scriptable Local JSON API providers · summary · trend scriptable default opt-in Legend External Backend Message bus Database Frontend

Normalize once

  • • Provider readers preserve source-specific detail
  • • Usage, raw payloads, metrics, and cursors stay queryable
  • • Stable deduplication keys keep synchronization idempotent

Local by default

  • • SQLite keeps provider data on the developer machine
  • • The Rust binary embeds the web UI and loopback API
  • • CLI reports and the TUI reuse the same summaries

Status stays current

  • • Historical usage comes from normalized events
  • • Quota comes from the newest quota-bearing raw payload
  • • PostgreSQL is used only when shared storage is intentional

Architecture diagram • Built with Archify • Hover to trace • R route • Click to focus • +/− zoom • M radar • [/] views • P play story • T theme • E export