npx ccdeck

Why

An agent session is a tree, but a terminal shows it as a scroll. Five subagents working in parallel arrive as one interleaved column of text, and the questions you actually have — what is running right now, what did that subagent do, which one is stuck, what is this costing — are the ones the scroll answers worst.

ccdeck draws the tree instead. It is local and needs no configuration: it registers a hook, listens, and paints. It never steers an agent or edits your code, but it is not read-only either — besides the hook entry and its own event log, it manages the two tools it leans on, and it refreshes the Codex token it reads quota with, rewriting ~/.codex/auth.json the way codex itself does.

Quick start

npx ccdeck          # or: npx agents-deck · npx agent-dag — same deck

Opens http://127.0.0.1:4317 and registers the Claude Code hook on first run. Start any Claude Code or Codex session and the graph fills in live. Ctrl+C stops it.

No config file. No account. No telemetry — nothing about your sessions is reported anywhere. What does go out is short and ordinary: a ~20-byte version check against the npm registry (plus one small request to confirm a version it has not seen before), installs and daily version checks for the two tools the deck manages (claude-swap from PyPI, ccusage from npm), and, while the page is open, quota reads to Anthropic and OpenAI signed with your own credentials — that is where those numbers live. AGENTS_DECK_NO_INSTALL=1 turns off everything but the quota reads; AGENTS_DECK_NO_DOWNLOAD=1 is the narrower version — no uv binary is fetched, the managed installs stay.

What you get

How it works

Two capture paths feed one SSE stream, which feeds one canvas.

Claude Code — on first run, ccdeck adds a hook entry to ~/.claude/settings.json for every relevant event (or to $CLAUDE_CONFIG_DIR/settings.json, and every other path below moves with it, when you have that variable set):

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

Each one fires the bundled hook.js, which POSTs the event JSON to the running server. The hook is fire-and-forget with a 1-second timeout: if the deck is not running, your session is not slowed down and nothing fails.

OpenAI Codex — Codex CLI hooks do not fire reliably on Windows, so nothing is installed at all. The server tails Codex's own rollout files at ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl and reconstructs the equivalent stream — session start, prompts, tool calls, token usage, model. No hook install, no trust prompt. Set CODEX_HOME to override the path.

Quota is the one thing that is not just reading. It needs a live token, so when the one in ~/.codex/auth.json is within 90 seconds of expiring the deck refreshes it exactly as the CLI does and writes the rotated credential back — one refresh at a time, re-reading the file inside the lock, and atomically, because OpenAI's refresh tokens are single-use and a rotation that never reaches disk costs you a codex login. It happens only while the page is open, and nothing else in auth.json is touched.

Accounts

The Accounts panel reads the store claude-swap keeps, and can drive it.

+ → Sign in runs claude auth login, shows you the link, takes the code your browser gives back, and hands the result to cswap add. The account you were using stays active — signing in replaces the live credentials, so the previous one is switched back the moment the new one is recorded. The code goes straight into the CLI's stdin on this machine; it is never stored, logged, or sent anywhere else.

share on an account produces a ccdeck1:… blob to paste into another deck's + → Paste a share.

[!WARNING]
A share carries that account's live login in the clear — claude-swap's export format has no encryption. It expires ten minutes after it is made and imports refuse it after that. While it lives, treat it like a password: anything that can read your clipboard can read the account.

Renaming, reordering and removing are on the same row menu. Removal takes two clicks and cannot be undone.

Updating

The deck checks npm for a newer release at most once an hour, plus once when it starts — a ~20-byte GET to registry.npmjs.org, asking about the package this copy would actually install (a deck started with npx ccdeck asks about ccdeck). When that names a version it has not seen before, one more request confirms the version is really there: npm moves the dist-tag before the version itself has propagated, and a banner shown inside that window ends in ETARGET instead of an upgrade. So a check is one request, or two when there is something new to confirm — and a version that is tagged but not yet installable is looked at again in five minutes rather than in an hour. Click the version chip in the topbar to ask immediately.

