Agent Usage

A desktop app for local usage, cost, throughput, and session analytics across AI coding agents.

中文文档

Agent Usage reads the session and usage records already stored on this computer, normalizes them into a local SQLite index, and presents them in a focused desktop workspace. It is designed for one person inspecting their own coding-agent activity; there is no account, cloud database, or session upload.

Highlights

• Compare token usage, estimated cost, prompts, sessions, API calls, RPM, and TPM across supported agents.
• Filter the workspace by time range, source, model, and project, then carry the same query into session search.
• Search and inspect readable Claude Code and Codex event timelines, including tool calls and errors.
• Scan incrementally, deduplicate records, and rebuild the local index from source files when needed.
• Use immutable pricing snapshots with bundled offline fallback, online LiteLLM refresh, and JSON import.
• Run from the system tray with autostart, cost notifications, English/Chinese UI, and light/dark themes.

Supported Sources

Collectors resume from stored file offsets, so unchanged JSONL content is not parsed again. OpenCode is read from its local SQLite database. All sources share one statistical model, while deep event indexing is intentionally limited to Claude Code and Codex in v2.0.

Install

Download an installer from GitHub Releases:

macOS Intel and Linux users can build from source. These platforms do not have official v2.0 installers.

The macOS build is currently unsigned. After moving the app to Applications, remove its quarantine attribute once if macOS reports that the app is damaged:

xattr -cr "/Applications/Agent Usage.app"

Launch Agent Usage. The sidecar starts on a loopback-only dynamic port and scans enabled local sources in the background.

Privacy and Network Access

Raw agent files remain the source of truth. The SQLite index and configuration stay on this computer and can be rebuilt. Session content is never uploaded, and the local API binds to loopback.

The only routine network request is model-pricing refresh from LiteLLM's jsDelivr mirror. A bundled catalog lets first-run cost estimation work offline. Online refresh and manual import never rewrite costs already assigned from historical pricing snapshots.

Metric Semantics

Token totals use four non-overlapping components:

total input  = non-cached input + cache read input + cache creation input
total output = output tokens
total tokens = total input + total output

Reasoning output is informational and is already a subset of output tokens, so it is not added again. RPM and TPM are locally observed throughput, not provider quota, remaining capacity, or rate-limit utilization. Displayed cost is a local estimate, not a provider invoice.

Configuration

The desktop app creates ~/.config/agent-usage/config.yaml on first launch. Data sources and application behavior can also be managed in Settings.

server:
  port: 9800
  bind_address: "127.0.0.1"

collectors:
  claude:
    enabled: true
    paths: ["~/.claude/projects"]
    scan_interval: 60s
  codex:
    enabled: true
    paths: ["~/.codex/sessions"]
    scan_interval: 60s
  openclaw:
    enabled: true
    paths: ["~/.openclaw/agents"]
    scan_interval: 60s
  opencode:
    enabled: true
    paths: ["~/.local/share/opencode/opencode.db"]
    scan_interval: 60s

storage:
  path: "~/.config/agent-usage/agent-usage.db"

pricing:
  sync_interval: 1h

Build From Source

Prerequisites: Go 1.25+, Node.js 24+, and Rust stable. Linux also requires libwebkit2gtk-4.1-dev and libappindicator3-dev.

npm install

# macOS Apple Silicon sidecar
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 \
  go build -o src-tauri/binaries/agent-usage-aarch64-apple-darwin .

npx tauri dev

For a production build, prepare the sidecar matching the target and run npx tauri build:

# macOS Intel
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 \
  go build -o src-tauri/binaries/agent-usage-x86_64-apple-darwin .

# Linux x64
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -o src-tauri/binaries/agent-usage-x86_64-unknown-linux-gnu .

# Windows x64
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 \
  go build -o src-tauri/binaries/agent-usage-x86_64-pc-windows-msvc.exe .

Tauri requires the sidecar name agent-usage-{rust-target-triple}[.exe].

The Go backend can also run on its own:

go build -o agent-usage-desktop .
./agent-usage-desktop
./agent-usage-desktop --config path/to/config.yaml
./agent-usage-desktop --port 9800
./agent-usage-desktop version

Run the complete local verification suite with:

go test ./...
go vet ./...
npm test
npm run build
cargo test --manifest-path src-tauri/Cargo.toml

Architecture

The React and TypeScript frontend runs inside Tauri v2. Rust manages the desktop window, tray, notifications, autostart, and Go sidecar lifecycle. The pure-Go sidecar collects local records, stores the normalized index with modernc.org/sqlite (no CGO), calculates snapshot-based costs, and serves the loopback REST API consumed by the UI.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow and SECURITY.md for private vulnerability reporting.

Community

• GitHub Issues
• linux.do

License

Agent Usage is licensed under the Apache License 2.0.