agent-dag 3.20.0 → 3.21.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# ccdeck
+# ccdeck — a live dashboard for Claude Code and Codex
 
 **Know which agent is waiting on you, and for how long.**
 
@@ -22,7 +22,7 @@ npx ccdeck
 
 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) · [Options](#options)
+[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>
@@ -43,6 +43,43 @@ ccdeck draws the tree instead. It is local and needs no configuration: it regist
 
 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. |
@@ -52,6 +89,7 @@ One canvas. No tabs. No kanban.
 | **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. |
 
@@ -61,7 +99,12 @@ One canvas. No tabs. No kanban.
 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. 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. `Ctrl+C` stops it.
+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.
 
@@ -158,6 +201,37 @@ An import adds what is missing and leaves a working account exactly as it is. Th
 
 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
 
 ```
@@ -287,7 +361,7 @@ Being told to restart after an upgrade is local only — no network involved —
 npx ccdeck --uninstall
 ```
 
-Removes every hook entry ccdeck injected from `~/.claude/settings.json`, and `~/.codex/hooks.json` if present.
+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
@@ -315,7 +389,7 @@ Nothing is ever installed unless you click, the argument vector is fixed in the
 
 ### 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.
+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.
 
@@ -349,6 +423,40 @@ 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
 
 MIT © [Bargan Constantin](https://github.com/BarganConstantin)