agent-dag 1.35.16 → 1.35.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -5,16 +5,20 @@
|
|
|
5
5
|
**A live canvas for your AI agents.** Watch Claude Code and OpenAI Codex call tools and finish — every Claude Code subagent on a node of its own — all on one calm graph, in real time.
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/ccdeck)
|
|
8
|
-
[](https://www.npmjs.com/package/agents-deck)
|
|
9
9
|
[](LICENSE)
|
|
10
10
|
[](https://nodejs.org)
|
|
11
11
|
[](#requirements)
|
|
12
12
|
|
|
13
|
+
[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)
|
|
14
|
+
|
|
13
15
|
```bash
|
|
14
16
|
npx ccdeck
|
|
15
17
|
```
|
|
16
18
|
|
|
17
|
-
](assets/canvas.png)
|
|
20
|
+
|
|
21
|
+
*An older shot — the deck was still called `agents-deck` then. Click through for full size.*
|
|
18
22
|
|
|
19
23
|
</div>
|
|
20
24
|
|
|
@@ -24,32 +28,42 @@ npx ccdeck
|
|
|
24
28
|
|
|
25
29
|
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.
|
|
26
30
|
|
|
27
|
-
ccdeck draws the tree instead. It is local and needs no configuration: it registers a hook, listens, and paints.
|
|
28
|
-
|
|
29
|
-
## Quick start
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
npx ccdeck # or: npx agents-deck · npx agent-dag — same deck
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
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.
|
|
36
|
-
|
|
37
|
-
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.
|
|
31
|
+
ccdeck draws the tree instead. It is local and needs no configuration: it registers a hook, listens, and paints.
|
|
38
32
|
|
|
39
33
|
## What you get
|
|
40
34
|
|
|
35
|
+
One canvas. No tabs. No kanban.
|
|
36
|
+
|
|
41
37
|
| | |
|
|
42
38
|
|---|---|
|
|
39
|
+
| **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, and puts a count in the topbar that jumps to the oldest one. Claude Code only — Codex emits no such signal. |
|
|
40
|
+
| **Cost and quota, live** | Spend per model and per session, plus Claude and Codex quota windows as they refill. |
|
|
43
41
|
| **Live DAG** | Nodes are agents, edges are spawns and tool calls. In-flight edges animate, settled ones fade. |
|
|
44
42
|
| **Both providers, one canvas** | Claude Code through hooks, Codex through its rollout log. The model chip (`Opus 5`, `GPT-5.5`) tells them apart. |
|
|
45
|
-
| **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, and puts a count in the topbar that jumps to the oldest one. Claude Code only — Codex emits no such signal. |
|
|
46
43
|
| **Click to inspect** | Any node opens its prompt, tool calls, token usage and timing. |
|
|
47
|
-
| **Cost and quota, live** | Spend per model and per session, plus Claude and Codex quota windows as they refill. |
|
|
48
44
|
| **Survives restarts** | Events are appended to `~/.claude/agent-dag/events.jsonl` and replayed on open. |
|
|
49
45
|
| **Accounts without a terminal** | Sign a new Claude account in, share one to another machine, rename, reorder, remove — from the panel. |
|
|
50
46
|
| **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. |
|
|
51
47
|
| **Workspace scoping** | `--scope` for the current directory, `--workspace <path>` for any subtree — for Claude Code and Codex alike. |
|
|
52
48
|
|
|
49
|
+
## Quick start
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npx ccdeck # or: npx agents-deck · npx agent-dag — same deck
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
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.
|
|
56
|
+
|
|
57
|
+
No config file. No account. No telemetry — nothing about your sessions is reported anywhere.
|
|
58
|
+
|
|
59
|
+
What the deck does write, and the short list of what does leave the machine, is in [What it touches](#what-it-touches).
|
|
60
|
+
|
|
61
|
+
## Requirements
|
|
62
|
+
|
|
63
|
+
- Node.js ≥ 18 — macOS, Linux and Windows
|
|
64
|
+
- Claude Code CLI or OpenAI Codex CLI (or both)
|
|
65
|
+
- Optional: [claude-swap](https://pypi.org/project/claude-swap/) for the Accounts panel; the deck can install it for you
|
|
66
|
+
|
|
53
67
|
## How it works
|
|
54
68
|
|
|
55
69
|
Two capture paths feed one SSE stream, which feeds one canvas.
|
|
@@ -67,6 +81,12 @@ Each one fires the bundled `hook.js`, which POSTs the event JSON to the running
|
|
|
67
81
|
|
|
68
82
|
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.
|
|
69
83
|
|
|
84
|
+
## What it touches
|
|
85
|
+
|
|
86
|
+
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.
|
|
87
|
+
|
|
88
|
+
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.
|
|
89
|
+
|
|
70
90
|
## Accounts
|
|
71
91
|
|
|
72
92
|
The Accounts panel reads the store [claude-swap](https://pypi.org/project/claude-swap/) keeps, and can drive it.
|
|
@@ -80,28 +100,6 @@ The Accounts panel reads the store [claude-swap](https://pypi.org/project/claude
|
|
|
80
100
|
|
|
81
101
|
Renaming, reordering and removing are on the same row menu. Removal takes two clicks and cannot be undone.
|
|
82
102
|
|
|
83
|
-
## Updating
|
|
84
|
-
|
|
85
|
-
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.
|
|
86
|
-
|
|
87
|
-
What the banner offers depends on how this copy was installed:
|
|
88
|
-
|
|
89
|
-
| Installed as | Offer |
|
|
90
|
-
|---|---|
|
|
91
|
-
| global npm install | **Update now** — runs `npm install -g agents-deck@latest`, then restarts once nothing is running |
|
|
92
|
-
| `npx` | **Update & restart** — re-runs the spec through npx, which fetches a fresh copy and takes over the same port |
|
|
93
|
-
| git checkout | the command, because your working copy leads npm: `git pull && npm run build` |
|
|
94
|
-
| directory not writable | the command — a root-owned prefix is declined up front rather than failing inside npm |
|
|
95
|
-
| `AGENTS_DECK_NO_INSTALL=1` | the command only; you asked for no installs |
|
|
96
|
-
|
|
97
|
-
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.
|
|
98
|
-
|
|
99
|
-
### Restarting
|
|
100
|
-
|
|
101
|
-
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.
|
|
102
|
-
|
|
103
|
-
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.
|
|
104
|
-
|
|
105
103
|
## Options
|
|
106
104
|
|
|
107
105
|
```
|
|
@@ -166,9 +164,29 @@ uninstaller. Deleting `~/.claude/agent-dag/` and `~/.agents-deck/` clears
|
|
|
166
164
|
ccdeck's own files; `uv tool uninstall claude-swap` (or `pipx uninstall
|
|
167
165
|
claude-swap`) removes the account switcher.
|
|
168
166
|
|
|
169
|
-
##
|
|
167
|
+
## Updating
|
|
170
168
|
|
|
171
|
-
|
|
169
|
+
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.
|
|
170
|
+
|
|
171
|
+
What the banner offers depends on how this copy was installed:
|
|
172
|
+
|
|
173
|
+
| Installed as | Offer |
|
|
174
|
+
|---|---|
|
|
175
|
+
| global npm install | **Update now** — runs `npm install -g agents-deck@latest`, then restarts once nothing is running |
|
|
176
|
+
| `npx` | **Update & restart** — re-runs the spec through npx, which fetches a fresh copy and takes over the same port |
|
|
177
|
+
| git checkout | the command, because your working copy leads npm: `git pull && npm run build` |
|
|
178
|
+
| directory not writable | the command — a root-owned prefix is declined up front rather than failing inside npm |
|
|
179
|
+
| `AGENTS_DECK_NO_INSTALL=1` | the command only; you asked for no installs |
|
|
180
|
+
|
|
181
|
+
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.
|
|
182
|
+
|
|
183
|
+
### Restarting
|
|
184
|
+
|
|
185
|
+
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.
|
|
186
|
+
|
|
187
|
+
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.
|
|
188
|
+
|
|
189
|
+
## Design
|
|
172
190
|
|
|
173
191
|
- Node = agent (root session or subagent)
|
|
174
192
|
- Edge = parent → child (spawn), or agent → tool (call)
|
|
@@ -194,12 +212,6 @@ three commands on your `PATH`. `ccdeck` is a thin package that depends on
|
|
|
194
212
|
The repository was previously named `agents-deck`; the old URL redirects here,
|
|
195
213
|
so existing clones, links and bookmarks keep working.
|
|
196
214
|
|
|
197
|
-
## Requirements
|
|
198
|
-
|
|
199
|
-
- Node.js ≥ 18 — macOS, Linux and Windows
|
|
200
|
-
- Claude Code CLI or OpenAI Codex CLI (or both)
|
|
201
|
-
- Optional: [claude-swap](https://pypi.org/project/claude-swap/) for the Accounts panel; the deck can install it for you
|
|
202
|
-
|
|
203
215
|
## License
|
|
204
216
|
|
|
205
217
|
MIT © [Bargan Constantin](https://github.com/BarganConstantin)
|