@juliantanx/aiusage 1.2.1 → 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, and Hermes.
+**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 (tested on v18 LTS and v22 LTS; Node.js 16 and below are not supported)
+**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,28 +81,187 @@ 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@main/docs/assets/readme/home.png)
+![Homepage dashboard](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@0ae8299/docs/assets/readme/home.png)
+
+![Overview page](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@0ae8299/docs/assets/readme/overview.png)
+
+![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)
+
+Print a usage summary to the terminal (same as `aiusage summary`).
+
+### `aiusage parse`
 
-![Overview page](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@main/docs/assets/readme/overview.png)
+Import newly appended local session data from discovered source paths.
 
-![Token usage page](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@main/docs/assets/readme/token.png)
+| Option | Description |
+|--------|-------------|
+| `--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) |
 
-## Common Commands
+```bash
+aiusage parse                        # Parse all tools
+aiusage parse --tool claude-code     # Only parse Claude Code logs
+aiusage parse --progress             # Show progress bar while parsing
+```
+
+### `aiusage serve`
+
+Start the local web dashboard and runtime settings controller.
 
-| Command | Purpose |
-| --- | --- |
-| `aiusage` | Print the same terminal summary as `aiusage summary` |
-| `aiusage parse` | Import newly appended local session data from discovered source paths |
-| `aiusage serve` | Start the local dashboard and runtime settings controller |
-| `aiusage summary` | Print a usage summary in the terminal |
-| `aiusage status` | Show database path, schema version, and record counts |
-| `aiusage sync` | Push and pull data with a configured remote backend |
-| `aiusage export` | Export records as CSV, JSON, or NDJSON |
-| `aiusage clean` | Remove old data |
-| `aiusage recalc` | Recalculate costs with updated pricing |
-| `aiusage init` | Configure a sync backend |
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --port <port>` | Port number | `3847` |
+
+```bash
+aiusage serve             # Start on port 3847
+aiusage serve -p 8080     # Start on port 8080
+```
+
+### `aiusage summary`
+
+Print a usage summary in the terminal.
+
+| Option | Description |
+|--------|-------------|
+| `--device <id>` | Filter by device instance ID |
+| `--tool <tool>` | Filter by tool type (`claude-code`, `codex`, `openclaw`, `opencode`, `hermes`, `qoder`, `cursor`) |
+
+```bash
+aiusage summary                        # All-time summary
+aiusage summary --tool claude-code     # Single tool
+```
+
+### `aiusage status`
+
+Show version, device name, DB path, schema version, table/view counts, record count, DB size, and sync status.
+
+### `aiusage export`
+
+Export records as CSV, JSON, or NDJSON.
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--format <format>` | Output format: `csv`, `json`, `ndjson` | Yes |
+| `-o, --output <file>` | Output file path (default: stdout) | No |
+
+```bash
+aiusage export --format csv                 # CSV to stdout
+aiusage export --format json -o report.json # JSON to file
+aiusage export --format ndjson              # NDJSON to stdout
+```
+
+### `aiusage clean`
+
+Remove old records from the local database based on age.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--before <duration>` | Delete data older than this duration (e.g. `30d`, `180d`) | `180d` |
+
+```bash
+aiusage clean                    # Delete records older than 180 days
+aiusage clean --before 30d       # Delete records older than 30 days
+aiusage clean --before 90d --yes # Delete records older than 90 days, skip confirm
+```
+
+### `aiusage reset`
+
+Delete all parsed records, tool calls, synced data, and the parse watermark. Source log files (`~/.claude`, `~/.codex`, etc.) are **not** affected. Use this to re-import everything from scratch.
+
+| Option | Description |
+|--------|-------------|
+| `--yes` | Skip confirmation prompt (required to execute) |
+
+```bash
+aiusage reset --yes    # Wipe all data, then run `aiusage parse` to re-import
+```
+
+### `aiusage recalc`
+
+Recalculate costs using the latest pricing data.
+
+```bash
+aiusage recalc
+```
+
+### `aiusage init`
+
+Configure a sync backend for multi-machine data aggregation.
+
+| Option | Description |
+|--------|-------------|
+| `--backend <backend>` | Sync backend: `github`, `s3`, `skip` |
+| `--repo <repo>` | GitHub repository (format: `username/repo-name`) |
+| `--token <token>` | GitHub Personal Access Token |
+| `--bucket <bucket>` | S3 bucket name |
+| `--prefix <prefix>` | S3 object prefix (default: `aiusage/`) |
+| `--endpoint <endpoint>` | S3 endpoint URL |
+| `--region <region>` | S3 region (default: `auto`) |
+| `--access-key-id <id>` | S3 access key ID |
+| `--secret-access-key <key>` | S3 secret access key |
+| `--device <alias>` | Device alias |
+
+```bash
+aiusage init --backend github --repo user/aiusage-data --token ghp_xxx
+aiusage init --backend s3 --bucket my-bucket --endpoint https://xxx.r2.cloudflarestorage.com --access-key-id AKIAxxx --secret-access-key xxx
+```
+
+### `aiusage sync`
+
+Push and pull data with the configured remote backend.
+
+```bash
+aiusage sync
+```
 
 ## Web Dashboard
 
