idletime 0.1.2 → 0.2.0

package/README.md

@@ -14,7 +14,7 @@ Local Bun CLI for Codex activity, token burn, visual 24-hour rhythm charts, and
 
 ## How It Works
 
-`idletime` is read-only. It scans your local Codex session logs under `~/.codex/sessions/YYYY/MM/DD/*.jsonl` and builds reports from those raw events.
+The dashboard and snapshot commands are read-only. They scan your local Codex session logs under `~/.codex/sessions/YYYY/MM/DD/*.jsonl` and build reports from those raw events. The explicit `refresh-bests` command is the maintenance exception: it updates `~/.idletime/` and can fire best-related notifications.
 
 At a high level:
 
@@ -64,7 +64,9 @@ bun run idletime
 
 That shows:
 
+- A gold `BEST` plaque in the header for your top concurrent agents, top 24-hour raw burn, and top agent-sum record
 - A framed trailing-24h dashboard
+- A dedicated `Agents` section that charts concurrent child-task windows over the day
 - A `24h Rhythm` strip for `focus`, `active`, `quiet` or `idle`, and `burn`
 - `Spike Callouts` for the biggest burn hours
 - A lower detail section with activity, tokens, and wake-window stats
@@ -76,11 +78,14 @@ That shows:
 - `idle`: awake idle time, only shown when you pass `--wake`
 - `quiet`: non-active time when no wake window is provided
 - `burn`: practical burn, calculated as `input - cached_input + output`
+- `Agents`: concurrent child-task windows derived from transcript lifecycle records when they exist, with a compatibility fallback for older subagent logs
 
 Additional behavior:
 
 - `last24h`: the default trailing window, clipped to the actual last 24 hours
 - `today`: local midnight to now
+- `live`: global task scoreboard by default, with `waiting on you`, `running`, recent concurrency, and per-project live state
+- `refresh-bests`: explicit full-history personal-record refresh for the `BEST` plaque and best-related notifications
 - `direct`: user-started work in the main CLI or compatible direct session types
 - `subagent`: spawned agent sessions
 - `idle cutoff`: how long activity stays alive after the last event before it counts as quiet or idle
@@ -123,12 +128,54 @@ Open the full hourly table:
 bun run idletime hourly --window 24h --workspace-only /path/to/demo-workspace
 ```
 
+Open the live global scoreboard:
+
+```bash
+bun run idletime live
+```
+
+`live` defaults to all local sessions. Use `--workspace-only` when you want to pin the board to one repo or project path.
+Use `--global` when you want to clear a previously added workspace scope explicitly.
+When stdout is a TTY it repaints in place like a scoreboard. When stdout is not a TTY, it renders one snapshot and exits, which makes it usable in scripts and validation.
+
+Pin the live board to one workspace:
+
+```bash
+bun run idletime live --workspace-only /path/to/demo-workspace
+```
+
+Refresh your `BEST` records explicitly:
+
+```bash
+bun run idletime refresh-bests
+```
+
 Group the summary by model and effort:
 
 ```bash
 bun run idletime last24h --group-by model --group-by effort
 ```
 
+Get machine-readable snapshots:
+
+```bash
+bun run idletime --json
+```
+
+```bash
+bun run idletime today --json
+```
+
+```bash
+bun run idletime hourly --json
+```
+
+```bash
+bun run idletime live --json
+```
+
+`--json` is read-only. It emits one versioned JSON snapshot and exits. On `last24h` and `today`, it does not refresh best metrics or trigger best-related notifications. `--share` is human-only and cannot be combined with `--json`.
+
 ## Share Mode
 
 `--share` keeps the visual story and trims the secondary detail:
@@ -144,6 +191,7 @@ That is the best mode for terminal screenshots.
 
 The top of the dashboard is intentionally visual-first.
 
+- `Agents` plots concurrent child-task windows with real clock labels like `8am`, `12pm`, and `4pm`
 - `24h Rhythm` gives one character per hour bucket across the trailing day
 - `focus` makes it obvious where you were actually engaged
 - `active` shows the broader direct-session footprint
@@ -151,6 +199,17 @@ The top of the dashboard is intentionally visual-first.
 - `burn` highlights token spikes without making you read the table first
 - `Spike Callouts` surfaces the top burn hours immediately
 
+The live board is intentionally narrower:
+
+- `waiting on you`: recent direct sessions whose latest task completed after your last `user_message`, so you likely owe the next reply
+- `running`: active task windows across the selected scope after effort-aware staleness
+- `running at`: per-project counts for currently running work
+- `waiting at`: per-project counts for sessions currently waiting on you
+- `top waiting`: the specific waiting threads, shown as `project • age • thread id`
+- `recent`: short live concurrency strip across the last 15 minutes
+- `this turn`: completed child tasks anchored to the latest still-warm direct `user_message`
+- `today peak`: highest observed concurrent child-task count since local midnight
+
 ## Help
 
 ```bash
