@juliantanx/aiusage 1.4.0 → 1.5.0

package/README.md

@@ -1,30 +1,86 @@
-# aiusage — AI Coding Assistant Usage Tracker
+<h1 align="center">
+  <img src="https://cdn.jsdelivr.net/gh/juliantanx/aiusage@main/packages/site/static/logo-icon.svg" alt="AIUsage logo" width="42" align="absmiddle" />
+  AIUsage
+</h1>
 
-[![npm version](https://img.shields.io/npm/v/@juliantanx/aiusage)](https://www.npmjs.com/package/@juliantanx/aiusage)
-[![CI](https://github.com/juliantanx/aiusage/actions/workflows/test.yml/badge.svg)](https://github.com/juliantanx/aiusage/actions/workflows/test.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  Local-first usage tracker for AI coding assistants.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@juliantanx/aiusage"><img src="https://img.shields.io/npm/v/@juliantanx/aiusage" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@juliantanx/aiusage"><img src="https://img.shields.io/npm/dm/@juliantanx/aiusage" alt="npm downloads" /></a>
+  <a href="https://github.com/juliantanx/aiusage/actions/workflows/test.yml"><img src="https://github.com/juliantanx/aiusage/actions/workflows/test.yml/badge.svg" alt="CI" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+</p>
 
-**[aiusage.jtanx.com](https://aiusage.jtanx.com)** · English | [中文](https://github.com/juliantanx/aiusage/blob/main/README_zh.md)
+<p align="center">
+  <strong><a href="https://aiusage.jtanx.com">Website</a></strong> ·
+  <strong><a href="https://aiusage.jtanx.com/docs">Docs</a></strong> ·
+  <strong><a href="https://aiusage.jtanx.com/leaderboard">Leaderboard</a></strong> ·
+  English | <a href="https://github.com/juliantanx/aiusage/blob/main/README_zh.md">中文</a>
+</p>
 
-Track token usage, cost, and sessions across **22 AI coding tools** in one local dashboard. No accounts. No telemetry. No cloud required.
+Track tokens, cost, sessions, models, projects, tool calls, and quota pressure across **22 AI coding tools** in one local dashboard. Local use needs no account, sends no telemetry, and does not require cloud sync.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/juliantanx/aiusage/a527444cf87a9c1e92f1440282ed4e94f744b910/packages/site/static/screenshots/dashboard-home.png" alt="aiusage dashboard home" width="32%" />
-  <img src="https://raw.githubusercontent.com/juliantanx/aiusage/a527444cf87a9c1e92f1440282ed4e94f744b910/packages/site/static/screenshots/overview.png" alt="aiusage overview dashboard" width="32%" />
-  <img src="https://raw.githubusercontent.com/juliantanx/aiusage/a527444cf87a9c1e92f1440282ed4e94f744b910/packages/site/static/screenshots/sessions.png" alt="aiusage sessions dashboard" width="32%" />
+  <img src="https://cdn.jsdelivr.net/gh/juliantanx/aiusage@b179e5a37c92e7040a07b84a7b2048821d120aed/packages/site/static/screenshots/aiusage-demo.gif" alt="AIUsage dashboard demo" width="92%" />
 </p>
 
+## 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 official cloud sync, 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
 
-**Prerequisites:** Node.js 20+
+**Requirements:** Node.js 20+ on macOS, Linux, or Windows.
 
 ```bash
 npm install -g @juliantanx/aiusage
-aiusage parse
 aiusage serve
 ```
 
-Open `http://localhost:3847` to explore the dashboard.
+Open `http://localhost:3847` to use the dashboard. `serve` parses once on startup and then serves the local web UI.
+
+Prefer pnpm:
+
+```bash
+pnpm add -g @juliantanx/aiusage
+```
+
+Use Docker:
+
+```bash
+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](https://aiusage.jtanx.com/docs#docker).
+
+## Common Commands
+
+| Command | What it does |
+|---|---|
+| `aiusage` / `aiusage summary` | Print a terminal summary |
+| `aiusage parse` | Parse supported local AI tool logs |
+| `aiusage serve` | Start the local dashboard on port `3847` |
+| `aiusage status` | Show data source and local database status |
+| `aiusage export --range month` | Export usage data |
+| `aiusage init` | Configure optional sync |
+| `aiusage sync` | Sync with the configured backend |
+| `aiusage widget` | Launch the desktop tray widget |
+| `aiusage leaderboard` | View public leaderboard rankings |
+| `aiusage login` / `aiusage upload` | Authorize this device and upload aggregate leaderboard data |
+| `aiusage pm2-start` | Run dashboard and widget as PM2 background services |
+
+Full CLI reference: [aiusage.jtanx.com/docs#cli-reference](https://aiusage.jtanx.com/docs#cli-reference).
 
 ## Supported Tools
 
@@ -36,36 +92,105 @@ Open `http://localhost:3847` to explore the dashboard.
 | `Roo Code` | `Zed` | `Goose` | `oh-my-pi` | `pi` |
 | `Craft` | `Droid` | | | |
 
-## Why aiusage
+Default paths and environment variable overrides are documented in [Data Sources](https://aiusage.jtanx.com/docs#settings-sources) and [Source Env Vars](https://aiusage.jtanx.com/docs#settings-env).
+
+## Dashboard Password
+
+The local dashboard is open on localhost by default. Set `AIUSAGE_DASHBOARD_PASSWORD` to protect dashboard APIs.
+
+| Shell | Command |
+|---|---|
+| macOS / Linux | `AIUSAGE_DASHBOARD_PASSWORD="change-me" aiusage serve` |
+| Windows PowerShell | `$env:AIUSAGE_DASHBOARD_PASSWORD="change-me"; aiusage serve` |
+| Windows CMD | `set AIUSAGE_DASHBOARD_PASSWORD=change-me && aiusage serve` |
 
-Your AI coding tools each log usage separately — different formats, different machines, no shared view. aiusage pulls it all into one local dashboard:
+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](https://aiusage.jtanx.com/docs#dashboard-password) and [PM2](https://aiusage.jtanx.com/docs#pm2).
 
-- **One dashboard** for tokens, cost, model mix, and tool-call activity
-- **Multi-machine sync** via GitHub, S3, or R2 — entirely optional
-- **Your data stays local** by default
+## 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 official cloud sync, 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](./SECURITY.md).
+
+## Sync and Leaderboard
+
+Sync and leaderboard are independent optional features.
+
+- **Sync** keeps your own devices aligned through official cloud sync, 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](https://aiusage.jtanx.com/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:
+
+```bash
+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](https://aiusage.jtanx.com/docs#widget).
+
+## Development
+
+```bash
+git clone https://github.com/juliantanx/aiusage.git
+cd aiusage
+pnpm install
+pnpm build
+pnpm test
+pnpm dev
+```
+
+Project layout:
+
+| Path | Purpose |
+|---|---|
+| `packages/core` | Shared types, schema, pricing, and utilities |
+| `packages/cli` | Published CLI, parsers, local API server, sync, PM2 helpers |
+| `packages/web` | Local dashboard UI bundled into the CLI |
+| `packages/widget` | Electron tray/menu-bar widget |
+| `packages/site` | Official website, docs, accounts, uploads, leaderboard |
+
+Contributions are welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md), use the issue templates, and run `pnpm test` before opening a PR.
 
 ## Documentation
 
-Full documentation — CLI reference, Docker deployment, sync setup, desktop widget, and more — is available on the **[Docs page](https://aiusage.jtanx.com/docs)**.
+- [Full docs](https://aiusage.jtanx.com/docs)
+- [CLI reference](https://aiusage.jtanx.com/docs#cli-reference)
+- [Docker deployment](https://aiusage.jtanx.com/docs#docker)
+- [Sync setup](https://aiusage.jtanx.com/docs#sync)
+- [Widget](https://aiusage.jtanx.com/docs#widget)
+- [Changelog](./CHANGELOG.md)
+- [Security policy](./SECURITY.md)
+
+## Community
 
-## Friends
+- Bugs: [GitHub Issues](https://github.com/juliantanx/aiusage/issues/new?template=bug_report.md)
+- Feature requests: [GitHub Issues](https://github.com/juliantanx/aiusage/issues/new?template=feature_request.md)
+- Questions: [GitHub Discussions](https://github.com/juliantanx/aiusage/discussions)
 
-[**linux.do**](https://linux.do/) — Thanks to the linux.do community for their support and inspiration during the development of this project.
+[**linux.do**](https://linux.do/) - thanks to the linux.do community for support and inspiration during the development of this project.
 
 ## Star History
 
 <a href="https://www.star-history.com/?repos=juliantanx%2Faiusage&type=date&logscale=&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&theme=dark&legend=top-left&t=20260603" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260603" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260603" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&theme=dark&logscale&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&logscale&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&logscale&legend=top-left" />
  </picture>
 </a>
 
-## Contributing
-
-Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get started.
-
 ## License
 
 [MIT](./LICENSE)