@scrylog/cli 0.1.4 → 0.3.0

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrylog/cli",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Terminal dashboard for monitoring tmux sessions running AI coding agents",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "bun": ">=1.3.0"
   },
   "bin": {
-    "scrylog": "src/tui/index.ts",
+    "scrylog": "src/cli/index.ts",
     "scrylogd": "src/daemon/index.ts",
     "scrylog-mcp": "src/mcp/index.ts",
     "scrylog-claude-hook": "src/hooks/claude.ts",
@@ -49,29 +49,32 @@
   "scripts": {
     "clean": "rm -rf .turbo && rm -rf dist",
     "clean:node-modules": "rm -rf node_modules",
-    "dev": "bun run src/tui/index.ts",
-    "dev:daemon": "bun run src/daemon/index.ts",
-    "start": "bun run src/tui/index.ts",
+    "dev": "bun run src/cli/index.ts",
+    "dev:daemon": "bun run src/daemon/index.ts --loglevel debug",
+    "start": "bun run src/cli/index.ts",
+    "postinstall": "bun src/postinstall.cjs",
     "check-types": "tsc --noEmit",
     "test": "bun test",
-    "prepublishOnly": "bun run ../../scripts/resolve-catalogs.ts",
-    "postpublish": "bun run ../../scripts/restore-catalogs.ts",
-    "pack:dry-run": "bun run ../../scripts/resolve-catalogs.ts && npm pack --dry-run && bun run ../../scripts/restore-catalogs.ts"
+    "pack:dry-run": "bash ../../scripts/npm-pack.sh \"$PWD\" \"\" --dry-run"
   },
   "dependencies": {
     "@hono/zod-openapi": "^1.3.0",
+    "@joeldmtz/prtl-core": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@opentui/core": "0.5.11",
+    "@opentui/react": "0.5.11",
     "@opencode-ai/sdk": "1.4.10",
     "@scalar/hono-api-reference": "^0.10.11",
     "@scalar/openapi-to-markdown": "^0.5.9",
+    "commander": "15.0.0",
     "hono": "^4.12.15",
-    "neo-blessed": "^0.2.0",
+    "react": "19.2.7",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/blessed": "^0.1.27",
     "@types/bun": "^1.3.14",
     "@types/node": "^24.3.0",
+    "@types/react": "19.2.17",
     "typescript": "5.9.3"
   }
 }

package/src/api/docs/sessions.ts

@@ -1,5 +1,5 @@
 import type { RouteConfig } from "@hono/zod-openapi";
