agent-dag 1.17.0 → 1.19.0

package/README.md

@@ -1,59 +1,99 @@
-# agent-dag
+# agents-deck
 
-Live DAG of Claude Code **and OpenAI Codex** agents. Watch parallel subagents fork, call tools, and return — all on one calm canvas.
+[![npm](https://img.shields.io/npm/v/agents-deck?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/agents-deck)
+[![npm downloads](https://img.shields.io/npm/dm/agents-deck?color=blue)](https://www.npmjs.com/package/agents-deck)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org)
 
-## Run
+Live canvas for **Claude Code** and **OpenAI Codex** agents. Watch parallel subagents fork, call tools, and finish — all on one calm graph.
+
+![agents-deck — live agent DAG](image_2026-06-16_08-58-42.png)
+
+## Quick start
 
 ```bash
-npx agent-dag
+npx agents-deck
 ```
 
-Opens http://127.0.0.1:4317 (or a random port in 4318–4400 if 4317 is taken). Start a Claude Code **or Codex** session in any directory and watch the graph fill in. Both providers render side by side on the same canvas; the model chip on each node tells them apart (e.g. `Opus 4.8`, `GPT-5.5`).
+Opens **http://127.0.0.1:4317** and auto-registers the Claude Code hook. Start any Claude Code or Codex session and the graph fills in live.
 
-## Options
+No config. No install step. Ctrl+C to stop.
+
+## Features
+
+- **Live DAG** — nodes are agents, edges are spawns and tool calls; in-flight edges animate, settled edges fade
+- **Dual provider** — Claude Code via hooks, Codex via log-tail; both appear on the same canvas; the model chip (`Opus 4.8`, `GPT-5.5`) tells them apart
+- **Click-to-inspect** — click any node for prompt, tool calls, token usage, and timing
+- **Persistent replay** — events survive restarts; the log at `~/.claude/agent-dag/events.jsonl` replays the last session on open
+- **Workspace filter** — `--scope` limits capture to the current directory; `--workspace <path>` for any subtree
+- **Zero trust step for Codex** — no hook install, no `/hooks` trust prompt; the server tails `~/.codex/sessions/` directly
+
+## How it works
+
+Two capture paths feed one SSE stream → one browser canvas.
+
+**Claude Code** — on first run `agents-deck` injects a hook entry into `~/.claude/settings.json` for every relevant event:
 
 ```
--p, --port <number>      Preferred port (default: 4317; falls back to random 4318–4400)
-    --no-open            Don't open the browser automatically
-    --workspace <path>   Only capture sessions whose cwd is inside <path>
-    --scope              Restrict to the current working directory
-    --all                Capture sessions from all workspaces (machine-wide; default)
-    --codex              Force-enable Codex capture even if ~/.codex/ is missing
-    --no-codex           Skip Codex capture (Claude only)
-    --history <path>     Override events log file (default: ~/.claude/agent-dag/events.jsonl)
-    --no-persist         RAM-only mode, no log file
-    --uninstall          Remove agent-dag hooks from ~/.claude/settings.json
--h, --help               Show help
+SessionStart · UserPromptSubmit · PreToolUse · PostToolUse · PostToolUseFailure
+SubagentStart · SubagentStop · Stop · SessionEnd · Notification
 ```
 
-## Design
+Each hook fires the bundled `hook.js`, which POSTs the event JSON to the running server.
 
-- One canvas. No tabs. No kanban.
-- Node = agent (root session, subagent).
-- Edge = parent → child (spawn) or agent → tool (call).
-- In-flight edges animate; settled edges fade.
-- Click a node for details.
+**OpenAI Codex** — Codex CLI hooks don't fire reliably on Windows (the sandbox refuses to spawn them). Instead, the server tails Codex's rollout files at `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` and reconstructs an equivalent event stream — session start, prompts, tool calls, token usage, model. No hook install, no trust step needed. Set `CODEX_HOME` to override the default path.
 
-## How it works
+## Options
 
-Two providers, two capture paths — both stream to the same server, which pushes events to the browser over SSE.
+```
+agents-deck [options]
+
+  -p, --port <number>      Preferred port  (default: 4317; fallback: random 4318–4400)
+      --no-open            Don't open the browser automatically
+      --workspace <path>   Only capture sessions whose cwd is inside <path>
+      --scope              Restrict to the current working directory
+      --all                Capture every session on this machine  (default)
+      --history <path>     Override the events log file
+                           (default: ~/.claude/agent-dag/events.jsonl)
+      --no-persist         RAM-only mode — don't write or replay the log
+      --codex              Force Codex capture even if ~/.codex/ is missing
+      --no-codex           Skip Codex capture (Claude only)
+      --uninstall          Remove agents-deck hooks from settings files
+  -h, --help               Show this help
+```
 
-**Claude Code** — `agent-dag` registers a hook script in `~/.claude/settings.json` for these events:
+## Uninstall
 
-`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `SubagentStart`, `SubagentStop`, `Stop`, `SessionEnd`, `Notification`.
+```bash
+npx agents-deck --uninstall
+```
 
-The hook forwards the event JSON to the running server.
+Removes all hook entries injected by agents-deck from `~/.claude/settings.json` (and `~/.codex/hooks.json` if present).
 
-**OpenAI Codex** — Codex CLI hooks don't fire reliably on Windows (the sandbox refuses to spawn the hook command), so instead the server tails Codex's session rollout files at `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` and reconstructs the same event stream (session start, prompts, tool calls, token usage, model). No hook install and no `/hooks` trust step is needed — just run a Codex session and it shows up. Honors `CODEX_HOME` if set.
+## Legacy name
 
-## Uninstall
+Formerly **agent-dag**. Both names publish the same package and the `agent-dag` command is a built-in alias — existing installs and scripts keep working.
 
 ```bash
-npx agent-dag --uninstall
+# both work identically
+npx agents-deck
+npx agent-dag
 ```
 
-Removes all hooks from `~/.claude/settings.json`.
+## Design
+
+One canvas. No tabs. No kanban.
+
+- Node = agent (root session or subagent)
+- Edge = parent → child (spawn) or agent → tool (call)
+- In-flight = animated; settled = dimmed
+- Click a node for full details
+
+## Requirements
+
+- Node.js ≥ 18
+- Claude Code CLI or OpenAI Codex CLI (or both)
 
-## Status
+## License
 
-Pre-alpha. Names, ports, and event shapes may change.
+MIT © [Bargan Constantin](https://github.com/BarganConstantin)

package/bin/agent-dag.js

@@ -24,13 +24,13 @@ if (flags.uninstall) {
   const { uninstallHooks, hasCodexInstalled } = await import(pathToFileURL(join(PKG_ROOT, "src/server/installer.mjs")).href);
   const claude = await uninstallHooks({ provider: "claude" });
   console.log(claude.changed
-    ? `agent-dag: hooks removed from ${claude.settingsPath}`
-    : "agent-dag: no Claude hooks to remove");
+    ? `agents-deck: hooks removed from ${claude.settingsPath}`
+    : "agents-deck: no Claude hooks to remove");
   if (hasCodexInstalled()) {
     const codex = await uninstallHooks({ provider: "codex" });
     console.log(codex.changed
-      ? `agent-dag: hooks removed from ${codex.settingsPath}`
-      : "agent-dag: no Codex hooks to remove");
+      ? `agents-deck: hooks removed from ${codex.settingsPath}`
+      : "agents-deck: no Codex hooks to remove");
   }
   process.exit(0);
 }
@@ -59,7 +59,7 @@ const wantCodex = flags.noCodex
 
 const WEB_DIST = join(PKG_ROOT, "dist", "web", "index.html");
 if (!existsSync(WEB_DIST)) {
-  console.error("agent-dag: ui not built. run `npm run build` (or `pnpm build`) first.");
+  console.error("agents-deck: ui not built. run `npm run build` (or `pnpm build`) first.");
   process.exit(1);
 }
 
@@ -88,7 +88,7 @@ async function printBanner() {
 
   // Each entry: [rendered string with ANSI, visible char count, left-border color, right-border color]
   const rows = [
-    { l: `  ${C.bCyan}${C.bold}◉${C.reset}  ${C.white}${C.bold}agent-dag${C.reset}  ${C.dim}v${PKG_VERSION}${C.reset}`, vis: 17 + PKG_VERSION.length, lc: C.blue,    rc: C.blue    },
+    { l: `  ${C.bCyan}${C.bold}◉${C.reset}  ${C.white}${C.bold}agents-deck${C.reset}  ${C.dim}v${PKG_VERSION}${C.reset}`, vis: 19 + PKG_VERSION.length, lc: C.blue,    rc: C.blue    },
     { l: `  ${C.dim}live DAG · Claude Code + Codex${C.reset}`,                                                  vis: 32, lc: C.magenta, rc: C.magenta },
     { l: `  ${C.yellow}watch agents fork  ${C.cyan}→${C.reset}  ${C.green}tools fire${C.reset}`,               vis: 34, lc: C.bMag,    rc: C.bMag    },
   ];
@@ -206,10 +206,10 @@ function parseArgs(args) {
 }
 
 function printHelp() {
-  process.stdout.write(`agent-dag — live DAG of Claude Code + Codex agents
+  process.stdout.write(`agents-deck — live deck of Claude Code + Codex agents
 
 Usage:
-  agent-dag [options]
+  agents-deck [options]
 
 Options:
   -p, --port <number>      Preferred port (default: 4317; falls back to random 4318–4400)
@@ -221,7 +221,7 @@ Options:
       --no-persist         Don't write or replay events log (RAM-only)
       --codex              Force-enable Codex capture even if ~/.codex/ missing
       --no-codex           Skip Codex capture (Claude only)
-      --uninstall          Remove agent-dag Claude hook entries
+      --uninstall          Remove agents-deck Claude hook entries
   -h, --help               Show this help
 `);
 }