@juliantanx/aiusage 1.3.0 → 1.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juliantanx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,42 +1,58 @@
-# aiusage
+# aiusage — AI Coding Assistant Usage Tracker
 
-Track AI coding assistant usage, token consumption, cost, and tool calls in one place across Claude Code, Codex, OpenClaw, OpenCode, Hermes, and Qoder.
+**Open-source CLI and dashboard to track token usage, cost, and sessions across Claude Code, Codex, OpenCode, Hermes, Qoder, and more.** Local-first, privacy-respecting, with an optional web dashboard and multi-machine sync.
 
-English | [中文](https://github.com/juliantanx/aiusage/blob/main/README_zh.md)
+[![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)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
 
-## Why aiusage
+**aiusage** gives you one local-first place to understand how your AI coding tools are being used: tokens, cost, model mix, tool activity, projects, sessions, and multi-machine sync when you need it. Supports Claude Code, Codex, OpenClaw, OpenCode, Hermes, and Qoder.
 
-- Aggregate local session logs from multiple AI coding assistants into one view.
-- Analyze token usage, cost, model mix, and tool call activity.
-- Explore the data through a local dashboard with overview ranges from Today to All Time.
-- Sync usage data across multiple machines with GitHub, S3, or R2.
-- Keep everything local-first, with optional cloud sync when you need shared visibility.
+English | [中文](https://github.com/juliantanx/aiusage/blob/main/README_zh.md)
 
 ## Quick Start
 
 **Prerequisites:** Node.js 18 or later
 
 ```bash
-# Install
 npm install -g @juliantanx/aiusage
-
-# Parse local session logs
 aiusage parse
-
-# Start the dashboard
 aiusage serve
-# Open http://localhost:3847
 ```
 
-Day-to-day usage is usually just:
+Open `http://localhost:3847` to explore the dashboard.
 
-```bash
-aiusage parse
-aiusage serve
-```
+If aiusage is useful, consider starring the repo to help more developers discover it.
 
 `aiusage` does not run a built-in background parser. If you want automatic imports, schedule `aiusage parse` with cron or Task Scheduler.
 
+### Running in Background (PM2)
+
+`aiusage serve` runs in the foreground and stops when you close the terminal. To keep it running in the background on **Windows, macOS, and Linux**, use [PM2](https://pm2.keymetrics.io/):
+
+```bash
+# Install PM2 (one-time)
+npm install -g pm2 pm2-startup
+
+# Start aiusage serve as a background service
+pm2 start aiusage -- serve
+
+# Start the system tray widget as a background service (optional)
+pm2 start aiusage-widget -- --foreground
+
+# Set auto-start on boot (Windows / macOS / Linux)
+pm2 save
+pm2-startup install
+
+# Common commands
+pm2 list            # View running status
+pm2 logs            # View logs
+pm2 stop all        # Stop all services
+pm2 restart all     # Restart all services
+pm2 delete all      # Remove all services
+```
+
 <details>
 <summary>Build from source</summary>
 
@@ -65,6 +81,39 @@ pnpm rebuild:sqlite
 
 </details>
 
+## Why aiusage
+
+AI coding assistant usage is scattered by default: different tools, different local logs, different machines, and no shared view of tokens or cost.
+
+aiusage brings that data into one local-first dashboard so you can:
+
+- Track token usage, cost, model mix, and tool-call activity in one place.
+- Aggregate usage across Claude Code, Codex, OpenClaw, OpenCode, Hermes, and Qoder.
+- Understand usage over time through overview, token, cost, model, session, and project views.
+- Sync across multiple machines with GitHub, S3, or R2 when shared visibility matters.
+- Keep your data local by default, with optional sync only when you choose it.
+
+## Who is this for?
+
+aiusage is built for:
+
+- Developers using Claude Code, Codex, or other AI coding assistants every day.
+- People who want visibility into token usage and spend over time.
+- Multi-tool users who want one dashboard instead of multiple disconnected logs.
+- Multi-machine workflows that need optional aggregation and sync.
+
+## Supported tools
+
+aiusage currently supports:
+
+- Claude Code
+- Codex
+- OpenClaw
+- OpenCode
+- Hermes
+- Qoder
+- Cursor
+
 ## Screenshots
 
 ![Homepage dashboard](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@0ae8299/docs/assets/readme/home.png)
@@ -73,6 +122,16 @@ pnpm rebuild:sqlite
 
 ![Token usage page](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@0ae8299/docs/assets/readme/token.png)
 
+## Common use cases
+
+Use aiusage to:
+
+- Track token and cost trends across AI coding assistants.
+- Compare model usage and activity over time.
+- Inspect tool-call volume and session-level behavior.
+- Aggregate usage across multiple machines into one view.
+- Run a local or Docker-hosted dashboard for ongoing visibility.
+
 ## CLI Reference
 
 ### `aiusage` (default)
@@ -85,7 +144,7 @@ Import newly appended local session data from discovered source paths.
 
 | Option | Description |
 |--------|-------------|
-| `--tool <tool>` | Only parse a specific tool: `claude-code`, `codex`, `openclaw`, `opencode`, `hermes`, `qoder` |
+| `--tool <tool>` | Only parse a specific tool: `claude-code`, `codex`, `openclaw`, `opencode`, `hermes`, `qoder`, `cursor` |
 | `--progress` | Show real-time progress bar on stderr (TTY only, silent in pipes/CI) |
 
 ```bash
@@ -114,7 +173,7 @@ Print a usage summary in the terminal.
 | Option | Description |
 |--------|-------------|
 | `--device <id>` | Filter by device instance ID |
-| `--tool <tool>` | Filter by tool type |
+| `--tool <tool>` | Filter by tool type (`claude-code`, `codex`, `openclaw`, `opencode`, `hermes`, `qoder`, `cursor`) |
 
 ```bash
 aiusage summary                        # All-time summary
@@ -452,6 +511,7 @@ docker build -t aiusage .
 | Hermes | `~/.hermes/state.db` | `~/.hermes/state.db` | `%USERPROFILE%\.hermes\state.db` |
 | Qoder (sessions) | `~/.qoder/logs/sessions/` | `~/.qoder/logs/sessions/` plus WSL-mounted Windows user homes | `%USERPROFILE%\.qoder\logs\sessions\` |
 | Qoder (SQLite) | `~/Library/Application Support/Qoder/SharedClientCache/cache/db/local.db` | `~/.local/share/Qoder/SharedClientCache/cache/db/local.db` | `%LOCALAPPDATA%\Qoder\SharedClientCache\cache\db\local.db` |
+| Cursor | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` | `~/.config/Cursor/User/globalStorage/state.vscdb` | `%APPDATA%\Cursor\User\globalStorage\state.vscdb` |
 
 Discovery behavior:
 
@@ -462,6 +522,7 @@ Discovery behavior:
 - **Hermes** — reads the SQLite database file (`state.db`) directly. Sessions without a recorded end time are still imported if they have token data (e.g. sessions from a force-quit).
 - **Qoder (sessions)** — recursively scans structured session segment logs (`logs/sessions/**/segments/*.jsonl`) and imports `model.response.completed` token events. On WSL, aiusage also checks mounted Windows user homes such as `/mnt/c/Users/<user>`, `/mnt/d/Users/<user>`, and `/mnt/e/Users/<user>` for the same Qoder session-log layout.
 - **Qoder (SQLite)** — reads the `local.db` SQLite database directly (`SharedClientCache/cache/db/local.db`) and imports assistant messages from the `chat_message` table, joined with `chat_record` for model information. This is the primary source on macOS and is tried alongside the sessions directory.
+- **Cursor** — reads Cursor's `state.vscdb` SQLite database directly and imports composer conversations with token usage data.
 
 > On Linux, OpenCode respects `$XDG_DATA_HOME` if set.
 
@@ -480,7 +541,8 @@ If you installed a tool to a non-default location, override the paths in the **S
     "opencode": "/custom/path/opencode.db",
     "hermes": "/custom/path/.hermes/state.db",
     "qoder": "/custom/path/.qoder/logs/sessions",
-    "qoder-db": "/custom/path/local.db"
+    "qoder-db": "/custom/path/local.db",
+    "cursor": "/custom/path/state.vscdb"
   }
 }
 ```
@@ -527,6 +589,28 @@ packages/
   web/      - SvelteKit web dashboard (SPA)
 ```
 
+## FAQ
+
+### Does aiusage upload my data?
+
+No. aiusage is local-first. Your usage data stays on your machine unless you explicitly configure a sync backend.
+
+### Can I use aiusage across multiple machines?
+
+Yes. You can sync usage data through GitHub, S3, or R2 and then view the combined result from any configured machine or Docker deployment.
+
+### Does aiusage run a background parser automatically?
+
+No. By default, you run `aiusage parse` manually. You can automate parsing and syncing with cron, Task Scheduler, or your own scheduler.
+
+### Which assistants are supported?
+
+aiusage currently supports Claude Code, Codex, OpenClaw, OpenCode, Hermes, and Qoder.
+
+### Can I inspect the raw database myself?
+
+Yes. aiusage stores data in a local SQLite database, and the README already documents how to open it in tools like DBeaver, TablePlus, DataGrip, or DB Browser for SQLite.
+
 ## Friends
 
 [**linux.do**](https://linux.do/) — Thanks to the linux.do community for their support and inspiration during the development of this project.
@@ -535,12 +619,16 @@ packages/
 
 <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=20260524" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260524" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260524" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&theme=dark&legend=top-left&t=20260526" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260526" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260526" />
  </picture>
 </a>
 
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get started.
+
 ## License
 
-MIT
+[MIT](./LICENSE)