Home

budi wiki

budi — local-first cost analytics for AI coding agents. Tracks tokens, costs, and usage per message across Claude Code, Cursor, Codex CLI, Copilot CLI, and Copilot Chat by tailing the JSONL transcripts those agents already write to disk. Optional cloud sync pushes pre-aggregated daily rollups to a team dashboard — prompts, code, and responses never leave the machine.

This wiki is the durable design record for budi: architecture decisions, undocumented upstream contracts, and operational references that need to outlive any single release. Implementation truth lives in the source code; product overview lives in README.md; the canonical AI-agent / architecture reference lives in SOUL.md.

Where things live

Core (Rust workspace)	siropkin/budi
Cloud dashboard + ingest API	siropkin/budi-cloud — app.getbudi.dev
Cursor / VS Code extension	siropkin/budi-cursor
JetBrains plugin	siropkin/budi-jetbrains — Marketplace
Homebrew tap	siropkin/homebrew-budi
Marketing site	siropkin/getbudi.dev — getbudi.dev
Issue tracker	GitHub Issues on siropkin/budi (also: discussions, releases)
Owner	@siropkin (Ivan Seredkin)

Start here

If you are…	Read
An end user installing or using budi	README.md
A contributor opening a PR	CONTRIBUTING.md
An AI coding agent working in this repo	SOUL.md (canonical) — AGENTS.md and CLAUDE.md are thin pointers
Looking for design principles	docs/design-principles.md
Building a status line / consumer of the analytics API	docs/statusline-contract.md
Trying to understand why a piece of code looks the way it does	This wiki — design rationale lives here

Architecture decisions

Durable design records. Each ADR is a self-contained page with a "Last verified" date at the bottom. When a contract shifts, the ADR is amended in the same PR as the code change.

Data, privacy, and identity

Cloud Data Contract and Privacy Boundary	What leaves the machine and what never does. Sync payload shape, identity model (workspace / user / device), never-upload fields, idempotency, auth. (ADR-0083)

Live ingestion

JSONL Tailing as Live Ingestion	Why JSONL tailing replaced the reverse proxy as the sole live ingestion path. Latency budget, attribution-from-transcript contract, no-fallback policy. (ADR-0089)
Cursor Usage API Contract	Undocumented Cursor dashboard API: endpoints, auth via state.vscdb, response shapes, lag profile, and the 2026-04-23 pivot to cursorDiskKV bubbles as primary data source. (ADR-0090)

Pricing

Model Pricing – Embedded Baseline and Runtime Refresh	LiteLLM manifest as source of truth: embedded baseline at build time, daily HTTPS refresh, immutable history via pricing_source tagging, validation guards. (ADR-0091)
Custom Team Pricing and Effective Cost	Team-pricing overlay: cost_cents_ingested vs cost_cents_effective, cloud-managed price lists, recompute semantics, dashboard parity. (ADR-0094)

Provider contracts

Copilot Chat Data Contract	Copilot Chat (VS Code-family) transcript discovery, parsing across five envelope shapes and five token-key dispatches, model resolution, GitHub Billing API truth-up. (ADR-0092)
Copilot Chat – JetBrains Storage Contract	JetBrains-specific Nitrite DB layout for Copilot Chat: phase 1 discovery (sessions table), phase 2 (token attribution). (ADR-0093)

Operational references

Reference docs that sit alongside the ADRs. Where ADRs pin what was decided and why, these pages document how the system runs today — install, sync, observability, release. Each one points at the relevant ADR for design rationale and at current source files for implementation truth.

Daemon Lifecycle and Autostart	The launchd / systemd / Task Scheduler contract, daemon ↔ CLI version contract, port-7878 takeover, offline behavior, failure-mode playbook.
Provider Plugin Contract	The Provider trait surface, the shared enricher chain, the current set of five providers, the recipe for adding a sixth, and the privacy rules parse_file must uphold.
Cloud Sync Mechanics	The daemon-side sync worker: watermark tracking, retry/backoff matrix, manual paths (budi cloud sync / cloud status), the five-state onboarding UX.
Statusline Integration	The shared JSON contract across Claude Code, Cursor, VS Code, and the cloud dashboard. Two scopes (provider / host), slot vocabulary, install paths, render contract, state indicators.
Operations and Observability	Local-side health: budi doctor's three attribution checks, pricing observability, schema audit + repair, session vitals freshness, the e2e regression-guard discipline. Cloud-side ops surface (still being built).
Release and Versioning	The tag-driven pipeline (stable vs rc), schema-version policy, dual-emit / dual-accept windows for cross-repo renames, upgrade-path compatibility guards, distribution channels.

How this wiki is organized

• ADRs are pinned to the v8.x architecture and amended in-place when their contract shifts. Amendments land at the top of the page as banners; superseded ADRs are marked, not deleted.
• Reference docs are a layer on top. When the underlying ADR is amended, the reference doc that depends on it gets revisited in the same PR.
• Cross-page links use wiki-link syntax ([[Page Name]]) so they survive page renames. Links to in-repo files use absolute GitHub URLs against main.
• Issue and PR references are full GitHub URLs (#NNN → https://github.com/siropkin/budi/issues/NNN) so they work when opened from a clone of the wiki.
• "Last verified against code on YYYY-MM-DD" at the bottom of each ADR is the trustworthiness marker. If you're reading an ADR whose "Last verified" is more than ~3 months old, treat the details as a starting point and confirm against current source.

ADRs 0081, 0082, 0086, 0088 are historical (pre-tailer pivot). They lived in the in-tree docs/adr/ directory that was retired in v8.3.0. Where this wiki references them, the reference is to capture history — those ADRs are not authoritative for current behavior.