openusage: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is this project?

OpenUsage is a terminal dashboard (TUI) for monitoring AI coding tool usage and spend. It auto-detects AI tools and API keys on the workstation and displays live data using Bubble Tea. Written in Go, requires CGO enabled (for mattn/go-sqlite3 used by the Cursor provider).

Commands

make build          # build binary to ./bin/openusage (includes version ldflags)
make test           # run all tests with -race and coverage
make test-verbose   # verbose test output
make lint           # golangci-lint (skips gracefully if not installed)
make fmt            # go fmt ./...
make vet            # go vet ./...
make run            # go run cmd/openusage/main.go
make demo           # build and run demo with dummy data (for screenshots)
make sync-tools     # regenerate all AI tool configs from canonical template

# Run a single test
go test ./internal/providers/openai/ -run TestFetch -v

# Run provider tests only
go test ./internal/providers/...

Code style

• Standard gofmt with goimports. Tabs for indentation.
• Import groups (separated by blank lines): stdlib, third-party, internal.
• Bubble Tea aliased as tea.
• Errors wrapped with provider prefix: fmt.Errorf("openai: creating request: %w", err).
• Pointer fields for optional numerics: Limit *float64.
• JSON tags use snake_case with omitempty for optional fields.

Architecture

Data flow

There are two runtime modes:

Direct mode (default):

main.go → config.Load() → runDashboard()
  → detect.AutoDetect() → registers providers from providers.AllProviders()
  → polls providers concurrently on a ticker
  → snapshots sent to TUI via tea.Program.Send(SnapshotsMsg)

Daemon mode (openusage telemetry):

daemon.Server polls providers → ingests into SQLite (telemetry.Store)
  → TUI connects via daemon.ViewRuntime over unix socket
  → daemon.ReadModel hydrates snapshots from stored events
  → telemetry events deduplicated, mapped to providers via ProviderLinks