juliantanx/aiusage repository overview

⁠ AIUsage

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.

⁠Highlights

• 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.

⁠Quick Start

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

npm install -g @juliantanx/aiusage
aiusage serve

Open http://127.0.0.1:3847 to use the dashboard. serve starts the local web UI immediately and parses local logs in the background during startup.

Prefer pnpm:

pnpm add -g @juliantanx/aiusage

Use Docker:

docker run -d \
  -p 3847:3847 \
  -e AIUSAGE_DASHBOARD_PASSWORD=change-me \
  -v ~/.aiusage:/root/.aiusage \
  juliantanx/aiusage

The container binds to 0.0.0.0 so it is reachable from outside Docker, and startup is refused unless AIUSAGE_DASHBOARD_PASSWORD is set to a non-empty value; replace change-me with your own password. 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⁠.

⁠Common Commands

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

⁠Supported Tools

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

⁠Dashboard Password

The dashboard binds to 127.0.0.1 by default. Use aiusage serve --host ::1 for IPv6 loopback. Local access can remain passwordless; set AIUSAGE_DASHBOARD_PASSWORD to require authentication for detailed APIs, including the detailed summary, quotas, and settings. Only the aggregate totals shown on the home page stay public, through the minimal /api/home-summary endpoint.

To allow network access, explicitly use aiusage serve --host 0.0.0.0 (or --host :: for IPv6) and set a non-empty AIUSAGE_DASHBOARD_PASSWORD; startup is refused without it. The Docker image uses this explicit network binding, so the password is mandatory there. For remote access, use HTTPS through a trusted reverse proxy that preserves the browser-facing Host header and replaces X-Forwarded-Proto with the browser-facing scheme.

The API accepts same-origin browser requests only; cross-origin integrations are no longer supported. Native local clients can omit Origin. Credential settings show configured state and accept replacements; existing secret values and credential references are never returned. Blank credential fields keep the saved value. See local API security and compatibility⁠.

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⁠.

⁠Privacy and Data

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

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. GitHub sync prefers aiusage github login --repo OWNER/REPO or Connect GitHub in local settings, using a least-privilege GitHub App without an AIUsage account. Fine-grained PATs remain an advanced fallback. See GitHub App setup and migration⁠.
• AIUsage Cloud sync is available after device authorization: run aiusage login, then aiusage init --backend cloud and aiusage sync.
• If versions up to 1.5.13 caused duplicate cross-device records, use aiusage sync --repair to inspect them before applying cleanup. See the sync repair guide⁠. Every device namespace is an authoritative snapshot of that device; see the sync model⁠.
• 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.

⁠Desktop Widget

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⁠.

⁠Development

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

pnpm dev builds the shared packages and starts only the local dashboard at http://127.0.0.1:3847. To develop account, authorization, or cloud-sync flows against the local official site, run pnpm dev:site separately on port 4000 and set SITE_URL=http://localhost:4000 in packages/cli/.env. Without that override, the CLI uses https://aiusage.jtanx.com.

Project layout:

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

⁠Documentation

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

⁠Contributors

Thanks to these wonderful people (emoji key⁠):

Julian⁠ 💻⁠ 📖⁠ 🚇⁠ 🔧⁠	Fiveonine⁠ 💻⁠	joyshan1986⁠ 💻⁠	zhaolu83949426-hub⁠ 💻⁠	Mnoisec⁠ 💻⁠	jlxyfll⁠ 💻⁠	Harlan Hu⁠ 💻⁠
Mingde⁠ 🐛⁠	Aaron C⁠ 💻⁠ 📖⁠

This project follows the all-contributors⁠ specification. Contributions of any kind welcome!

⁠Community

• 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.

⁠License

MIT⁠ © Julian⁠