@@ -132,7 +307,7 @@ For single-machine usage, Quick Start is enough.
 
 ### Multi-Machine Sync
 
-Use this to aggregate token usage from multiple machines into one dashboard. Works with Claude Code, Codex, OpenClaw, OpenCode, and Hermes.
+Use this to aggregate token usage from multiple machines into one dashboard. Works with Claude Code, Codex, OpenClaw, OpenCode, Hermes, and Qoder.
 
 **Architecture:**
 
@@ -157,7 +332,7 @@ Machine C ──┘
 
 **Step 2 — Install and configure on each machine**
 
-On every machine that uses Claude Code, Codex, OpenClaw, OpenCode, or Hermes:
+On every machine that uses Claude Code, Codex, OpenClaw, OpenCode, Hermes, or Qoder:
 
 ```bash
 # Install aiusage CLI
@@ -320,7 +495,8 @@ docker build -t aiusage .
 |------|------|
 | Local database | `~/.aiusage/cache.db` |
 | Config | `~/.aiusage/config.json` |
-| State (watermarks, sync) | `~/.aiusage/state.json` |
+| Sync state | `~/.aiusage/state.json` |
+| Parse watermarks | `~/.aiusage/watermark.json` |
 
 ### Default Source Paths
 
@@ -333,6 +509,9 @@ docker build -t aiusage .
 | OpenClaw | `~/.openclaw/agents/*/sessions/` | `~/.openclaw/agents/*/sessions/` | `%USERPROFILE%\.openclaw\agents\*\sessions\` |
 | OpenCode | `~/Library/Application Support/opencode/opencode.db` | `~/.local/share/opencode/opencode.db` | `%APPDATA%\opencode\opencode.db` |
 | 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:
 
@@ -341,9 +520,14 @@ Discovery behavior:
 - **OpenClaw** — scans each agent's `sessions/` directory under `~/.openclaw/agents/*/sessions/` and skips checkpoint files.
 - **OpenCode** — reads the SQLite database file directly instead of `.jsonl` logs.
 - **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.
 
+Qoder Desktop also creates installation files under `Program Files`, UI/cache data under `AppData/Roaming/Qoder` and `AppData/Local/.qoder`, and transcripts under `%USERPROFILE%\.qoder\projects` or `%USERPROFILE%\.qoder\cache`. These are not imported as token records: desktop `Context usage update` log lines are repeated context-window snapshots, and transcripts/conversation-history files do not contain per-request token usage.
+
 ### Custom Source Paths
 
 If you installed a tool to a non-default location, override the paths in the **Settings** page of the web dashboard (`http://localhost:3847/settings` → Sources section), or edit `~/.aiusage/config.json` directly:
@@ -355,12 +539,15 @@ If you installed a tool to a non-default location, override the paths in the **S
     "codex": "/custom/path/.codex/sessions",
     "openclaw": "/custom/sessions-dir",
     "opencode": "/custom/path/opencode.db",
-    "hermes": "/custom/path/.hermes/state.db"
+    "hermes": "/custom/path/.hermes/state.db",
+    "qoder": "/custom/path/.qoder/logs/sessions",
+    "qoder-db": "/custom/path/local.db",
+    "cursor": "/custom/path/state.vscdb"
   }
 }
 ```
 
-Only the paths you specify are overridden; unspecified tools fall back to their defaults.
+Only the paths you specify are overridden; unspecified tools fall back to their defaults. `qoder` points to the session logs directory; `qoder-db` points directly to the `local.db` SQLite file.
 
 ## Database Visualization
 
@@ -402,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.
@@ -410,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=20260522" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260522" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left&t=20260522" />
+   <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)