agent-dag 3.22.0 → 3.22.3

package/README.md

@@ -1,482 +1,11 @@
-<div align="center">
+# agent-dag
 
-# ccdeck — a live dashboard for Claude Code and Codex
-
-**Know which agent is waiting on you, and for how long.**
-
-**ccdeck keeps them in one queue** — every session stopped on a human, longest wait first, and the count in the topbar is one click to the oldest. That queue is Claude Code's, because Codex emits no such signal; the canvas under it is both, with every Claude Code subagent on a node of its own.
-
-[![npm](https://img.shields.io/npm/v/ccdeck?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/ccdeck)
-[![agents-deck downloads](https://img.shields.io/npm/dm/agents-deck?color=blue&label=agents-deck%20downloads)](https://www.npmjs.com/package/agents-deck)
-[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
-[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org)
-[![macOS · Linux · Windows](https://img.shields.io/badge/macOS%20·%20Linux%20·%20Windows-supported-6aa9f7)](#requirements)
-
-```bash
-npx ccdeck
-```
-
-[![ccdeck — live agent DAG](assets/canvas.png)](assets/canvas.png)
-
-*A generated session, drawn by the deck itself — see `assets/canvas-demo.mjs`. Click through for full size.*
-
-who is blocked on you · tool calls · one canvas · cost · quota · local · no telemetry
-
-[What you get](#what-you-get) · [Quick start](#quick-start) · [How it works](#how-it-works) · [What it touches](#what-it-touches) · [Accounts](#accounts) · [Local network](#local-network) · [Options](#options) · [FAQ](#questions-people-ask)
-
-
-</div>
-
----
-
-## Why
-
-Four agents running, and the machine has been quiet for twenty minutes. One of them stopped to ask something and you did not see it go by. From the outside every terminal tab looks the same — the one that is working and the one that has been holding a permission prompt since the coffee — so you find it by clicking through them, and the agent that was closest to finished is the one that has been waiting longest.
-
-ccdeck answers that in one place: every session stopped on a human is at the top of the sidebar with the wait beside it, longest first, and the count in the topbar goes straight to the oldest one. The question stops being *which tab* and becomes *this one*.
-
-That is the sharp end of a wider problem. 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.
-
-## What you get
-
-One canvas. No tabs. No kanban.
-
-The deck opens on these eight pictures the first time it runs — they are the whole tour, and `Take the tour` on an empty canvas brings them back.
-
-<table>
-<tr>
-<td><img src="assets/guide/welcome-1.svg" width="440" alt="Sessions waiting on you rise to the top, longest wait first."></td>
-<td><img src="assets/guide/welcome-2.svg" width="440" alt="Every agent and subagent is a node. Tool calls light up as they run."></td>
-</tr>
-<tr>
-<td align="center"><sub>Sessions waiting on you rise to the top, longest wait first.</sub></td>
-<td align="center"><sub>Every agent and subagent is a node. Tool calls light up as they run.</sub></td>
-</tr>
-<tr>
-<td><img src="assets/guide/welcome-3.svg" width="440" alt="Click any node: its prompt, every tool call, tokens and timing."></td>
-<td><img src="assets/guide/welcome-4.svg" width="440" alt="What each session costs, and how much quota is left."></td>
-</tr>
-<tr>
-<td align="center"><sub>Click any node: its prompt, every tool call, tokens and timing.</sub></td>
-<td align="center"><sub>What each session costs, and how much quota is left.</sub></td>
-</tr>
-<tr>
-<td><img src="assets/guide/welcome-5.svg" width="440" alt="Cores, memory and heat while the agents run, and what is hogging them."></td>
-<td><img src="assets/guide/welcome-6.svg" width="440" alt="Several Claude accounts: switch, add one, share one to another machine."></td>
-</tr>
-<tr>
-<td align="center"><sub>Cores, memory and heat while the agents run, and what is hogging them.</sub></td>
-<td align="center"><sub>Several Claude accounts: switch, add one, share one to another machine.</sub></td>
-</tr>
-<tr>
-<td><img src="assets/guide/welcome-7.svg" width="440" alt="Your machines repair each other's expired logins over the local network."></td>
-<td><img src="assets/guide/welcome-8.svg" width="440" alt="Run claude or codex in any folder. It shows up here on its own."></td>
-</tr>
-<tr>
-<td align="center"><sub>Your machines repair each other's expired logins over the local network.</sub></td>
-<td align="center"><sub>Run <code>claude</code> or <code>codex</code> in any folder. It shows up here on its own.</sub></td>
-</tr>
-</table>
-
-| | |
-|---|---|
-| **Blocked on you** | A permission prompt, or a finished turn waiting for your next instruction, sorts that session to the top of the sidebar with how long it has been stuck — longest wait first, so the oldest block is the first row. A permission prompt also puts a count in the topbar that jumps straight to it. Claude Code only — Codex emits no such signal. |
-| **Live DAG** | Nodes are agents, edges are spawns and tool calls. In-flight edges animate, settled ones fade. |
-| **Both providers, one canvas** | Claude Code through hooks, Codex through its rollout log. The model chip (`Opus 5`, `GPT-5.5`) tells them apart. |
-| **Cost and quota, live** | Spend per model and per session, plus Claude and Codex quota windows as they refill. |
-| **Click to inspect** | Any node opens its prompt, tool calls, token usage and timing. |
-| **Survives restarts** | Events are appended to `~/.claude/agent-dag/events.jsonl` and replayed on open. |
-| **Accounts without a terminal** | Sign a new Claude account in, move one or your whole set to another machine, rename, reorder, remove — from the panel. |
-| **Logins that repair each other** | A Claude login that expires on one of your machines is copied back from another machine on the same network that still has it — see [Local network](#local-network). |
-| **Knows when it is stale** | Node caches modules at startup, so an upgraded-while-running deck keeps executing old code. This one says so, and can restart itself when nothing is running. |
-| **Workspace scoping** | `--scope` for the current directory, `--workspace <path>` for any subtree — for Claude Code and Codex alike. |
-
-## Quick start
-
-```bash
-npx ccdeck          # or: npx agents-deck · npx agent-dag — same deck
-```
-
-Opens **http://127.0.0.1:4317**, shows an eight-picture tour the first time, and registers the Claude Code hook on first run. If something else already holds 4317, the deck takes a port between 4318 and 4400 instead and prints the address it ended up on — that line in the terminal is the one to trust. Start any Claude Code or Codex session and the graph fills in live.
-
-The deck keeps running after you close the terminal, and starts again when you
-log in. **`ccdeck --stop` is the off switch**; `Ctrl+C` only cancels a start that
-is still printing. `ccdeck --status` says what is running, and `--foreground`
-holds the terminal the way every version before 3.20 did.
-
-No config file. No account. No telemetry — nothing about your sessions is reported anywhere.
-
-**The deck cannot steer your agent.** The hook it installs is a one-way forwarder: it POSTs the event, exits `0`, and writes nothing to stdout. Those are the two channels Claude Code's hook protocol gives a hook for allowing, denying, deferring or rewriting the tool call it was told about, and this one uses neither — it has no way to answer at all. `src/web/__tests__/hook-read-only.test.ts` pins both halves, over the source and by running the real script.
-
-What the deck does write, and the short list of what does leave the machine, is in [What it touches](#what-it-touches).
-
-## Requirements
-
-- Node.js ≥ 18 — macOS, Linux and Windows. The floor is checked on every run: CI installs the packed release on Node 18 and boots it, so the badge is a measurement rather than a claim
-- Claude Code CLI or OpenAI Codex CLI (or both)
-- Optional: [claude-swap](https://pypi.org/project/claude-swap/) for the Accounts panel; the deck can install it for you
-- Nothing else. On Apple Silicon the deck fetches [`macmon`](https://github.com/vladkens/macmon) itself for the temperature rows; see below.
-
-### Temperature, per machine
-
-The machine panel shows a **Thermal** section only where the machine actually answers, and it never invents a reading — no sensor means no row.
-
-| | reads | needs |
-| --- | --- | --- |
-| Linux | `/sys/class/hwmon`, then `/sys/class/thermal/thermal_zone*` | nothing |
-| Windows | the `Thermal Zone Information` performance counter, then `MSAcpi_ThermalZoneTemperature`, then LibreHardwareMonitor's web server if it happens to be running | nothing — where the machine has an ACPI thermal zone. Many do not; see below |
-| macOS, Intel | `ioreg` for the GPU, `pmset -g therm` for throttling | nothing |
-| macOS, Apple Silicon | `macmon`, which the deck fetches for you | nothing |
-
-Apple Silicon is the one that needs a tool, and it is not an oversight. No command that ships with macOS prints a temperature on an M-series Mac: `powermetrics` needs root, `pmset -g therm` records nothing there, and the sensors sit behind a private API that only native code can call. [`macmon`](https://github.com/vladkens/macmon) reads them without `sudo` and covers M1 through M5.
-
-You do not have to install it. The deck downloads the published binary into `~/.agents-deck/tools/macmon` — the same place it already keeps `uv` — verifies it against the SHA-256 the GitHub release publishes, checks that it runs, and only then uses it. Not through Homebrew, because a machine without Homebrew would need Homebrew installed first, and that is a large thing to do to somebody who asked for a dashboard. It happens in the background, after the deck is already up, and never on the first run's critical path.
-
-It is skipped entirely on a machine that already answers, on an Intel Mac — the release publishes an arm64 build and only that, so the architecture is checked before anything is fetched — and on one where you have `macmon` yourself, which is looked for on PATH and on either Homebrew prefix before the download is considered. `AGENTS_DECK_NO_DOWNLOAD=1` turns it off on its own; `AGENTS_DECK_NO_INSTALL=1` turns it off along with everything else.
-
-#### Windows, and why it is often blank
-
-Windows is the platform where this most often shows nothing, and that is not a defect in the deck. Measured on a physical Windows 11 laptop — a Lenovo IdeaPad L340, Intel i5-9300H, English install, checked both as an ordinary user and as an administrator:
-
-- its firmware declares **zero** ACPI thermal zones, so the performance counter above is registered but has no instances
-- `MSAcpi_ThermalZoneTemperature` — which the deck does try, in the same PowerShell child, whenever the counter has no instances — answers `Not supported` **even to an administrator**
-- `Win32_TemperatureProbe` exists but every field reads `32768`, which is WMI's value for "unknown"
-- the sensors are real and actively managed — Intel Dynamic Tuning is running — but it publishes them in `root\WMI EsifDeviceInformation`, which is **Access denied** without administrator
-
-That is a class of machine, not a fault: modern Intel laptops moved thermal management into Intel DTT and stopped declaring the ACPI zones that Windows exposes to ordinary programs. There is no standard user-mode Windows API for CPU temperature — which is why HWiNFO, Core Temp and LibreHardwareMonitor all install a kernel driver, and why this deck does not.
-
-Where the counter does have instances — many desktop boards, servers, and older laptops — it is read without any privileges at all. Its path is currently English-only; see [#747](https://github.com/BarganConstantin/ccdeck/issues/747).
-
-One thing does work on the machines above, and it costs you nothing to have: if **LibreHardwareMonitor** happens to be running with its web server on, the deck reads its numbers over plain HTTP on localhost, which needs no privileges. That is a read, not a request — the deck does not install it, will not ask you to, and shows no section if it is not there. It is mentioned only so nobody is surprised to see degrees appear on a machine that had none.
-
-## 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.
-
-## What it touches
-
-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. It also reads your browser's history when Browser Watch is on; that is its own section below, because it is the one thing here that is about you rather than about an agent.
-
-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), on an Apple Silicon Mac whose sensors stay silent one release lookup and one binary download from GitHub for `macmon`, 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.
-
-## Browser Watch
-
-The panel behind the eye icon answers one question: **did something drive your browser while you were away?** An agent with browser control opens pages through an API, and Chromium records that — `visits.transition` says `FROM_API` rather than `LINK` or `TYPED`. So a run of those, in a stretch when you were not touching the machine, is a finding worth showing.
-
-To answer it the deck reads the browsers' own history. That means, on each poll: it finds every Chromium profile (Chrome, Brave, Edge, Vivaldi), **copies each profile's `History` database** to a temp file — a live database cannot be opened safely — queries the visits newer than the moment this deck started, and deletes the copy. Nothing leaves the machine, and the copy exists for as long as one query takes.
-
-**The switch decides whether any of that happens in the background.** With Browser Watch off, the deck's five-minute poll reads no browser at all; with it on, the poll reads, keeps what it finds in `~/.claude/agent-dag/browser-watch/state.json`, writes a line per finding to `watch.log` beside it, and performs whatever reaction you chose. Opening the panel always reads live, on either setting — that is you looking, and it is the only way the panel can tell you what is there.
-
-Only visits **after this deck started** are ever considered. Your existing history is not swept, not archived and not shown.
-
-## Accounts
-
-The Accounts panel reads the store [claude-swap](https://pypi.org/project/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 `ccdeck2:…` blob to paste into another deck's **`+` → Paste a share**.
-
-**`↗`** in the panel header does the same for a set of them, which is what moving your accounts from home to work actually is. Tick the ones to send — all of them to start — and one blob carries the set. The dialog counts sign-in tokens rather than rows, and an account that cannot be exported is named rather than quietly dropped, so the number on the copy button is always the number in the blob.
-
-An import adds what is missing and leaves a working account exactly as it is. The one it does rewrite unasked is a slot claude-swap has itself quarantined as refresh-token-dead, which is what heals a machine whose login stopped working. The result names every account in the paste — imported, already here, healed, or refused — and an account it skipped can be overwritten one at a time with **update anyway**.
-
-> [!WARNING]
-> A share carries the **live login of every account in it, in the clear** — claude-swap's export format has no encryption, and five ticked boxes is five passwords on your clipboard. It expires ten minutes after it is made and imports refuse it after that. While it lives, treat it as those passwords: anything that can read your clipboard can read the accounts.
-
-Renaming, reordering and removing are on the same row menu. Removal takes two clicks and cannot be undone.
-
-## Local network
-
-A Claude login expires on the machine that has not used it for a while, and stays alive on the one that has. With two or three machines that is a `claude login` a week, each time on the machine you are not sitting at. **Local network** is the last section of the Claude accounts panel, and it is that chore done for you: decks on one network find each other, pair, and a login that has expired on one is copied back from another that still has it.
-
-Four pictures, which are also the guide the section opens from `See how it works`:
-
-<table>
-<tr>
-<td><img src="assets/guide/lan-1.svg" width="440" alt="A login can expire on one machine while it still works on another."></td>
-<td><img src="assets/guide/lan-2.svg" width="440" alt="Turn this on, on both machines. They find each other and pair."></td>
-</tr>
-<tr>
-<td align="center"><sub><b>1.</b> A login can expire on one machine while it still works on another.</sub></td>
-<td align="center"><sub><b>2.</b> Turn this on, on both machines. They find each other and pair.</sub></td>
-</tr>
-<tr>
-<td><img src="assets/guide/lan-3.svg" width="440" alt="Tick which logins this machine may hand out. Nothing is shared until you do."></td>
-<td><img src="assets/guide/lan-4.svg" width="440" alt="An expired login is copied from a paired machine within a minute."></td>
-</tr>
-<tr>
-<td align="center"><sub><b>3.</b> Tick which logins this machine may hand out. Nothing is shared until you do.</sub></td>
-<td align="center"><sub><b>4.</b> An expired login is copied from a paired machine within a minute.</sub></td>
-</tr>
-</table>
-
-**On each machine, in order:** open the Claude accounts panel (`A`), switch **Local network** on, and in the dialog that opens tick the logins this machine may hand out. That is all — the two decks find each other over a UDP beacon on port 45317, pair on their own, and from then on every paired deck is asked once a minute for anything this deck's expired logins need.
-
-**When they do not find each other** — a VPN, a guest network, two subnets — `+` at the top of the section reaches a deck by address, or with an invite the other deck minted. An invite is the route when the machine that cannot be seen is this one.
-
-**What is shared, and with whom.** Nothing until you tick a login, and then only that login, and only with decks somebody at this machine accepted — the deck asks the machines it finds and says yes to the ones that ask, and both switches are in the same dialog if you would rather press `accept` yourself. A paired deck can fill an *expired* slot of this deck's and nothing else: it cannot overwrite a login that still works here. What crosses the wire is the same live credential a share carries, sealed to the deck it is addressed to, so treat the pairing decision as the moment that matters. Unpairing stops future rounds; a login already copied stays where it went.
-
-## Options
+This is the old name for **[ccdeck](https://www.npmjs.com/package/ccdeck)**.
 
 ```
-ccdeck [options]
-
-  -p, --port <number>      Preferred port  (default: 4317; fallback: random 4318–4400)
-      --no-open            Don't open the browser automatically
-      --foreground         Hold the terminal, the way every version before 3.20
-                           did (Ctrl+C stops the deck again)
-      --new                Start a second deck even if one is already running
-      --stop               Stop the deck a bare `ccdeck` would open
-                           (--port <n> stops that one; --all stops every deck)
-      --status             What is running on this machine, and on which ports
-      --logs               What a backgrounded deck wrote where a terminal would
-                           have shown it
-      --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)
-                           (beside --stop: every deck, not every session)
-      --history <path>     Override the events log file
-                           (default: this platform's log directory —
-                           ~/Library/Logs/ccdeck on macOS, %LOCALAPPDATA%\ccdeck\Log
-                           on Windows, $XDG_STATE_HOME/ccdeck on Linux)
-      --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
-  -v, --version            Print the version and exit
-```
-
-Anything else on the command line is reported as an unknown option and then
-ignored — the deck still starts, so a typo costs you a warning rather than a
-dashboard.
-
-`--foreground` is there for anything that was relying on the old behaviour — a
-wrapper script, a CI step, a supervisor of your own that starts the deck and
-waits on it. On the first run after upgrading you may also see a line about a
-deck from an older version still running: those publish nothing this one can
-check, so it starts beside them rather than attaching to something it cannot
-identify, and `ccdeck --stop --all` clears them.
-
-`ccdeck` runs in the background. The boot report prints in your terminal exactly
-as it always has — the hooks, the port, the URL — and then the prompt comes back
-and the deck stays up: closing the window does not take it with you any more,
-because it is in its own process group and the terminal's hangup never reaches
-it. `ccdeck --stop` ends it, `ccdeck --status` says what is running, and
-`ccdeck --logs` shows what it wrote after you stopped watching. Ctrl+C while the
-boot is still printing cancels the start, which is the one thing it still means.
-
-One Windows exception, and it is `ssh`'s rather than the deck's: OpenSSH puts a
-session's processes in a job object that it kills when the session ends, and
-nothing started from inside one survives it. A deck started from an ordinary
-Windows terminal, or by the login task below, keeps running — measured on a real
-machine, from a second SSH session, still serving.
-
-It also starts when you log in, so a reboot does not cost you the morning's
-events. That is set up once, on the first run, and said out loud when it happens;
-`ccdeck --uninstall-service` undoes it and `ccdeck --uninstall` takes it with the
-hooks. A launchd agent on macOS, a `systemd --user` unit on Linux, a Task
-Scheduler logon task on Windows — none of them carrying a restart policy of its
-own, because the one that decides when a crashed deck stops coming back lives in
-ccdeck and two policies over one process is how a stop becomes a suggestion. An
-`npx` run never installs one: it would name a path inside npm's cache, which npm
-deletes without warning. On Linux, `systemd --user` is torn down at logout unless
-`loginctl enable-linger` is on for your account — the install says so rather than
-changing that for you.
-
-If the deck falls over on its own, it comes back — five times in ten minutes,
-with the wait doubling each time, and then it stops and says so in the log rather
-than spinning on a machine nobody is watching. A clean `--stop` is never answered
-with a restart, and neither is a deck that failed to start in the first place:
-retrying a port the OS will not give you just prints the same refusal six times.
-
-Typing plain `ccdeck` beside a deck that is already running opens **that deck's
-tab** rather than building a second one. It used to build the second one: port
-4317 was busy, so the new deck took a random port out of 4318–4400 and stood
-there beside a perfectly healthy first one, and neither mentioned the other.
-The port fallback is still there — 4317 is also the standard OTLP collector
-port, and Windows reserves whole TCP ranges for Hyper-V, WSL2 and Docker — but
-it now runs only when the thing holding the port is *not* one of your decks. The
-deck on the port has to prove it is yours, with the same token handshake the
-hooks use, before its tab is opened. Any flag that changes what the deck **is**
-— a port, a workspace, a log, either `--codex` or `--claude` pair — still starts
-its own, and `--new` starts one unconditionally.
-
-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 all three paths a session can reach the canvas by — Claude Code's hook, Codex's rollout files, and the boot replay of the events log — 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 every path scopes to the same tree. The log is machine-wide by default and shared by every deck on the box, so a scoped deck replays only the part of it that is inside its own workspace: it comes up showing what it will go on to capture, and nothing else.
-
-That one events log is also the reason Clear is not quite the per-deck button it looks like. The decks elect a single writer for each log file, and only that deck may empty it: Clear on any other deck wipes its own canvas and leaves the file to the deck that writes it. The confirmation says which of the two you are about to do, and how many decks share the log when it is yours to empty — so `--history` or `--no-persist` gives a deck a log of its own if you want Clear to answer to nobody else.
-
-Environment:
-
-| Variable | Effect |
-|---|---|
-| `AGENT_DAG_PORT` | Default port, same as `-p` |
-| `CODEX_HOME` | Override `~/.codex` |
-| `AGENTS_DECK_NO_INSTALL=1` | Never install or update claude-swap / ccusage, and never ask npm about releases |
-| `AGENTS_DECK_NO_DOWNLOAD=1` | Never download the `uv` binary, but keep the managed installs |
-| `AGENTS_DECK_NO_UPDATE_CHECK=1` | Don't ask npm about releases, but keep everything else |
-| `AGENTS_DECK_NO_FRESHEN=1` | Never nudge claude-swap to collect usage early |
-| `AGENTS_DECK_NO_NOTIFY=1` | Never raise a desktop notification when a session blocks and no page is open |
-| `AGENTS_DECK_CSWAP` | Full path to `cswap`, when it lives somewhere unusual |
-| `AGENTS_DECK_CLAUDE` | Full path to the `claude` CLI |
-| `AGENTS_DECK_CCUSAGE` | Full path to your own `ccusage`, used ahead of everything else |
-| `CLAUDE_SWAP_BACKUP` | Override the claude-swap store root the Accounts panel reads |
-| `CLAUDE_CONFIG_DIR` | Override `~/.claude` — the hook entry, the event log and everything else the deck writes move with it |
-| `AGENTS_DECK_LHM_PORT` | Port of a running LibreHardwareMonitor web server, when it is not 8085 (Windows temperatures) |
-
-Usage history is read with `ccusage`, and the deck takes the first of these that answers: `AGENTS_DECK_CCUSAGE` if you set it, then the copy it installed for itself under `~/.agents-deck/ccusage`, then a `ccusage` on your PATH, then `npx -y ccusage@latest`. So installing ccusage yourself is enough — the deck will not fetch a second copy, and it works under `AGENTS_DECK_NO_INSTALL=1`, which is the combination that variable is for. When something fails, the modal names which of those four it was.
-
-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
-
-```bash
-npx ccdeck --uninstall
-```
-
-Removes every hook entry ccdeck injected from `~/.claude/settings.json`, and `~/.codex/hooks.json` if present — and the login item, if this machine had one. That one exception to the narrowness below is deliberate: a login item left behind would keep starting a deck whose hooks had just been removed.
-
-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.
-
-## 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:
-
-| Installed as | Offer |
-|---|---|
-| global npm install | **Update now** — runs `npm install -g` on the name you installed (`ccdeck`, `agents-deck` or `agent-dag`), then restarts once nothing is running |
-| `npx` | **Update & restart** — re-runs the spec through npx, which fetches a fresh copy and takes over the same port |
-| git checkout | the command, because your working copy leads npm: `git pull && npm run build` |
-| directory not writable | the command — a root-owned prefix is declined up front rather than failing inside npm |
-| `AGENTS_DECK_NO_INSTALL=1` | the command only; you asked for no installs |
-
-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. Both live in their own process group since 3.20, so stdout goes to `deck.log` rather than to the terminal you started from — `ccdeck --logs` reads it back. The supervisor also puts the deck back after a crash, five times in ten minutes with the wait doubling, and then stops and says why rather than spinning.
-
-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.
-
-## Design
-
-- 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.
-
-```bash
-npx ccdeck        # this repo's name — the short one
-npx agents-deck   # the name it shipped under before the rename
-npx agent-dag     # the original name; existing installs and scripts keep working
+npx ccdeck
 ```
 
-The three are one build published three times, so they behave identically:
-`npx` on any of them fetches a single package, and `npm i -g` on any of them
-puts all three commands on your `PATH`.
-
-`ccdeck` was the exception until recently — a thin package that depended on
-`agents-deck` and spawned its binary. It worked, but `npx ccdeck` downloaded two
-packages instead of one and a global `ccdeck` ran under the old package's name.
-It is now the same build as the other two.
-
-The repository was previously named `agents-deck`; the old URL redirects here,
-so existing clones, links and bookmarks keep working.
-
-## Questions people ask
-
-**Does it work with Codex, or only Claude Code?**
-Both, on one canvas. Claude Code arrives through a hook, Codex through its
-rollout log, and the model chip tells them apart. The *blocked on you* queue is
-Claude Code only — Codex emits no signal for it.
-
-**Does anything leave my machine?**
-Your sessions, never. The deck binds `127.0.0.1` and has no telemetry. The only
-outbound requests are a ~20-byte version check to the npm registry at most once
-an hour, and whatever the usage panels ask Anthropic and OpenAI for about your
-own quota. [What it touches](#what-it-touches) lists all of it.
-
-**Can it interfere with what my agent does?**
-No. The hook it installs is a one-way forwarder: it POSTs the event, exits `0`,
-and writes nothing to stdout — the two channels Claude Code's hook protocol
-gives a hook for allowing, denying or rewriting a tool call. It uses neither, so
-it has no way to answer at all, and a test pins both halves.
-
-**Does it need an account, an API key or a config file?**
-None of the three. `npx ccdeck` and it runs.
-
-**macOS, Linux, Windows?**
-All three, and each release is tested on all three.
-
-**What is the difference between `ccdeck`, `agents-deck` and `agent-dag`?**
-One deck, three names on npm. `ccdeck` is the one to use; the other two are the
-names it shipped under before, kept working so nobody's command breaks. See
-[Names](#names).
-
-**Do I have to keep a terminal open?**
-No. Since 3.20 the deck runs in the background, survives the terminal closing,
-and starts again when you log in. `ccdeck --stop` ends it.
-
-## License
-
-ccdeck is licensed under the GNU Affero General Public License v3.0 only
-(AGPL-3.0-only).
-
-Copyright © 2026 [Bargan Constantin](https://github.com/BarganConstantin).
-
-See [LICENSE](./LICENSE) for the full text.
-
-Running the deck imposes nothing on you. The AGPL's obligations attach to
-distributing ccdeck or offering a **modified** version to users over a network
-— and what they require is that those users be offered the corresponding
-source of that modified version, not that anyone contribute changes back to
-this repository.
-
-Releases up to and including **3.21.4** were published under the MIT licence
-and remain available under MIT — this change is not retroactive and revokes
-nothing already granted. [LICENSING.md](./LICENSING.md) explains what applies
-to which version.
-
-ccdeck bundles third-party code under permissive licences (MIT, ISC,
-BSD-3-Clause); their notices are preserved in
-[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+Running `npx agent-dag` still works and will keep working — it installs ccdeck
+and starts it. There is nothing else in this package, and it is not where the
+deck is developed or documented.

package/package.json

@@ -1,33 +1,23 @@
 {
   "name": "agent-dag",
-  "version": "3.22.0",
-  "description": "Live deck of Claude Code and Codex agents — watch tool calls, token spend and every Claude Code subagent on one calm canvas. Run it with npx ccdeck.",
+  "version": "3.22.3",
+  "description": "Renamed to ccdeck. This package installs and starts ccdeck for you — run `npx ccdeck` instead.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BarganConstantin/ccdeck.git"
+  },
+  "homepage": "https://github.com/BarganConstantin/ccdeck#readme",
   "type": "module",
   "bin": {
-    "agents-deck": "bin/agent-dag.js",
-    "agent-dag": "bin/agent-dag.js",
-    "ccdeck": "bin/agent-dag.js"
+    "agent-dag": "shim.js"
   },
   "files": [
-    "bin",
-    "hook",
-    "src/server",
-    "dist/web",
-    "release-notes.json",
-    "LICENSE",
-    "README.md",
-    "THIRD_PARTY_NOTICES.md",
-    "LICENSING.md"
+    "shim.js",
+    "README.md"
   ],
-  "scripts": {
-    "dev:web": "vite",
-    "dev:server": "node src/server/index.mjs",
-    "start": "node bin/agent-dag.js",
-    "build": "vite build",
-    "test": "vitest run",
-    "prepublishOnly": "vite build",
-    "prepack": "vite build",
-    "typecheck": "tsc --noEmit -p tsconfig.build.json"
+  "dependencies": {
+    "ccdeck": "^3"
   },
   "engines": {
     "node": ">=18"
@@ -46,29 +36,5 @@
     "deck",
     "graph",
     "live"
-  ],
-  "author": "Bargan Constantin",
-  "license": "AGPL-3.0-only",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/BarganConstantin/ccdeck.git"
-  },
-  "bugs": {
-    "url": "https://github.com/BarganConstantin/ccdeck/issues"
-  },
-  "homepage": "https://github.com/BarganConstantin/ccdeck#readme",
-  "devDependencies": {
-    "@types/dagre": "^0.7.54",
-    "@types/node": "^22.20.1",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
-    "@vitejs/plugin-react": "^4.3.4",
-    "dagre": "^0.8.5",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "reactflow": "^11.11.4",
-    "typescript": "^5.6.3",
-    "vite": "^6.0.0",
-    "vitest": "^2.1.9"
-  }
+  ]
 }