Local-first usage tracker for AI coding assistants.

Website · Docs · Leaderboard · English | 中文

Track tokens, cost, sessions, models, projects, tool calls, and quota pressure across 20+ AI coding tools in one local dashboard. Local use needs no account, sends no telemetry, and does not require cloud sync.

• One local dashboard for tokens, cost, sessions, models, projects, tool calls, and quotas.
• Broad parser support for Claude Code, Codex, OpenCode, Cursor, Copilot, Gemini CLI, and more.
• Optional sync through GitHub, S3, R2, or MinIO.
• Optional public leaderboard with signed aggregate uploads only.
• Desktop widget for a tray/menu-bar glance at recent usage.
• Private by default: local parsing and local dashboards do not upload your prompts, completions, source code, or file paths.

Requirements: Node.js 20+ on macOS, Linux, or Windows.

npm install -g @juliantanx/aiusage
aiusage serve

Open http://localhost:3847 to use the dashboard. serve parses once on startup and then serves the local web UI.

Prefer pnpm:

pnpm add -g @juliantanx/aiusage

Use Docker:

docker run -d \
  -p 3847:3847 \
  -v ~/.aiusage:/root/.aiusage \
  juliantanx/aiusage

Docker persists AIUsage data with the ~/.aiusage mount. To parse AI tool logs from the host, also mount each source log directory and configure the matching AIUSAGE_*_PATH variable. See the Docker docs.

Full CLI reference: aiusage.jtanx.com/docs#cli-reference.

Default paths and environment variable overrides are documented in Data Sources and Source Env Vars.

The local dashboard is open on localhost by default. Set AIUSAGE_DASHBOARD_PASSWORD to protect dashboard APIs.

For PM2 background services, pass the same variable when starting aiusage pm2-start, and use pm2 restart aiusage-server --update-env after changing it. Details: Dashboard Password and PM2.

AIUsage is designed to be local-first.

• Local parsing reads tool logs and stores parsed usage in ~/.aiusage/cache.db.
• Local dashboard mode does not require an account and does not send telemetry.
• Optional sync is user-configured and can use GitHub, S3, R2, or MinIO.
• Optional leaderboard uploads contain aggregate token totals for ranking periods. They do not include prompts, completions, source code, file paths, or local cost estimates.
• Cost is an estimate based on pricing metadata and can change when pricing is refreshed or recalculated.
• Historical totals depend on whether each AI tool still retains its source logs or local databases.

Security issues should be reported privately when possible. See SECURITY.md.

Sync and leaderboard are independent optional features.

• Sync keeps your own devices aligned through GitHub, S3, R2, or MinIO. Configure it with aiusage init, then run aiusage sync.
• Leaderboard is public ranking for users who explicitly upload aggregate totals. Authorize a device with aiusage login, then run aiusage upload.
• Anonymous mode is available in site settings for leaderboard participation.

The official site handles accounts, OAuth login, profile settings, authorized devices, upload review status, and admin moderation. The CLI handles local parsing, local dashboards, sync, terminal summaries, and signed uploads.

Install the optional tray/menu-bar widget:

npm install -g @juliantanx/aiusage-widget
aiusage-widget

The widget reads the same local AIUsage database and can open the full dashboard from its tray menu. See Widget docs.

git clone https://github.com/juliantanx/aiusage.git
cd aiusage
pnpm install
pnpm build
pnpm test
pnpm dev

Project layout:

Contributions are welcome. Read CONTRIBUTING.md, use the issue templates, and run pnpm test before opening a PR.

• Full docs
• CLI reference
• Docker deployment
• Sync setup
• Widget
• Changelog
• Security policy

• Bugs: GitHub Issues
• Feature requests: GitHub Issues
• Questions: GitHub Discussions

linux.do - thanks to the linux.do community for support and inspiration during the development of this project.

MIT