@scrylog/cli 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # scrylog
 
-`scrylog` is a Bun-based terminal dashboard and daemon for monitoring AI coding sessions in `tmux` and as standalone processes.
+`scrylog` is a Bun-based terminal dashboard and daemon for monitoring AI coding sessions in `tmux`, herdr, and as standalone processes.
 
 It ships four commands:
 
@@ -14,12 +14,14 @@ It ships four commands:
 ## Features
 
 - `tmux` monitoring for OpenCode, Codex, Copilot, and shell panes
+- herdr default-session monitoring through its structured agent and pane API
 - OpenCode integration in `hooks` or `sse` mode
 - Claude transcript collection
 - Codex transcript collection and hook-based state tracking
 - Local daemon with Unix socket IPC on macOS and Linux, TCP fallback on Windows
 - Optional TCP REST API exposure (enabled by default on Windows)
 - Optional MCP HTTP exposure with bearer token support
+- Responsive OpenTUI dashboard with Sessions and provider-usage views
 - User-service installation on macOS and Linux
 - Interactive setup wizard and diagnostics
 
@@ -27,6 +29,7 @@ It ships four commands:
 
 - [Bun](https://bun.sh) `>= 1.3.0`
 - `tmux` if you want `tmux` monitoring
+- [herdr](https://herdr.dev) if you want herdr monitoring; absence is handled automatically
 - OpenCode if you want OpenCode monitoring
 - `ps` on Unix or `wmic` on Windows for process auto-discovery
 
@@ -38,6 +41,35 @@ It ships four commands:
 | Tier 2 | Linux / WSL 2 | Compatible | Claude OAuth via `~/.claude/.credentials.json`, Chrome/Chromium cookies, systemd service when available |
 | Tier 3 | Windows (native) | Experimental / not recommended | TCP IPC, `wmic` process scan, degraded service status. Chrome cookie decryption not available (DPAPI not implemented). Primary use is ad-hoc debugging, not daily monitoring. |
 
+## Terminal Icon Rendering
+
+The Usage view renders provider icons with one of these values for `tui.providerIcons`:
+
+| Mode | Behavior |
+| --- | --- |
+| `blocks` (default) | Bundled pixel-art PNGs rendered with Unicode half-blocks on the Usage cards. Works in any terminal, including multiplexers. |
+| `graphics` | Full artwork. Probes the terminal (`XTVERSION`, kitty graphics query, Sixel support) and falls back to `blocks` when nothing is confirmed. |
+| `kitty` / `sixel` | Force a specific image protocol even when detection does not confirm it (useful for terminals whose detection response is ambiguous). |
+| `text` | Two-letter provider monogram on Usage cards. Never uses images. |
+
+In the sessions list the Tool column also depends on the mode: image modes render 2x1-cell mini icons, `blocks` shows the colored brand monogram (`CL`, `CX`, `OC`, ...) plus child-session badges, and `text` keeps the full tool name. Press `?` in the dashboard to see a legend mapping each icon or monogram to its tool name (legend shown only when an image mode is active).
+
+Compatibility of `graphics` by environment:
+
+| Environment | Works | Detail |
+| --- | --- | --- |
+| Ghostty | Yes | Kitty graphics protocol (`TERM=xterm-ghostty`) |
+| Kitty | Yes | Kitty graphics protocol (reference implementation) |
+| WezTerm | Yes | Kitty graphics and Sixel |
+| iTerm2 | Yes | Inline images and Sixel |
+| Konsole, Foot | Yes | Sixel, requires pixel-resolution detection to confirm |
+| Direct SSH (no multiplexer) | Yes | Inherits the local terminal's protocol support |
+| tmux / herdr | Forced `blocks` | The multiplexer sits between the client and the terminal; passthrough is not reliable, so rendering degrades to `blocks` |
+| Alacritty, Terminal.app, GNOME Terminal | No | No image protocol; falls back to `blocks` |
+| Windows native (Tier 3) | No | Sixel support is partial/experimental; falls back to `blocks` |
+
+Run `scrylog doctor` for a "Terminal graphics" section with detected capabilities and the recommended value for the current terminal.
+
 ## WSL 2 Notes
 
 - The daemon runs as a Linux process and uses the same paths as native Linux.
@@ -130,8 +162,11 @@ For most users on macOS or Linux:
 ```bash
 scrylog
 scrylog --config ~/.config/scrylog/config.json
+scrylog --include-unknown
 ```
 
+By default, sessions whose tool could not be identified (`tool: "unknown"`) are hidden from the dashboard and API. Launch with `--include-unknown` to request them from the daemon for the current run.
+
 Keyboard shortcuts:
 
 | Key | Action |
@@ -139,7 +174,7 @@ Keyboard shortcuts:
 | `↑` / `k` | Move selection up |
 | `↓` / `j` | Move selection down |
 | `Enter` | Open session detail |
-| `t` | Attach to selected `tmux` session |
+| `t` | Attach to selected `tmux` or herdr session |
 | `/` | Search |
 | `f` | Cycle filters |
 | `a` | Show actionable sessions only |
@@ -299,7 +334,8 @@ Example config:
     "refreshMs": 5000,
     "showStandalone": true,
     "usePushUpdates": true,
-    "standaloneMaxAgeHours": 6
+    "standaloneMaxAgeHours": 6,
+    "providerIcons": "blocks"
   },
   "mcp": {
     "stdioEnabled": true,
@@ -336,7 +372,10 @@ Notes:
 - `daemon.commandTimeoutMs` bounds daemon-owned commands such as `ps`, `tmux`, `git`, `lsof`, and `pgrep`.
 - `daemon.networkTimeoutMs` bounds daemon-owned usage/integration network requests.
 - `usage.enabled: false` disables periodic Claude/OpenCode usage probes without disabling session monitoring.
+- In the dashboard, use `Tab`, `u`, or `s` to switch between Sessions and Usage. Every usage window uses the complete card width. When provider cards exceed the terminal height, scroll with `↑`/`↓`, `j`/`k`, Page Up/Page Down, or the mouse wheel. `tui.providerIcons` accepts `blocks` (portable pixel-art PNGs, the default), `graphics` (official artwork with automatic kitty/Sixel negotiation), `kitty` or `sixel` (force a specific image protocol), or `text` (two-letter monogram); all assets are bundled for offline rendering. See [Terminal icon rendering](#terminal-icon-rendering) for environment compatibility.
 - `retention` limits in-memory state. Active `working` and `waiting-input` sessions are preserved even when old.
+- `retention` applies only to standalone sessions: tmux and herdr panes are never pruned by age or count, and `tool: "unknown"` sessions do not consume `retention.maxSessions` capacity (unknown standalone sessions are still pruned by age).
+- Native agent collectors remain authoritative for state and summaries, but matching sessions retain `source: "herdr"` and herdr attach metadata while their pane remains in a successful herdr snapshot. Tmux takes precedence for nested sessions.
 - The daemon log file is always JSONL and rotates by size: `scrylogd.log`, `scrylogd.1.log`, `scrylogd.2.log` by default.
 - The current CLI preserves an existing legacy config path when updating config, so older `~/.scrylog.json` users are not forced onto a new file immediately.
 
@@ -346,7 +385,7 @@ Notes:
 
 | Setting | Default | Effect |
 | --- | ---: | --- |
-| `retention.maxSessions` | `500` | Prunes oldest inactive sessions above this count |
+| `retention.maxSessions` | `500` | Prunes oldest inactive identified standalone sessions above this count (tmux/herdr/unknown rows never count) |
 | `retention.standaloneMaxAgeHours` | `168` | Prunes inactive standalone sessions older than 7 days |
 | `retention.cacheMaxEntries` | `1000` | Bounds internal path/project caches |
 | `retention.transcriptMaxBytes` | `10485760` | Parses only a bounded tail for very large Claude transcripts |
@@ -567,8 +606,8 @@ Endpoints:
 | Method | Path | Returns |
 | --- | --- | --- |
 | `GET` | `/api/health` | daemon health, timestamps, collector status |
-| `GET` | `/api/status` | visible counts, collector status, generated timestamp |
-| `GET` | `/api/sessions` | visible session tree plus counts |
+| `GET` | `/api/status` | visible counts, collector status, generated timestamp (`?includeUnknown=true` opts in) |
+| `GET` | `/api/sessions` | visible session tree plus counts (`?includeUnknown=true` opts in; unknown-tool rows hidden by default) |
 | `GET` | `/api/sessions/:id` | full session detail |
 | `GET` | `/api/sessions/:id/children` | visible child sessions |
 | `GET` | `/api/sessions/:id/messages` | recent messages when available |
@@ -834,7 +873,7 @@ Publish-readiness checks:
 bun run release:check
 ```
 
-Public packages are versioned with Changesets and validated through Turborepo. The release workflow creates a version PR on `main`; merging that PR publishes `@scrylog/cli` and `@scrylog/opencode-plugin` to npm.
+Public packages are versioned with Changesets and validated through Turborepo. Manually running the Release workflow in `version` mode creates a version PR on `main`; merging that PR publishes `@scrylog/cli` and `@scrylog/opencode-plugin` to npm.
 
 ## OpenSpec