open-usage 0.9.0 → 0.11.1

package/README.md

@@ -83,6 +83,50 @@ open-usage --help
 
 Every control is also clickable, and the mouse wheel scrolls views taller than the terminal.
 
+### Background daemon
+
+The dashboard only refreshes while it is open.
+If you would rather have current numbers waiting for you, run a daemon: it polls every provider on its own interval and keeps the same cache the dashboard reads, so the app opens on fresh figures instead of fetching them while you watch.
+
+It is off until you start it.
+
+```bash
+open-usage daemon start --interval 5   # minutes; remembered for next time
+open-usage daemon status
+open-usage daemon logs
+open-usage daemon stop
+```
+
+`status` reports the pid, the interval, how long ago the last poll ran, and the last error if one is standing:
+
+```
+running · pid 4821 · every 5m · last poll 42s ago
+log: ~/.config/open-usage/daemon.log
+```
+
+A provider that stops working - an expired credential, a stale cookie - is named rather than counted as a healthy poll, and `last success` stops advancing until it recovers:
+
+```
+running · pid 4821 · every 5m · last poll 42s ago
+last error: cl: claude live limits unavailable (last success 3h ago)
+log: ~/.config/open-usage/daemon.log
+```
+
+The interval accepts 1 to 1440 minutes and is saved in `preferences.json`, so a later `daemon start` with no flag reuses it.
+Starting a second daemon is refused while one is running; `daemon restart --interval 10` is how you change the cadence.
+
+A daemon does not double your API traffic.
+The dashboard treats a reading the daemon has cached as one of its own - at launch, and on every tick after - so a dashboard open beside a running daemon polls nothing the daemon has already fetched.
+That includes the OpenCode dashboard's month history and usage table, which is the expensive part of a Go refresh: the daemon walks it, and the dashboard reads the result.
+
+The log is kept to a megabyte while the daemon runs, with the previous stretch left beside it as `daemon.log.1`.
+
+On Windows `daemon stop` terminates the daemon rather than asking it to finish, because Windows does not deliver the signal the other platforms use.
+Nothing is lost by that: every file the daemon writes is written through a sibling and renamed into place, so an interrupted poll leaves the previous record intact.
+
+The daemon does not survive a reboot on its own.
+Start it from your login items, or supervise `open-usage daemon run --interval 5` with launchd or systemd - that form stays in the foreground and logs to stdout, which is what those want.
+
 ### Staying current
 
 When a newer version has been published, the header says so:
@@ -142,6 +186,7 @@ OpenCode Go does not publish per-account limits, so its percentages are local es
 
 Settings live in the app, on the `5` screen.
 They persist to `~/.config/open-usage/preferences.json` (or `$XDG_CONFIG_HOME/open-usage/`).
+The same directory holds the cached limits the app opens on (`usage-cache.json`), the cached Go history (`go-history.json`, about a megabyte for a busy workspace), the spend record (`spend-history.json`), and, while a daemon runs, its record and log (`daemon.json`, `daemon.log`).
 
 | Variable                     | Purpose                                        |
 | ---------------------------- | ---------------------------------------------- |
@@ -175,6 +220,9 @@ Hand `open-usage` that session cookie and the Go card swaps its local estimate f
 The config file is re-read on every poll, so a cookie pasted there lands within a minute - press `r` to skip the wait.
 The environment variable is read once at launch, so exporting it means restarting the app.
 
+The exact limits are two requests; the month history and the 30-day activity chart behind the Go screen are many more, so they are read every half hour rather than every poll, and `r` leaves them alone while the last reading is under five minutes old.
+The first read walks the whole usage table - a busy workspace is several thousand rows - and the numbers on the overview do not wait for it; after that each read pages back only to the rows already held.
+
 The cookie is optional, and it is also sufficient on its own.
 Without it the Go card still works, on the local estimate; with it, OpenCode need not be installed at all, though a machine with no `opencode.db` has no token history to chart and the card says so.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-usage",
-  "version": "0.9.0",
+  "version": "0.11.1",
   "description": "A terminal dashboard for unified AI plan usage across Claude Code, Codex, and OpenCode Go",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -55,10 +55,10 @@
     "typescript": "^5"
   },
   "optionalDependencies": {
-    "@open-usage/darwin-arm64": "0.9.0",
-    "@open-usage/linux-arm64": "0.9.0",
-    "@open-usage/linux-x64": "0.9.0",
-    "@open-usage/win32-arm64": "0.9.0",
-    "@open-usage/win32-x64": "0.9.0"
+    "@open-usage/darwin-arm64": "0.11.1",
+    "@open-usage/linux-arm64": "0.11.1",
+    "@open-usage/linux-x64": "0.11.1",
+    "@open-usage/win32-arm64": "0.11.1",
+    "@open-usage/win32-x64": "0.11.1"
   }
 }