What the banner offers depends on how this copy was installed:

Nothing is ever installed unless you click, the argument vector is fixed in the server rather than taken from the request, and the command is always on screen — button or no button. If npm fails, the banner shows npm's own last line.

Restarting

ccdeck runs as a two-process pair: a supervisor that owns nothing but the lifecycle, and the deck itself. When newer code is found, the deck exits with code 75 and the supervisor brings it back on the port it actually bound, which is not always the one it asked for. Ctrl+C, stdout and exit codes behave exactly as before — same terminal, same process group.

It restarts on its own only after 30 seconds with nothing running, because hook events are fire-and-forget and anything fired during the gap is lost. The toggle in the banner turns that off; the preference is per-browser. Under --no-persist a restart is refused outright — with no event log there is nothing to replay, and the canvas would be gone.

Options

ccdeck [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)
      --claude             Force Claude capture even if Claude Code wasn't found
      --no-claude          Skip Claude entirely — no hooks, no claude-swap,
                           no Accounts panel (Codex only)
      --uninstall          Remove ccdeck's hooks from settings files
  -h, --help               Show this help

ccdeck looks for each CLI before it does anything on that CLI's behalf. Claude
Code counts as present when its binary is on PATH (or in one of the places its
installers put it), or when its config dir carries traces of having been used;
Codex counts as present when ~/.codex/ exists. On a machine with only one of
them, the other one's hooks, installs and panels are skipped rather than shown
empty — the boot banner says which way it went, and --claude / --codex
override it if the guess is wrong.

--workspace is a filter this deck applies to itself, not a claim on the sessions it matches: every running deck whose workspace contains a session's directory draws that session, so a machine-wide deck and one scoped to ~/proj both show the agents working inside ~/proj. It reads the same way on both capture paths — Claude Code's hook and Codex's rollout files — and the events log still gets exactly one copy of each event, whichever decks are up. A relative path is resolved against the directory you start the deck in, and once, so both paths scope to the same tree.

Environment:

Being told to restart after an upgrade is local only — no network involved — and cannot be turned off, because a deck running superseded code is a bug you cannot see any other way.

Uninstall

npx ccdeck --uninstall

Removes every hook entry ccdeck injected from ~/.claude/settings.json, and ~/.codex/hooks.json if present.

It removes the hook entries and nothing else. The forwarder script
(~/.claude/agent-dag/hook.js), the discovery directory around it, the events
log, and the tools ccdeck installed for you — claude-swap, ccusage, and a uv
binary if it had to fetch one — are all left in place, and each has its own
uninstaller. Deleting ~/.claude/agent-dag/ and ~/.agents-deck/ clears
ccdeck's own files; uv tool uninstall claude-swap (or pipx uninstall claude-swap) removes the account switcher.

Design

One canvas. No tabs. No kanban.

• Node = agent (root session or subagent)
• Edge = parent → child (spawn), or agent → tool (call)
• In-flight animates; settled dims
• Click a node for the full story

Names

ccdeck is the name — of this repo and of the command. On npm it goes out
under three, and npx runs the same deck from any of them.

npx ccdeck        # this repo's name — the short one
npx agents-deck   # the canonical npm package (in-app updates install this one)
npx agent-dag     # the original name; existing installs and scripts keep working

A global install is the one place the three differ. agents-deck and
agent-dag are one build published twice, so npm i -g on either puts all
three commands on your PATH. ccdeck is a thin package that depends on
agents-deck and ships only the ccdeck command.

The repository was previously named agents-deck; the old URL redirects here,
so existing clones, links and bookmarks keep working.

Requirements

• Node.js ≥ 18 — macOS, Linux and Windows
• Claude Code CLI or OpenAI Codex CLI (or both)
• Optional: claude-swap for the Accounts panel; the deck can install it for you

License

MIT © Bargan Constantin