agent-dag 1.33.7 → 1.33.9
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
|
@@ -1,50 +1,103 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# agents-deck
|
|
2
4
|
|
|
5
|
+
**A live canvas for your AI agents.** Watch Claude Code and OpenAI Codex fork subagents, call tools, and finish — all on one calm graph, in real time.
|
|
6
|
+
|
|
3
7
|
[](https://www.npmjs.com/package/agents-deck)
|
|
4
8
|
[](https://www.npmjs.com/package/agents-deck)
|
|
5
9
|
[](LICENSE)
|
|
6
10
|
[](https://nodejs.org)
|
|
11
|
+
[](#requirements)
|
|
7
12
|
|
|
8
|
-
|
|
13
|
+
```bash
|
|
14
|
+
npx ccdeck
|
|
15
|
+
```
|
|
9
16
|
|
|
10
17
|
|
|
11
18
|
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Why
|
|
24
|
+
|
|
25
|
+
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
|
+
|
|
27
|
+
agents-deck draws the tree instead. It is read-only, local, and needs no configuration: it registers a hook, listens, and paints.
|
|
28
|
+
|
|
12
29
|
## Quick start
|
|
13
30
|
|
|
14
31
|
```bash
|
|
15
|
-
npx agents-deck
|
|
32
|
+
npx ccdeck # or: npx agents-deck · npx agent-dag — same package
|
|
16
33
|
```
|
|
17
34
|
|
|
18
|
-
Opens **http://127.0.0.1:4317** and
|
|
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.
|
|
19
36
|
|
|
20
|
-
No config. No
|
|
37
|
+
No config file. No account. No telemetry. Nothing leaves your machine except one ~20-byte version check against the npm registry, which you can turn off.
|
|
21
38
|
|
|
22
|
-
##
|
|
39
|
+
## What you get
|
|
23
40
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
41
|
+
| | |
|
|
42
|
+
|---|---|
|
|
43
|
+
| **Live DAG** | Nodes are agents, edges are spawns and tool calls. In-flight edges animate, settled ones fade. |
|
|
44
|
+
| **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
|
+
| **Click to inspect** | Any node opens its prompt, tool calls, token usage and timing. |
|
|
46
|
+
| **Cost and quota, live** | Spend per model and per session, plus Claude and Codex quota windows as they refill. |
|
|
47
|
+
| **Survives restarts** | Events are appended to `~/.claude/agent-dag/events.jsonl` and replayed on open. |
|
|
48
|
+
| **Accounts without a terminal** | Sign a new Claude account in, share one to another machine, rename, reorder, remove — from the panel. |
|
|
49
|
+
| **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. |
|
|
50
|
+
| **Workspace scoping** | `--scope` for the current directory, `--workspace <path>` for any subtree. |
|
|
33
51
|
|
|
34
52
|
## How it works
|
|
35
53
|
|
|
36
|
-
Two capture paths feed one SSE stream
|
|
54
|
+
Two capture paths feed one SSE stream, which feeds one canvas.
|
|
37
55
|
|
|
38
|
-
**Claude Code** — on first run
|
|
56
|
+
**Claude Code** — on first run, agents-deck adds a hook entry to `~/.claude/settings.json` for every relevant event:
|
|
39
57
|
|
|
40
58
|
```
|
|
41
59
|
SessionStart · UserPromptSubmit · PreToolUse · PostToolUse · PostToolUseFailure
|
|
42
60
|
SubagentStart · SubagentStop · Stop · SessionEnd · Notification
|
|
43
61
|
```
|
|
44
62
|
|
|
45
|
-
Each
|
|
63
|
+
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.
|
|
64
|
+
|
|
65
|
+
**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.
|
|
66
|
+
|
|
67
|
+
## Accounts
|
|
68
|
+
|
|
69
|
+
The Accounts panel reads the store [claude-swap](https://pypi.org/project/claude-swap/) keeps, and can drive it.
|
|
70
|
+
|
|
71
|
+
**`+` → 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.
|
|
72
|
+
|
|
73
|
+
**`share`** on an account produces a `ccdeck1:…` blob to paste into another deck's **`+` → Paste a share**.
|
|
74
|
+
|
|
75
|
+
> [!WARNING]
|
|
76
|
+
> 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.
|
|
77
|
+
|
|
78
|
+
Renaming, reordering and removing are on the same row menu. Removal takes two clicks and cannot be undone.
|
|
79
|
+
|
|
80
|
+
## Updating
|
|
81
|
+
|
|
82
|
+
The deck checks npm for a newer release at most once an hour, plus once when it starts — the request is a ~20-byte GET to `registry.npmjs.org`. Click the version chip in the topbar to ask immediately.
|
|
83
|
+
|
|
84
|
+
What the banner offers depends on how this copy was installed:
|
|
85
|
+
|
|
86
|
+
| Installed as | Offer |
|
|
87
|
+
|---|---|
|
|
88
|
+
| global npm install | **Update now** — runs `npm install -g agents-deck@latest`, then restarts once nothing is running |
|
|
89
|
+
| `npx` | **Update & restart** — re-runs the spec through npx, which fetches a fresh copy and takes over the same port |
|
|
90
|
+
| git checkout | the command, because your working copy leads npm: `git pull && npm run build` |
|
|
91
|
+
| directory not writable | the command — a root-owned prefix is declined up front rather than failing inside npm |
|
|
92
|
+
| `AGENTS_DECK_NO_INSTALL=1` | the command only; you asked for no installs |
|
|
93
|
+
|
|
94
|
+
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.
|
|
95
|
+
|
|
96
|
+
### Restarting
|
|
97
|
+
|
|
98
|
+
agents-deck 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.
|
|
46
99
|
|
|
47
|
-
|
|
100
|
+
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.
|
|
48
101
|
|
|
49
102
|
## Options
|
|
50
103
|
|
|
@@ -67,73 +120,17 @@ agents-deck [options]
|
|
|
67
120
|
|
|
68
121
|
Environment:
|
|
69
122
|
|
|
70
|
-
|
|
71
|
-
AGENT_DAG_PORT Default port, same as -p
|
|
72
|
-
CODEX_HOME Override ~/.codex
|
|
73
|
-
AGENTS_DECK_NO_INSTALL=1 Never install or update claude-swap / ccusage,
|
|
74
|
-
and don't ask npm about newer agents-deck releases
|
|
75
|
-
AGENTS_DECK_NO_UPDATE_CHECK=1 Don't ask npm about releases, but keep everything else
|
|
76
|
-
AGENTS_DECK_NO_FRESHEN=1 Never nudge claude-swap to collect usage early
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
The update check is one ~20-byte GET to `registry.npmjs.org`, at most once a day.
|
|
80
|
-
Being told to restart after an upgrade is local only — no network involved — and
|
|
81
|
-
cannot be turned off, because a deck running superseded code is a bug you cannot
|
|
82
|
-
see any other way.
|
|
83
|
-
|
|
84
|
-
### Updating
|
|
85
|
-
|
|
86
|
-
`Update now` runs `npm install -g agents-deck@latest` and nothing else — the
|
|
87
|
-
argument vector is fixed in the server, not taken from the request. When it
|
|
88
|
-
finishes, the newer files on disk trigger the ordinary restart path below.
|
|
89
|
-
|
|
90
|
-
Nothing is ever installed unless you click. The button is replaced by the reason
|
|
91
|
-
when installing would be wrong:
|
|
92
|
-
|
|
93
|
-
| | |
|
|
123
|
+
| Variable | Effect |
|
|
94
124
|
|---|---|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
| `
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
### Accounts
|
|
104
|
-
|
|
105
|
-
`+` in the Accounts panel signs a new account in: the deck runs `claude auth login`,
|
|
106
|
-
shows you the link, takes the code the browser gives you, and hands the result to
|
|
107
|
-
`cswap add`. **The account you were using stays active** — signing in replaces the
|
|
108
|
-
live credentials, so the previous one is switched back the moment the new one is
|
|
109
|
-
recorded.
|
|
125
|
+
| `AGENT_DAG_PORT` | Default port, same as `-p` |
|
|
126
|
+
| `CODEX_HOME` | Override `~/.codex` |
|
|
127
|
+
| `AGENTS_DECK_NO_INSTALL=1` | Never install or update claude-swap / ccusage, and never ask npm about releases |
|
|
128
|
+
| `AGENTS_DECK_NO_UPDATE_CHECK=1` | Don't ask npm about releases, but keep everything else |
|
|
129
|
+
| `AGENTS_DECK_NO_FRESHEN=1` | Never nudge claude-swap to collect usage early |
|
|
130
|
+
| `AGENTS_DECK_CSWAP` | Full path to `cswap`, when it lives somewhere unusual |
|
|
131
|
+
| `AGENTS_DECK_CLAUDE` | Full path to the `claude` CLI |
|
|
110
132
|
|
|
111
|
-
|
|
112
|
-
logged, or sent anywhere else.
|
|
113
|
-
|
|
114
|
-
`share` on an account produces a `ccdeck1:…` blob to paste into another deck's
|
|
115
|
-
`+ → Paste a share`. **It carries that account's live login in the clear** —
|
|
116
|
-
claude-swap's export format has no encryption — so it expires ten minutes after it
|
|
117
|
-
is made and imports refuse it after that. Treat it like a password while it lives:
|
|
118
|
-
anything that reads your clipboard reads the account.
|
|
119
|
-
|
|
120
|
-
Renaming, reordering and removing are on the same row menu. Removal takes two
|
|
121
|
-
clicks and cannot be undone.
|
|
122
|
-
|
|
123
|
-
### Restarting
|
|
124
|
-
|
|
125
|
-
`agents-deck` runs as a two-process pair: a supervisor that owns nothing but the
|
|
126
|
-
lifecycle, and the deck itself. When newer code is found on disk, the deck exits
|
|
127
|
-
with code 75 and the supervisor brings it back **on the port it actually bound**,
|
|
128
|
-
which is not always the one it asked for. Ctrl+C, stdout and exit codes behave
|
|
129
|
-
exactly as before — same terminal, same process group.
|
|
130
|
-
|
|
131
|
-
It restarts on its own only once nothing has been running for 30 seconds: hook
|
|
132
|
-
events are fire-and-forget, so anything fired during the gap is lost. Turn that
|
|
133
|
-
off with the toggle in the banner and use the button instead; the preference is
|
|
134
|
-
per-browser. Under `--no-persist` restarting is refused outright, by the server
|
|
135
|
-
and not just by the UI — with no event log there is nothing to replay, and the
|
|
136
|
-
canvas would be gone.
|
|
133
|
+
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.
|
|
137
134
|
|
|
138
135
|
## Uninstall
|
|
139
136
|
|
|
@@ -141,31 +138,32 @@ canvas would be gone.
|
|
|
141
138
|
npx agents-deck --uninstall
|
|
142
139
|
```
|
|
143
140
|
|
|
144
|
-
Removes
|
|
145
|
-
|
|
146
|
-
## Legacy name
|
|
147
|
-
|
|
148
|
-
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.
|
|
149
|
-
|
|
150
|
-
```bash
|
|
151
|
-
# both work identically
|
|
152
|
-
npx agents-deck
|
|
153
|
-
npx agent-dag
|
|
154
|
-
```
|
|
141
|
+
Removes every hook entry agents-deck injected from `~/.claude/settings.json`, and `~/.codex/hooks.json` if present.
|
|
155
142
|
|
|
156
143
|
## Design
|
|
157
144
|
|
|
158
145
|
One canvas. No tabs. No kanban.
|
|
159
146
|
|
|
160
147
|
- Node = agent (root session or subagent)
|
|
161
|
-
- Edge = parent → child (spawn) or agent → tool (call)
|
|
162
|
-
- In-flight
|
|
163
|
-
- Click a node for full
|
|
148
|
+
- Edge = parent → child (spawn), or agent → tool (call)
|
|
149
|
+
- In-flight animates; settled dims
|
|
150
|
+
- Click a node for the full story
|
|
151
|
+
|
|
152
|
+
## Names
|
|
153
|
+
|
|
154
|
+
One package, three commands — use whichever you can remember.
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
npx ccdeck # short
|
|
158
|
+
npx agents-deck # canonical
|
|
159
|
+
npx agent-dag # the original name; existing installs and scripts keep working
|
|
160
|
+
```
|
|
164
161
|
|
|
165
162
|
## Requirements
|
|
166
163
|
|
|
167
|
-
- Node.js ≥ 18
|
|
164
|
+
- Node.js ≥ 18 — macOS, Linux and Windows
|
|
168
165
|
- Claude Code CLI or OpenAI Codex CLI (or both)
|
|
166
|
+
- Optional: [claude-swap](https://pypi.org/project/claude-swap/) for the Accounts panel; the deck can install it for you
|
|
169
167
|
|
|
170
168
|
## License
|
|
171
169
|
|