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 and undocumented upstream contracts 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 page is a self-contained ADR 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)

Still to write

Placeholders for ADRs the project keeps hitting in conversation but hasn't pinned yet. Each one is a wiki stub at the linked page with a short note on what it should cover.

• Daemon Lifecycle and Autostart — launchd / systemd / Task Scheduler contracts, takeover behavior, version mismatch handling
• Provider Plugin Contract — the Provider trait surface: discover_files / parse_file / watch_roots / sync_direct, how to add a new agent
• Cloud Sync Mechanics — daemon-side worker loop, watermark/idempotency, retry/backoff, manual sync paths
• Statusline Integration — the JSON shape, slot vocabulary, host- vs provider-scoped surfaces, install paths
• Operations and Observability — Datadog index, OpsGenie recipient, Slack alert, SLOs (once cloud is GA)
• Release and Versioning — release checklist, schema-version policy, embedded-manifest refresh, upgrade compatibility windows

How this wiki is organized

• One ADR per page. 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.
• Cross-ADR 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 rendered with https://github.com/siropkin/budi/issues/NNN) so they keep working 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.
• Per-page status banners at the top of each ADR carry amendment history, supersession links, and any drift notes.

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.