@@ -171,6 +230,27 @@ Once published, that also works as:
 idletime --version
 ```
 
+## Record Tracking
+
+`idletime` now keeps a local personal-best ledger under `~/.idletime/`.
+
+- `bests-v1.json`: durable best values for the header plaque
+- `best-events.ndjson`: append-only new-best history
+- `near-best-notifications-v1.json`: opt-in state for “close to best” nudges
+
+By default:
+
+- dashboards read cached `BEST` values when `bests-v1.json` already exists
+- a cold cache renders without the `BEST` plaque instead of bootstrapping best state implicitly
+- genuine new-best events can trigger a local macOS notification during the explicit refresh path
+- near-best nudges are stored but disabled until you opt in by setting `nearBestEnabled` to `true`
+
+When you want to recompute those records, update the ledger, and fire any eligible notifications, run:
+
+```bash
+bun run idletime refresh-bests
+```
+
 ## Validation
 
 ```bash
@@ -191,6 +271,8 @@ That QA pass reads:
 
 It builds the package, packs the current checkout, installs the tarball into an isolated temp `BUN_INSTALL`, seeds synthetic Codex session logs, and runs the shell journeys against the installed `idletime` binary.
 
+Operational note: the default `last24h` and `today` commands now stay on the fast read path. They render from the requested report window plus any cached `BEST` ledger state and do not refresh records implicitly. `refresh-bests` is the only CLI command that performs the full-history best-metrics scan.
+
 ## Release Prep
 
 Build the publishable CLI bundle:

package/assets/idle-time-notification-icon.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="24" y1="20" x2="228" y2="236" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#202611"/>
+      <stop offset="1" stop-color="#12160A"/>
+    </linearGradient>
+    <linearGradient id="glow" x1="44" y1="42" x2="212" y2="220" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#C7BC61"/>
+      <stop offset="1" stop-color="#786B2A"/>
+    </linearGradient>
+    <linearGradient id="top" x1="128" y1="62" x2="128" y2="116" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#F0E6AB"/>
+      <stop offset="1" stop-color="#D7C770"/>
+    </linearGradient>
+    <linearGradient id="left" x1="90" y1="92" x2="118" y2="196" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#D0BC58"/>
+      <stop offset="1" stop-color="#937F34"/>
+    </linearGradient>
+    <linearGradient id="right" x1="166" y1="92" x2="138" y2="198" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#BFA747"/>
+      <stop offset="1" stop-color="#6E5E22"/>
+    </linearGradient>
+  </defs>
+  <rect x="16" y="16" width="224" height="224" rx="44" fill="url(#bg)"/>
+  <rect x="26" y="26" width="204" height="204" rx="34" stroke="url(#glow)" stroke-opacity=".42" stroke-width="4"/>
+  <rect x="42" y="42" width="172" height="22" rx="11" fill="url(#glow)" fill-opacity=".34"/>
+  <path d="M128 58 184 90 128 122 72 90 128 58Z" fill="url(#top)"/>
+  <path d="M72 90 128 122V190L72 158V90Z" fill="url(#left)"/>
+  <path d="M184 90 128 122V190L184 158V90Z" fill="url(#right)"/>
+  <path d="M128 58 184 90 128 122 72 90 128 58Z" stroke="#F5EDBD" stroke-opacity=".74" stroke-width="3"/>
+  <path d="M72 90 128 122M184 90 128 122M128 122V190" stroke="#FFF5C5" stroke-opacity=".42" stroke-width="3"/>
+  <path d="M86 178h84" stroke="#FFF0AB" stroke-opacity=".24" stroke-width="6" stroke-linecap="round"/>
+</svg>