-import { ApiErrorSchema, SessionIdParamSchema } from "../schemas/common";
+import { ApiErrorSchema, IncludeUnknownQuerySchema, SessionIdParamSchema } from "../schemas/common";
 import {
   SessionsResponseSchema,
   SessionDetailResponseSchema,
@@ -16,6 +16,7 @@ export const SessionRoutes = {
     summary: "List sessions",
     description: "Returns the full session tree with counts.",
     security: [{ BearerAuth: [] }],
+    request: { query: IncludeUnknownQuerySchema },
     responses: {
       200: {
         content: { "application/json": { schema: SessionsResponseSchema } },
@@ -29,7 +30,7 @@ export const SessionRoutes = {
     tags: ["Sessions"],
     summary: "List session children",
     security: [{ BearerAuth: [] }],
-    request: { params: SessionIdParamSchema },
+    request: { params: SessionIdParamSchema, query: IncludeUnknownQuerySchema },
     responses: {
       200: {
         content: { "application/json": { schema: SessionChildrenResponseSchema } },

package/src/api/docs/system.ts

@@ -1,5 +1,6 @@
 import { z } from "@hono/zod-openapi";
 import type { RouteConfig } from "@hono/zod-openapi";
+import { IncludeUnknownQuerySchema } from "../schemas/common";
 import { SystemRouteKey } from "./system.keys";
 
 export const SystemRoutes = {
@@ -14,6 +15,7 @@ export const SystemRoutes = {
           "application/json": {
             schema: z.object({
               ok: z.literal(true),
+              version: z.string(),
               startedAt: z.number(),
               refreshedAt: z.number(),
               collectors: z.record(z.string(), z.unknown()),
@@ -30,6 +32,7 @@ export const SystemRoutes = {
     tags: ["System"],
     summary: "Session counts and collector status",
     security: [{ BearerAuth: [] }],
+    request: { query: IncludeUnknownQuerySchema },
     responses: {
       200: {
         content: {

package/src/api/docs/usage.ts

@@ -8,7 +8,7 @@ export const UsageRoutes = {
     method: "get",
     path: "/usage",
     tags: ["Usage"],
-    summary: "Get subscription usage limits",
+    summary: "Get subscription usage and extra-use credits",
     security: [{ BearerAuth: [] }],
     responses: {
       200: {
@@ -17,7 +17,7 @@ export const UsageRoutes = {
             schema: UsageResponseSchema,
           },
         },
-        description: "Current usage data for all configured providers",
+        description: "Current limits, extra-usage spend, and balances for configured providers",
       },
     },
   },

package/src/api/routes/sessions.ts

@@ -10,18 +10,22 @@ export function createSessionsRouter(store: DaemonStore, config: ScrylogConfig):
   const router = new OpenAPIHono();
 
   router.openapi(defineRoute(SessionRouteKey.LIST_SESSIONS), (c) => {
-    const view = buildSessionView(store.getSessions(), config);
+    const { includeUnknown } = c.req.valid("query");
+    const view = buildSessionView(store.getSessions(), config, Date.now(), { includeUnknown: includeUnknown === "true" });
     return c.json({ sessions: view.sessions, counts: view.counts, generatedAt: store.getState().refreshedAt }, 200);
   });
 
   // Must be registered before /:id to avoid the wildcard swallowing the path
   router.openapi(defineRoute(SessionRouteKey.SESSION_CHILDREN), (c) => {
     const { id } = c.req.valid("param");
+    const { includeUnknown } = c.req.valid("query");
     const parent = store.getSession(id);
     if (!parent) {
       throw new NotFoundError("Session", id);
     }
-    const children = buildSessionView(store.getSessions(), config).sessions.find((s) => s.id === id)?.children ?? [];
+    const children = buildSessionView(store.getSessions(), config, Date.now(), {
+      includeUnknown: includeUnknown === "true",
+    }).sessions.find((s) => s.id === id)?.children ?? [];
     return c.json({ sessionId: id, children }, 200);
   });
 

package/src/api/routes/system.ts

@@ -6,6 +6,7 @@ import type { Logger } from "../../shared/logger";
 import { buildSessionView } from "../../shared/session-view";
 import { SystemRouteKey } from "../docs/system.keys";
 import { defineRoute } from "../lib/route";
+import { getInstalledVersion } from "../../shared/version";
 
 export function createSystemRouter(store: DaemonStore, config: ScrylogConfig, logger: Logger): OpenAPIHono {
   const router = new OpenAPIHono();
@@ -14,6 +15,7 @@ export function createSystemRouter(store: DaemonStore, config: ScrylogConfig, lo
     const state = store.getState();
     return c.json({
       ok: true as const,
+      version: getInstalledVersion(),
       startedAt: state.startedAt,
       refreshedAt: state.refreshedAt,
       collectors: state.collectorStatus,
@@ -22,7 +24,8 @@ export function createSystemRouter(store: DaemonStore, config: ScrylogConfig, lo
 
   router.openapi(defineRoute(SystemRouteKey.STATUS), (c) => {
     const state = store.getState();
-    const view = buildSessionView(state.sessions, config);
+    const { includeUnknown } = c.req.valid("query");
+    const view = buildSessionView(state.sessions, config, Date.now(), { includeUnknown: includeUnknown === "true" });
     return c.json({
       counts: view.counts,
       collectorStatus: state.collectorStatus,

package/src/api/routes/webhooks/claude.ts

@@ -7,6 +7,7 @@ import { isMetadataOnlyEvent } from "../../services/claude-session";
 import { ValidationError } from "../../lib/errors";
 import { WebhookRouteKey } from "../../docs/webhooks.keys";
 import { defineRoute } from "../../lib/route";
+import { isKnownClaudeProbePath } from "../../../shared/session-exclusions";
 
 export function createClaudeWebhookRouter(store: DaemonStore, logger: Logger, gitCollector?: GitCollector): OpenAPIHono {
   const router = new OpenAPIHono();
@@ -44,29 +45,16 @@ export function createClaudeWebhookRouter(store: DaemonStore, logger: Logger, gi
     }
 
     const storeId = `claude:${sessionId}`;
-    if (eventType === "SessionEnd") {
+    if (isKnownClaudeProbePath(currentPath) || isKnownClaudeProbePath(transcriptPath)) {
       store.markLocalCommand(sessionId);
-      const existing = store.getSession(storeId);
-      if (existing) {
-        store.upsertSession({
-          ...existing,
-          state: "idle",
-          hasAttention: false,
-          summary: summary ?? existing.summary ?? "Claude session ended",
-          lastActivity: lastActivity ?? Date.now(),
-          detectionSource: "claude-hook",
-          claude: {
-            sessionId,
-            transcriptPath: transcriptPath ?? existing.claude?.transcriptPath ?? "",
-            ...(eventType !== undefined ? { hookEventType: eventType } : {}),
-            ...(eventTime !== undefined ? { hookEventTime: eventTime } : {}),
-            ...(hookSeq !== undefined ? { hookSeq } : {}),
-            ...(endReason !== undefined ? { endReason } : {}),
-            ...(errorType !== undefined ? { errorType } : {}),
-          },
-        });
-      }
+      store.removeSession(storeId);
+      logger.debug("webhook", "claude probe excluded", { event: "session.excluded", tool: "claude", sessionId });
+      return c.json({ ok: true as const, skipped: "claude-probe" }, 200);
+    }
 
+    if (eventType === "SessionEnd") {
+      store.markLocalCommand(sessionId);
+      store.removeSession(storeId);
       logger.info("webhook", "claude session ended", { event: "session.ended", tool: "claude", sessionId, reason: endReason });
       return c.json({ ok: true as const }, 200);
     }

package/src/api/routes/webhooks/opencode.ts

@@ -1,6 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { ScrylogConfig } from "../../../shared/config";
 import type { DaemonStore } from "../../../daemon/store";
+import type { GitCollector } from "../../../daemon/collectors/git";
 import type { Logger } from "../../../shared/logger";
 import type { SessionModel } from "../../../shared/types";
 import type { OpencodeWebhookPayload } from "../../models/opencode";
@@ -8,7 +9,7 @@ import { mapHookState, extractSessionParentId } from "../../services/opencode-se
 import { WebhookRouteKey } from "../../docs/webhooks.keys";
 import { defineRoute } from "../../lib/route";
 
-export function createOpencodeWebhookRouter(store: DaemonStore, config: ScrylogConfig, logger: Logger): OpenAPIHono {
+export function createOpencodeWebhookRouter(store: DaemonStore, config: ScrylogConfig, logger: Logger, gitCollector?: GitCollector): OpenAPIHono {
   const router = new OpenAPIHono();
 
   router.openapi(defineRoute(WebhookRouteKey.WEBHOOK_OPENCODE), async (c) => {
@@ -46,6 +47,7 @@ export function createOpencodeWebhookRouter(store: DaemonStore, config: ScrylogC
 
       const title = payload.info?.title ?? payload.title ?? existing?.summary ?? "OpenCode session";
       const directory = payload.info?.directory ?? payload.directory ?? existing?.currentPath;
+      const resolvedProject = directory && gitCollector ? gitCollector.resolve(directory) : undefined;
       const parentSessionId = extractSessionParentId(event, payload, existing);
       const timeUpdated = payload.info?.time?.updated ?? Date.now();
 
@@ -66,8 +68,10 @@ export function createOpencodeWebhookRouter(store: DaemonStore, config: ScrylogC
           hasAttention,
           summary: title,
           currentPath: directory ?? existing.currentPath,
+          project: resolvedProject ?? existing.project,
           parentSessionId,
           lastActivity: stateChanged ? Date.now() : Math.max(existing.lastActivity, timeUpdated),
+          detectionSource: "opencode-hook",
           opencode: {
             ...existing.opencode,
             sessionId: rawId,
@@ -88,6 +92,7 @@ export function createOpencodeWebhookRouter(store: DaemonStore, config: ScrylogC
           detectionSource: "opencode-hook",
           hasAttention,
           currentPath: directory,
+          project: resolvedProject,
           parentSessionId,
           opencode: {
             sessionId: rawId,

package/src/api/routes.ts

@@ -51,7 +51,7 @@ export function createApiApp(
   app.route("/api", createSystemRouter(store, config, logger));
   app.route("/api", createSessionsRouter(store, config));
   app.route("/api", createUsageRouter(store));
-  app.route("/api/webhook", createOpencodeWebhookRouter(store, config, logger));
+  app.route("/api/webhook", createOpencodeWebhookRouter(store, config, logger, gitCollector));
   app.route("/api/webhook", createClaudeWebhookRouter(store, logger, gitCollector));
   app.route("/api/webhook", createCodexWebhookRouter(store, logger, gitCollector));
 

package/src/api/schemas/common.ts

@@ -19,3 +19,11 @@ export const SessionIdParamSchema = z.object({
     .regex(/^[a-zA-Z0-9:_\-.]+$/, "Invalid session ID")
     .openapi({ param: { name: "id", in: "path" }, example: "claude:abc-123" }),
 });
+
+export const IncludeUnknownQuerySchema = z.object({
+  includeUnknown: z.enum(["true", "false"]).optional().openapi({
+    param: { name: "includeUnknown", in: "query" },
+    example: "true",
+    description: "Include sessions whose tool could not be identified",
+  }),
+});

package/src/api/schemas/sessions.ts

@@ -17,11 +17,23 @@ const TmuxInfoSchema = z.object({
   session: z.string(),
   window: z.string(),
   pane: z.string(),
+  windowName: z.string().optional(),
+});
+
+const HerdrInfoSchema = z.object({
+  paneId: z.string(),
+  terminalId: z.string().optional(),
+  workspaceId: z.string().optional(),
+  workspace: z.string().optional(),
+  tabId: z.string().optional(),
+  tab: z.string().optional(),
+  name: z.string().optional(),
+  agent: z.string().optional(),
 });
 
 export const SessionListItemSchema = z.object({
   id: z.string(),
-  source: z.enum(["tmux", "standalone"]),
+  source: z.enum(["tmux", "herdr", "standalone"]),
   tool: SessionToolSchema,
   state: SessionStateSchema,
   summary: z.string(),
@@ -30,8 +42,10 @@ export const SessionListItemSchema = z.object({
   hasAttention: z.boolean().optional(),
   detectionSource: z.string().optional(),
   parentSessionId: z.string().optional(),
+  displayName: z.string().optional(),
   project: ProjectInfoSchema.optional(),
   tmux: TmuxInfoSchema.optional(),
+  herdr: HerdrInfoSchema.optional(),
   currentPath: z.string().optional(),
   activeTool: z.string().optional(),
   childCount: z.number().optional(),

package/src/api/schemas/usage.ts

@@ -16,6 +16,7 @@ export const ProviderCostSnapshotSchema = z.object({
   limit: z.number(),
   currency: z.string(),
   period: z.string(),
+  balance: z.number().optional(),
   resetsAt: z.string().datetime().nullable().optional(),
   updatedAt: z.string().datetime(),
 });