agents-deck

Live canvas for Claude Code and OpenAI Codex agents. Watch parallel subagents fork, call tools, and finish — all on one calm graph.

Quick start

npx agents-deck

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.

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:

SessionStart · UserPromptSubmit · PreToolUse · PostToolUse · PostToolUseFailure
SubagentStart · SubagentStop · Stop · SessionEnd · Notification

Each hook fires the bundled hook.js, which POSTs the event JSON to the running server.

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.

Options

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

Uninstall

npx agents-deck --uninstall

Removes all hook entries injected by agents-deck from ~/.claude/settings.json (and ~/.codex/hooks.json if present).

Legacy name

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.

# both work identically
npx agents-deck
npx agent-dag

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)

License

MIT © Bargan Constantin