@juliantanx/aiusage 1.2.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # aiusage
 
-Track AI coding assistant usage, token consumption, cost, and tool calls in one place across Claude Code, Codex, OpenClaw, OpenCode, and Hermes.
+Track AI coding assistant usage, token consumption, cost, and tool calls in one place across Claude Code, Codex, OpenClaw, OpenCode, Hermes, and Qoder.
 
 English | [中文](https://github.com/juliantanx/aiusage/blob/main/README_zh.md)
 
@@ -14,7 +14,7 @@ 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
@@ -55,30 +55,154 @@ After pulling updates, rebuild to pick up changes:
 pnpm build
 ```
 
+If you switch Node.js versions locally, recompile the `better-sqlite3` native module for the new version:
+
+```bash
+pnpm rebuild:sqlite
+```
+
+> This is only needed when developing from source. Users who install via `npm install -g` do not need to do this — the module is compiled automatically during installation.
+
 </details>
 
 ## 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)
+
+## CLI Reference
+
+### `aiusage` (default)
+
+Print a usage summary to the terminal (same as `aiusage summary`).
+
+### `aiusage parse`
+
+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` |
+| `--progress` | Show real-time progress bar on stderr (TTY only, silent in pipes/CI) |
+
+```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.
+
+| 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 |
+
+```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`
 
-![Overview page](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@main/docs/assets/readme/overview.png)
+Export records as CSV, JSON, or NDJSON.
 
-![Token usage page](https://cdn.jsdelivr.net/gh/juliantanx/aiusage@main/docs/assets/readme/token.png)
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--format <format>` | Output format: `csv`, `json`, `ndjson` | Yes |
+| `-o, --output <file>` | Output file path (default: stdout) | No |
 
-## Common Commands
+```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
+```
 
-| 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 |
+### `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
 
@@ -124,7 +248,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:**
 
@@ -149,7 +273,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
@@ -312,7 +436,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
 
@@ -325,6 +450,8 @@ 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` |
 
 Discovery behavior:
 
@@ -333,9 +460,13 @@ 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.
 
 > 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:
@@ -347,12 +478,14 @@ 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"
   }
 }
 ```
 
-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,9 +535,9 @@ 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" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=juliantanx/aiusage&type=date&legend=top-left" />
+   <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" />
  </picture>
 </a>