token-rats 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Token Rats contributors
+
+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,23 +1,15 @@
 # token-rats
 
-> Strava for AI token burn — sync your Claude Code + Cursor + Codex usage to your Token Rats leaderboard. **Run once, watches forever.**
+> Strava for AI token burn — sync your Claude Code + Cursor usage to your Token Rats leaderboard.
 
 ## Install
 
 ```bash
 npx token-rats login   # one-time auth
-npx token-rats sync    # uploads usage, then asks to install a background watcher
+npx token-rats sync    # upload your usage
 ```
 
-After your first successful `sync`, the CLI asks:
-
-```
-Install background sync? [Y/n]
-```
-
-Say yes once and you’re done. A native OS service (launchd on macOS, systemd `--user` on Linux) keeps watching your Claude Code, Cursor, and Codex logs and uploads new sessions automatically. No more `sync` runs, no cron jobs to babysit.
-
-For a stable install across reboots, install globally rather than via npx:
+Or install globally:
 
 ```bash
 npm install -g token-rats
@@ -29,11 +21,7 @@ token-rats sync
 | Command | Description |
 |---|---|
 | `token-rats login` | Open your browser to authenticate (device-code flow). Saves a token to `~/.config/token-rats/token`. |
-| `token-rats sync` | Discover Claude Code, Cursor, and Codex logs, parse them, upload counts. On first success, prompts to install the background watcher. |
-| `token-rats watch` | Run the watcher in your terminal (Ctrl-C to stop). Useful for debugging. |
-| `token-rats watch --install` | Install the background watcher (launchd / systemd --user). |
-| `token-rats watch --uninstall` | Remove the background watcher. |
-| `token-rats watch --status` | Show whether the watcher is installed and running. |
+| `token-rats sync` | Discover Claude Code logs and the Cursor cache, parse them, and upload counts to your leaderboard. |
 | `token-rats whoami` | Show the currently signed-in account handle. |
 | `token-rats logout` | Delete your stored credentials. |
 | `token-rats --version` | Print the CLI version. |
@@ -42,42 +30,15 @@ token-rats sync
 ### Sync flags
 
 ```
-token-rats sync [--dry-run] [--verbose] [--no-daemon] [--api-url <url>]
+token-rats sync [--dry-run] [--verbose] [--api-url <url>]
 ```
 
 | Flag | Description |
 |---|---|
 | `--dry-run` | Parse files but do not upload. Prints what would be sent. |
 | `--verbose` | Print which files were discovered and how many records each contains. |
-| `--no-daemon` | Skip the post-sync prompt to install the background watcher. (`TOKEN_RATS_NO_DAEMON=1` does the same globally.) |
 | `--api-url <url>` | Override the API base URL (useful for local dev or staging). |
 
-### Watch flags
-
-```
-token-rats watch [--install | --uninstall | --status]
-token-rats watch [--interval <ms>] [--verbose]
-```
-
-| Flag | Description |
-|---|---|
-| `--install` | Install the background watcher. Idempotent. |
-| `--uninstall` | Remove the background watcher. |
-| `--status` | Print install + running state and the log path. |
-| `--interval <ms>` | Debounce window for file-change uploads. Default: 2000. |
-| `--verbose` | Print per-file change events and uploads. |
-
-## Background watcher details
-
-- **Sources watched:** Claude Code (`~/.claude/projects/**/*.jsonl`), Codex rollouts, and Cursor's per-workspace SQLite cache.
-- **Cursor polling:** every 90s, `stat()`-first, capped to the 10 most-recently-modified workspaces. Idle CPU is near zero.
-- **macOS:** `~/Library/LaunchAgents/com.tokenrats.watch.plist`. Auto-restarts on crash and runs at login.
-- **Linux:** `~/.config/systemd/user/token-rats-watch.service`. Auto-restarts on crash. For the watcher to survive logout, run once: `sudo loginctl enable-linger $USER`. Without it, the watcher resumes at your next login.
-- **Windows:** not yet supported. Use `token-rats sync` for now.
-- **Logs:** `~/.config/token-rats/logs/watch.log` (or `~/Library/Application Support/token-rats/logs/` on macOS).
-- **Auth expiry:** if your session expires, the watcher backs off 10 minutes instead of crashing. Run `token-rats login` to recover; the watcher picks up on its own.
-- **Upgrades:** when you `npm update -g token-rats`, just run `token-rats sync` once — the daemon re-installs against the new binary path automatically.
-
 ## What data is collected
 
 **Token Rats reads usage counts only.** It reads:
@@ -99,16 +60,12 @@ Reads `~/.claude/projects/**/*.jsonl` (macOS/Linux) or `%USERPROFILE%\.claude\pr
 
 ### Cursor
 
-Reads per-workspace SQLite caches under `Cursor/User/workspaceStorage/*/state.vscdb`:
-- **macOS:** `~/Library/Application Support/`
-- **Linux:** `~/.config/`
-- **Windows:** `%APPDATA%\`
-
-Cursor doesn't store token counts on disk for most sessions, so per-request tokens are estimated from request type. Numbers are comparable across Token Rats users but won't match cursor.com to the token. If the Cursor database isn't found or can't be read, the CLI skips it silently.
+Reads the Cursor sqlite cache:
+- **macOS:** `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`
+- **Linux:** `~/.config/Cursor/User/globalStorage/state.vscdb`
+- **Windows:** `%APPDATA%\Cursor\User\globalStorage\state.vscdb`
 
-### Codex
-
-Reads rollout JSONL files under `<codex-home>/sessions/YYYY/MM/DD/`. `<codex-home>` defaults to `~/.codex`; Snap and Flatpak distros are also probed.
+If the Cursor database is not found or cannot be read, the CLI skips it silently and continues with Claude Code data.
 
 ## Auth
 
@@ -128,4 +85,20 @@ Authentication uses a device-code flow:
 
 Token Rats is open source. The CLI source is in [`packages/cli/`](.) and the parsers are in [`packages/parsers/`](../parsers/). You can inspect exactly what is read from your disk and what is sent to the server.
 
-**Privacy posture:** Token Rats reads usage counts only — never prompts or completions. The parser source is in `packages/parsers/`. We literally can't read what you typed. The background watcher follows the same rule — it's the same parser code on a timer.
+**Privacy posture:** Token Rats reads usage counts only — never prompts or completions. The parser source is in `packages/parsers/`. We literally can't read what you typed.
+
+
+## Automatic tracking
+
+`token-rats login` installs the background tracker. It reads Claude Code,
+Codex, and Cursor records on startup, then checks for changes every 30 seconds.
+Failed uploads are retried. Use `login --no-daemon` to use manual sync only.
+Use `daemon-status` and `uninstall-daemon` to manage automatic tracking.
+After an upgrade, run `install-daemon` to copy the new runtime into place.
+Custom `--api-url` settings are passed to the installed tracker.
+
+Open `/app/compare` on your Token Rats server to enter a subscription amount
+for a month. Cursor counts are estimates. API estimates are not provider bills.
+See the [counting method](https://github.com/hsalberti/token-rats/blob/main/docs/counting.md).
+
+The CLI and its documentation are MIT licensed. The npm package includes LICENSE.