ccdeck 3.46.0 → 3.48.0

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.
Files changed (68) hide show
  1. package/README.md +99 -46
  2. package/bin/cli/commands.js +17 -9
  3. package/bin/cli/help.js +9 -4
  4. package/bin/cli/second-start.js +4 -2
  5. package/bin/cli/startup.js +26 -2
  6. package/bin/cli/tui.js +544 -0
  7. package/bin/deck.js +32 -1
  8. package/dist/web/assets/{BrowserWatchModal-CoX9FIUE.js → BrowserWatchModal-DuopT2Oa.js} +1 -1
  9. package/dist/web/assets/IntegrationModal-CszT-tts.js +7 -0
  10. package/dist/web/assets/{RadioPanel-biw_BbZq.js → RadioPanel-Cn3WvPUG.js} +1 -1
  11. package/dist/web/assets/TrafficRadar-DZA8XSi7.js +8 -0
  12. package/dist/web/assets/UsageHistoryModal-MgZJLXbF.js +1 -0
  13. package/dist/web/assets/app-DjlHxWHg.css +1 -0
  14. package/dist/web/assets/app-F1xryJpn.js +321 -0
  15. package/dist/web/assets/claude-settings-index-1Qg1AUda.js +1 -0
  16. package/dist/web/assets/{index-DmENqVdt.js → index-BK9avF1k.js} +1 -1
  17. package/dist/web/index.html +3 -3
  18. package/package.json +1 -1
  19. package/release-notes.json +58 -2
  20. package/src/server/args.mjs +1 -0
  21. package/src/server/ccusage-install.mjs +58 -1
  22. package/src/server/ccusage-registry.mjs +289 -0
  23. package/src/server/ccusage-runner.mjs +9 -2
  24. package/src/server/claude-accounts.mjs +21 -0
  25. package/src/server/claude-login.mjs +21 -3
  26. package/src/server/claude-settings-catalog.d.mts +37 -0
  27. package/src/server/claude-settings-catalog.mjs +169 -0
  28. package/src/server/claude-settings-docs.mjs +109 -0
  29. package/src/server/claude-settings-index.json +251 -0
  30. package/src/server/claude-settings-routes.mjs +46 -0
  31. package/src/server/claude-settings.mjs +406 -0
  32. package/src/server/cli-arrival.mjs +64 -0
  33. package/src/server/cli-lines.mjs +46 -0
  34. package/src/server/gpu-metrics.mjs +78 -0
  35. package/src/server/index.mjs +18 -2
  36. package/src/server/integrations/jira-move.mjs +239 -0
  37. package/src/server/integrations/jira.mjs +30 -8
  38. package/src/server/integrations/proxy.mjs +14 -6
  39. package/src/server/integrations/routes.mjs +25 -9
  40. package/src/server/quota-close-watch.mjs +81 -0
  41. package/src/server/quota-closes.mjs +181 -0
  42. package/src/server/quota-history.mjs +8 -1
  43. package/src/server/quota-shape.mjs +12 -0
  44. package/src/server/quota.mjs +28 -1
  45. package/src/server/request-gates.mjs +3 -1
  46. package/src/server/system-metrics.mjs +4 -0
  47. package/src/server/term.mjs +14 -5
  48. package/src/server/tool-audit-operations.mjs +30 -10
  49. package/src/server/tool-audit-report.mjs +79 -7
  50. package/src/server/tool-audit-routes.mjs +1 -1
  51. package/src/server/tool-audit-skills.mjs +8 -3
  52. package/src/server/tool-audit.mjs +55 -5
  53. package/src/server/traffic-radar-capture.mjs +3 -3
  54. package/src/server/traffic-radar-config.mjs +10 -3
  55. package/src/server/traffic-radar-monitor.mjs +8 -5
  56. package/src/server/traffic-radar-permission.mjs +162 -0
  57. package/src/server/traffic-radar-platform.mjs +9 -3
  58. package/src/server/traffic-radar-routes.mjs +8 -18
  59. package/src/server/traffic-radar-service.mjs +76 -92
  60. package/src/server/tui-screen.mjs +110 -0
  61. package/src/server/tui-view.mjs +1072 -0
  62. package/src/server/usage-routes.mjs +14 -2
  63. package/src/server/way-back.mjs +27 -0
  64. package/dist/web/assets/IntegrationModal-B1ypkK-E.js +0 -5
  65. package/dist/web/assets/TrafficRadar-nhtFoYVv.js +0 -8
  66. package/dist/web/assets/UsageHistoryModal-Bd-JRAa4.js +0 -1
  67. package/dist/web/assets/app-BlRY6EME.css +0 -1
  68. package/dist/web/assets/app-DhGvSH7o.js +0 -319
package/README.md CHANGED
@@ -33,7 +33,7 @@ Or the desktop app, with the waiting count in your menu bar: **[macOS](https://g
33
33
 
34
34
  which Claude Code session is blocked on you · tool calls · one canvas · cost · quota · local · sessions never leave
35
35
 
36
- [ccdeck.dev](https://ccdeck.dev) · [Guides](https://ccdeck.dev/guides/) · [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)
36
+ [ccdeck.dev](https://ccdeck.dev) · [Guides](https://ccdeck.dev/guides/) · [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) · [Support](#support-ccdeck) · [FAQ](#questions-people-ask)
37
37
 
38
38
 
39
39
  </div>
@@ -130,7 +130,7 @@ The panels open from the window's edges: the session list and the Claude account
130
130
 
131
131
  Two notes can appear at the bottom of the canvas: **Undo**, for a few seconds after `R` or the re-arrange button lays the canvas out again — `Ctrl+Z` (`⌘Z` on a Mac) does the same — and **Resume**, which turns auto-fit back on after you have panned or zoomed.
132
132
 
133
- Everything the page lets you set apart from the music — the theme, the text size and spacing, the character on the canvas, the single-key shortcuts, the sounds and notifications, how long Tool activity keeps its history — is in **Settings**, behind the gear at the right of the topbar, or `Cmd+,` (`Ctrl+,` on Windows and Linux); the music is in **Radio**, below. Changes apply immediately except startup recovery, which applies at the next server start. **Settings › Appearance** holds twelve color themes, Gruvbox Dark, Gruvbox Light and Gruvbox Material the newest — a fresh install starts in Rider Black rather than following your system's light or dark setting, a theme you picked stays, `T` steps through all twelve, and the deck fades from one theme to the next over 180 ms, or switches at once when your system asks for reduced motion — and the character: Deck companion, Fox or Penguin, with a switch to hide it. **Settings › Text & density** has five text sizes — Smallest, Smaller, Default, Larger and Largest, 11, 12, 13, 15 and 17 px for body text — and five densities for the spacing in lists, panels and controls: Tightest, Tighter, Compact, Default and Comfortable, at 30%, 50%, 70%, 100% and 140% of the designed spacing. Both are kept in this browser, and neither is a zoom: your browser's zoom and the canvas's stay where they were, the panels widen for larger text, and the cards on the canvas follow it. **Reset to defaults** puts both back. The sounds and how loud each tone is are in **Settings › Sounds**, which `V` opens straight away; `M` turns sounds off or on from anywhere. `?` lists every key. If you use voice control or press letters by accident, turn off **Single-key shortcuts** in **Settings › Keyboard**, which also lists every shortcut: letters, `?` and Space then do nothing, while `Cmd+,`, `Esc`, `Enter`, `Tab`, `Delete` and the arrows keep working.
133
+ Everything the page lets you set apart from the music — the theme, the text size and spacing, the character on the canvas, the single-key shortcuts, the sounds and notifications, how long Tool activity keeps its history — is in **Settings**, behind the gear at the right of the topbar, or `Cmd+,` (`Ctrl+,` on Windows and Linux); the music is in **Radio**, below. Changes apply immediately except startup recovery, which applies at the next server start. **Settings › Appearance** holds twelve color themes, Gruvbox Dark, Gruvbox Light and Gruvbox Material the newest — a fresh install starts in Rider Black rather than following your system's light or dark setting, a theme you picked stays, `T` steps through all twelve, from inside any dialog too unless you are typing in a field, and the deck fades from one theme to the next over 180 ms, or switches at once when your system asks for reduced motion — and the character: Deck companion, Fox or Penguin, with a switch to hide it. **Settings › Text & density** has five text sizes — Smallest, Smaller, Default, Larger and Largest, 11, 12, 13, 15 and 17 px for body text — and five densities for the spacing in lists, panels and controls: Tightest, Tighter, Compact, Default and Comfortable, at 30%, 50%, 70%, 100% and 140% of the designed spacing. Both are kept in this browser, and neither is a zoom: your browser's zoom and the canvas's stay where they were, the panels widen for larger text, and the cards on the canvas follow it. **Reset to defaults** puts both back. The sounds and how loud each tone is are in **Settings › Sounds**, which `V` opens straight away; `M` turns sounds off or on from anywhere. `?` lists every key. If you use voice control or press letters by accident, turn off **Single-key shortcuts** in **Settings › Keyboard**, which also lists every shortcut: letters, `?` and Space then do nothing, while `Cmd+,`, `Esc`, `Enter`, `Tab`, `Delete` and the arrows keep working. **Settings › Claude Code**, there when Claude Code is, changes twelve of Claude Code's own settings in your `settings.json` — whether your sessions take messages from and can find each other, auto memory, automatic compaction, how long conversations are kept, checkpoints for rewind, the Co-Authored-By credit, the terminal's tips, turn duration and motion, and the update channel. It shows only what it read: a value that comes from somewhere else, such as an environment variable or your organization, is said under its row, and a `settings.json` it cannot read shows no values, only why. Below them it lists every setting Claude Code documents, the ones your file sets first, each with a link to Claude Code's reference (see [What it touches](#what-it-touches)).
134
134
 
135
135
  **Radio**, on the right sidebar beside the character (in **More** on a phone), opens a responsive Radio Explorer with a large interactive map, station discovery and a persistent player. Filter by country, sound or language, save favorites, return to recent stations, or choose **Surprise me**. Your existing Claude FM, Lofi Girl and custom streams are under **Your streams**. Select a station to inspect it, then press Play to listen; closing Radio or hiding the character keeps it playing. Favorites, history and the last catalogue are saved in this browser. Control music directly in Radio Explorer; character settings are in **Settings › Appearance**.
136
136
 
@@ -208,25 +208,43 @@ phone. Three views keep configuration, observed traffic and saved files separate
208
208
  lines; the first 200 matching rows are displayed. File contents alone do not
209
209
  prove that a record was sent.
210
210
 
211
- Choose all configured IPv4 destinations, one destination or a custom IPv4
212
- address and port, then press **Start monitoring** once. ccdeck runs the capture
213
- itself, as the user running ccdeck: there is no command to paste into a
214
- Terminal or PowerShell tab, and no repeated ten-minute activation. It retries
215
- after a capture-process failure or network interface change, and remembers the
216
- enabled destinations across server restarts. What that user needs:
217
-
218
- - **macOS** — the `tcpdump` macOS includes, and permission to capture, which
219
- Wireshark’s official
220
- [ChmodBPF permission helper](https://www.wireshark.org/docs/wsug_html_chunked/ChBuildInstallOSXInstall.html)
221
- grants.
222
- - **Linux** — `tcpdump`, and packet capture permission for the user running
223
- ccdeck.
211
+ Radar monitors by itself, always: there is no Start, no Stop and no
212
+ destination to pick. ccdeck finds Claude Code's collector — from Claude's
213
+ settings, a running session's environment (a collector named by host is looked
214
+ up), the collectors it found before, or an active IPv4 OTLP/gRPC connection on
215
+ port 4317 — and runs the capture itself, as the user running ccdeck, with no
216
+ command to paste into a Terminal or PowerShell tab. It looks every five seconds
217
+ while Radar is open and about once a minute while it is closed, retries after a
218
+ capture-process failure or network interface change, and remembers the
219
+ collectors it found across server restarts.
220
+
221
+ Packet capture needs an administrator once. When it is missing, Monitor shows
222
+ **Allow packet capture once**, says what will change, and **Allow capture…**
223
+ opens the system's own password prompt:
224
+
225
+ - **macOS** — ccdeck adds a small helper of its own,
226
+ `/Library/LaunchDaemons/dev.ccdeck.chmodbpf.plist`, which does at every
227
+ startup what Wireshark's
228
+ [ChmodBPF](https://www.wireshark.org/docs/wsug_html_chunked/ChBuildInstallOSXInstall.html)
229
+ does: it lets the `access_bpf` group read the packet-capture devices, and
230
+ your user joins that group. This startup's devices are handed to you
231
+ directly, so capture starts without logging in again. A Mac with Wireshark's
232
+ ChmodBPF already set up needs nothing.
233
+ - **Linux** — ccdeck installs `tcpdump` with your package manager (apt, dnf,
234
+ zypper or pacman) when it is missing, then lets it capture
235
+ (`cap_net_raw,cap_net_admin`) and limits running it to your own group. A
236
+ `tcpdump` update replaces the file and drops this; Radar then asks again. The
237
+ desktop app's `.deb` recommends `tcpdump`, so apt installs it with the app.
224
238
  - **Windows** — [Wireshark with Npcap](https://www.wireshark.org/download.html)
225
- (ccdeck runs its `dumpcap`), with capture access for that user.
239
+ (ccdeck runs its `dumpcap`), which you install yourself: Npcap's free edition
240
+ may not be installed by another program.
226
241
 
227
- ccdeck stays unprivileged: it does not install drivers or change permissions. A
228
- blocked capture shows its permission or reconnecting state rather than claiming
229
- to be listening, and capture starts by itself once access is granted.
242
+ Where no password prompt can open — a deck reached over SSH, a Linux desktop
243
+ with no polkit agent — Radar writes the same setup script to
244
+ `~/.agents-deck/radar-capture-setup.sh` and shows the one `sudo` command that
245
+ runs it. Nothing else is changed without that password. A blocked capture shows
246
+ its permission or reconnecting state rather than claiming to be listening, and
247
+ capture starts by itself as soon as access is granted.
230
248
 
231
249
  Each destination gets its own decoder, up to eight destinations per capture.
232
250
  Linux captures routed and loopback traffic through `any`; macOS resolves the
@@ -246,27 +264,21 @@ success and rejection. Acceptance does not prove final backend storage. Contents
246
264
  come from captured traffic, not local conversation transcripts. Messages remain
247
265
  in local server memory for 24 hours, up to 2,000 exports and a 32 MiB encoded
248
266
  payload budget; unreadable observations are capped at 2,000 for 24 hours. The
249
- oldest entries are removed when a limit is reached. Stop/Start and closing the
250
- modal preserve history; restarting ccdeck removes it.
267
+ oldest entries are removed when a limit is reached. Closing the modal preserves
268
+ history; restarting ccdeck removes it.
251
269
  No capture file is written. **Pause list** pauses display, not capture or retention;
252
270
  **Clear messages** clears exports and unreadable observations.
253
271
 
254
- Monitoring continues until **Stop monitoring** or until ccdeck exits. An enabled
255
- monitor resumes when ccdeck next starts on the same port; Stop is remembered too.
256
- Closing the modal or browser does not stop capture. Only the opt-in and collector
257
- destinations are saved, never packet contents, tokens or decoded messages.
258
- Capture contents are available through the local loopback UI, not LAN endpoints.
259
- Local clients of the same server share its capture.
260
-
261
- **Automatic monitoring** is off unless you turn it on in **Settings → Radar →
262
- Monitor automatically**. On, ccdeck finds the collector itself — from Claude's
263
- settings, a monitor you started, or an active IPv4 OTLP/gRPC connection on port
264
- 4317 — monitors it without Radar open, and retries every five seconds while
265
- none is available; Monitor then hides Start and the destination picker. Off
266
- stops it, and nothing is looked for or retried.
267
-
268
- Configuration and connection sampling runs only while Radar is open and the
269
- browser page is visible. A connection does not prove an upload, and absence of
272
+ Monitoring continues while ccdeck runs and starts again with it;
273
+ `AGENTS_DECK_NO_RADAR=1` keeps a deck from looking for a collector or capturing
274
+ at all. Closing the modal or browser does not stop capture. Only the collector destinations are
275
+ saved, never packet contents, tokens or decoded messages. Capture contents are
276
+ available through the local loopback UI, not LAN endpoints. Local clients of
277
+ the same server share its capture.
278
+
279
+ Configuration and connection sampling runs every five seconds while Radar is
280
+ open and the browser page is visible, and about once a minute in the
281
+ background, to find the collector. A connection does not prove an upload, and absence of
270
282
  observed traffic does not mean telemetry is disabled. Native-process sampling
271
283
  can miss short-lived connections and Node wrappers. Windows samples native
272
284
  Claude processes with PowerShell; Linux uses process names and owned `/proc`
@@ -282,6 +294,17 @@ capture permissions and development dependencies. See the
282
294
  for Npcap and binary pcap output.
283
295
 
284
296
 
297
+ ### NVIDIA GPU readings
298
+
299
+ On Linux and Windows, the Machine panel can show each NVIDIA GPU's utilization,
300
+ allocated and total video memory, temperature and power. This requires the
301
+ NVIDIA driver's `nvidia-smi` command on `PATH`; ccdeck installs nothing.
302
+ Unavailable driver fields say “Unavailable”, and devices without a current
303
+ reading are hidden. Successful readings refresh every five seconds; a failed
304
+ probe clears the reading and retries after a minute. GPU history is not recorded.
305
+ These are readings from this machine, not the GPUs running a cloud model.
306
+ Existing Thermal sensors remain separate.
307
+
285
308
  ### Temperature, per machine
286
309
 
287
310
  The machine panel shows a **Thermal** section only where the machine actually answers, and it never invents a reading — no sensor means no row.
@@ -345,7 +368,9 @@ Opening Radio asks the public [Radio Browser](https://www.radio-browser.info/) d
345
368
 
346
369
  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, because Browser Watch is on unless you switch it off; that is its own section below, because it is the one thing here that is about you rather than about an agent.
347
370
 
348
- Telemetry Radar's flag switches write to `~/.claude/settings.json` too: each puts the flag you set — `CLAUDE_CODE_ENABLE_TELEMETRY`, `OTEL_LOG_USER_PROMPTS` and the other telemetry and content flags Radar lists — in that file's `env` block, as `"1"` or `"0"`. Switching a flag off writes `"0"` rather than removing it, and `--uninstall`, which removes ccdeck's hook entries, leaves these values as you set them. Starting Radar's monitoring writes `~/.agents-deck/radar-monitor-<port>.json`: the opt-in and the destinations a deck on that port resumes, never packets or decoded messages; turning on automatic monitoring writes `radar-settings-<port>.json` beside it, the switch and the collectors it found. And the quota readings the deck takes are kept in `quota-history.json`, in its data directory (see [Uninstall](#uninstall)), for 35 days and up to 2 MB, under a hash of the account rather than its address, for the Usage panel's quota history. What each Claude organization's settings turn on for telemetry is kept in `org-telemetry.json`, in the same data directory: per organization, its name, the level, the content flags that are on, the collector's scheme, host and port, and when the deck read them, never a path, a header or a credential.
371
+ Telemetry Radar's flag switches write to `~/.claude/settings.json` too: each puts the flag you set — `CLAUDE_CODE_ENABLE_TELEMETRY`, `OTEL_LOG_USER_PROMPTS` and the other telemetry and content flags Radar lists — in that file's `env` block, as `"1"` or `"0"`. Switching a flag off writes `"0"` rather than removing it, and `--uninstall`, which removes ccdeck's hook entries, leaves these values as you set them. Radar's monitoring writes `~/.agents-deck/radar-monitor-<port>.json`, the destinations a deck on that port resumes, never packets or decoded messages, and `radar-settings-<port>.json` beside it, the collectors it found. And the quota readings the deck takes are kept in `quota-history.json`, in its data directory (see [Uninstall](#uninstall)), for 35 days and up to 2 MB, under a hash of the account rather than its address, for the Usage panel's quota history. What each Claude organization's settings turn on for telemetry is kept in `org-telemetry.json`, in the same data directory: per organization, its name, the level, the content flags that are on, the collector's scheme, host and port, and when the deck read them, never a path, a header or a credential.
372
+
373
+ **Settings › Claude Code** writes `~/.claude/settings.json` only when you change one of its rows, and only that row's key: going back to Claude Code's default removes the key, and **Let sessions find each other** adds or removes the bare `ListAgents` entry in `permissions.deny` and nothing else in that list. Before each change it keeps the file as it was as `claude-settings.before-change.json` in its data directory, readable only by you. It never writes managed, organization or project settings, nor `~/.claude.json`. A row your organization decides, or one that needs a newer Claude Code than the one it finds, cannot be changed there. The page sees only on/off values, numbers and documented choices from the file; `env` blocks, helper commands and tokens show as "set". `--uninstall` leaves what you set there.
349
374
 
350
375
  Tool activity keeps its history in `tool-audit/`, in the same data directory: a file a day with a line per tool call — Claude Code or Codex, when it started and ended, whether it failed, and the tool's name or, for a shell command, its operation (`git push`, `npm run build`) — with a line per skill used, holding the skill's name, the session it ran in and the name of its project folder, and a `settings.json` holding how long to keep it, when it started counting, and a random id for this device that nothing sends anywhere. The rest of a command line, the tool's or the skill's arguments and output, and paths are not saved, nor a tool call's session id, and nothing in the folder leaves the machine. It keeps 90 days unless you pick 30 or 60 under **Keep history** in **Settings › Data › Tool history**, which also shows the space it takes and has **Clear history…**; older days are deleted as they fall out. `--no-persist` does not stop it — that flag is about the events log — and `--uninstall` leaves it, `--purge` too (see [Uninstall](#uninstall)).
351
376
 
@@ -353,6 +378,8 @@ What does go out is short and ordinary: a ~20-byte version check against the npm
353
378
 
354
379
  **Settings › Integrations** keeps each connection in `integrations/`, in the deck's data directory: `integrations.json` holds its name, its address and the account it signed in as, and `integrations-secrets.json`, which only you can read, holds its token. The token goes to that connection's own Jira and nowhere else — for a scoped Atlassian Cloud token, `api.atlassian.com` as well — never to the page, never into a report or a log, and never to another deck on the local network. The Jira panel reads from Jira only while it is open: when you open a board read more than five minutes ago, or press Refresh. What it reads stays in memory; only the panel's layout and filters are remembered, in this browser. Avatars and issue icons come through the deck, which sends the token only to Jira's own address. Disconnecting deletes the connection and its token.
355
380
 
381
+ On a Scrum board ordered by Rank, you can drag Jira issues to reorder them or move them between active/future sprints and the backlog. Ctrl/Cmd+click toggles individual selections; Shift+click selects a visible range, and Space toggles the focused issue. Drag a selected issue to move the whole selection, or use **Move selected** (up to 50 unfinished top-level issues). **Move** provides the same action for keyboard and touch; Alt+M opens it from a focused issue. Filtering or folding rows removes hidden issues from the selection. These actions save changes in Jira using your account’s permissions; browsing does not write. Subtasks, epics and completed issues cannot be moved here, and moving does not change workflow status. Positions refer to the loaded issues, so hidden or unloaded issues keep their relative rank. A failed or interrupted move refreshes the board; check the result before trying again because Jira may have saved part of the action.
382
+
356
383
  A GitHub or GitLab connection is kept the same way, and its token goes only to that forge's API — GitHub's at `api.github.com`, GitLab's at the address you typed (`gitlab.com` unless you set your own). The deck reads that forge only while its panel is open: opening the panel asks again for what is more than two minutes old, **Refresh** asks for the rest, and nothing is polled in the background. It only reads: it never comments, approves, merges, re-runs a job or touches a branch, and the token help asks for read access and nothing more (`repo` and `read:org`, or read-only fine-grained permissions, on GitHub; `read_api` on GitLab). A failed job's log is read only when you press **Show log**, and only its last lines. What it reads stays in the open page and is not written to disk; the project, tab and filters you last chose are remembered in this browser. Avatars and the pictures in a description reach the page through the deck, which fetches them only from the forge's own image hosts — GitHub's `githubusercontent.com` hosts without the token, your GitLab instance, or Gravatar without the token — and passes on PNG, JPEG, GIF and WebP only. Links in the panel open the forge in your browser.
357
384
 
358
385
  Local network, Claude accounts, Usage and the empty canvas each carry a small **Watch · 30 s** link to their 30-second video on [ccdeck.dev](https://ccdeck.dev/guides/). Opening one is your click, in your own browser; the deck itself sends nothing for it.
@@ -428,15 +455,20 @@ ccdeck switch pick from a list (arrows, Enter; Esc cancels)
428
455
  ccdeck usage the active account's limits, every lane
429
456
  ccdeck sessions what each session is doing, the ones waiting on you first
430
457
  ccdeck open the deck in your browser — over SSH, the line that opens it on yours
458
+ ccdeck tui all of the above on one screen that stays up
431
459
  ```
432
460
 
461
+ **`ccdeck tui`** keeps the accounts and the sessions waiting on you on one full screen, read again every few seconds. Move with the arrows (or `j` / `k`, or a slot's number), **Enter** switches to the selected account, **b** selects the one Auto-switch would pick, **a** turns Auto-switch on or off, **r** reads the usage again, **?** lists the keys and **q** leaves with your terminal as it was. With no deck running it reads claude-swap's store and **d** starts one in the background. It fits from 40×12 up, sets the selected account's detail beside the waiting sessions from 120 columns, follows `NO_COLOR`, and draws in ASCII on a console that cannot show its lines.
462
+
463
+ **Adding an account over SSH**: **+** signs one in, and **Enter** on an account whose login has expired signs it in again, keeping its slot, alias and history. The screen shows a sign-in link to open in any browser; once you approve, the page there shows a code, which you paste back into the terminal. If that browser runs on the machine itself, the sign-in finishes without the code. The account you are using stays active throughout. Sign-in goes through the deck, so it needs one running.
464
+
433
465
  `swap` and `use` are other names for `switch`, `ls` for `accounts` and `ps` for `sessions`; `status`, `stop` and `logs` are `--status`, `--stop` and `--logs`. `ccdeck swap 1 2` does not exchange two slots the way claude-swap's `cswap swap` does — it says so and points you there.
434
466
 
435
467
  **The commands ask the deck that is running.** A switch from the terminal goes through the same route as **Switch** on a row, so it waits for the same lock as the panel, Auto-switch and a sign-in in flight, the panel shows it at once, and it lands in the Projects report's history. With no deck running, `accounts`, `switch` and `usage` read and drive claude-swap's store directly; `sessions` and `open` need a deck, since sessions are what a deck watches. After a switch, the command says how many running Claude sessions move with it — all of them, from their next message.
436
468
 
437
- **Over SSH**, `ccdeck open` prints the line to run on your own computer, `ssh -N -o ExitOnForwardFailure=yes -L 14317:127.0.0.1:4317 you@that-machine` (with `-p` when sshd is not on 22), and the deck then opens at `http://127.0.0.1:14317` in your own browser. Your end is not 4317, so it cannot land on a deck of your own. The deck still listens only on 127.0.0.1; the tunnel is your SSH connection.
469
+ **Over SSH**, `ccdeck open` prints the line to run on your own computer, `ssh -N -o ExitOnForwardFailure=yes -L 14317:127.0.0.1:4317 you@that-machine` (with `-p` when sshd is not on 22), and the deck then opens at `http://127.0.0.1:14317` in your own browser. Your end is not 4317, so it cannot land on a deck of your own. The deck still listens only on 127.0.0.1; the tunnel is your SSH connection. To stay in the terminal instead, `ccdeck tui` shows the accounts there, and a start over SSH says so.
438
470
 
439
- **For scripts**, every command takes `--json` — one object on stdout with `schemaVersion` and `ok` — and `--port <n>` to name a deck. Nothing prompts without a terminal: `ccdeck switch` with no account named and no terminal is an error, not a wait. Exit codes are 0 done, 1 failed, 2 the command line was wrong (an account nothing matches, a misspelled command), and 3 no deck is running.
471
+ **For scripts**, every command but `tui` takes `--json` — one object on stdout with `schemaVersion` and `ok` — and every one takes `--port <n>` to name a deck. Nothing prompts without a terminal: `ccdeck switch` with no account named and no terminal is an error, not a wait. Exit codes are 0 done, 1 failed, 2 the command line was wrong (an account nothing matches, a misspelled command), and 3 no deck is running.
440
472
 
441
473
  A misspelled command is refused — `ccdeck acounts` suggests `accounts` and starts nothing — so a typo over SSH never leaves a deck behind.
442
474
 
@@ -596,7 +628,9 @@ installers put it), or when its config dir carries traces of having been used;
596
628
  Codex counts as present when `~/.codex/` exists. On a machine with only one of
597
629
  them, the other one's hooks, installs and panels are skipped rather than shown
598
630
  empty — the boot banner says which way it went, and `--claude` / `--codex`
599
- override it if the guess is wrong.
631
+ override it if the guess is wrong. A CLI installed while the deck is running is
632
+ noticed within about fifteen seconds, and the deck restarts itself to serve it
633
+ (unless you started it with `--no-claude` / `--no-codex`).
600
634
 
601
635
  `--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. That is not a way to keep a machine-wide deck and one scoped to `~/proj` side by side: in one Claude config directory the second start stops the first and takes its place, as above. The filter 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.
602
636
 
@@ -629,7 +663,7 @@ Environment:
629
663
 
630
664
  `AGENTS_DECK_NO_MUSIC=1` turns Radio off: no station directory requests, no play reports and no playback. It is not in the table because, unlike the variables above, the login item does not carry it and the desktop app does not take it from your login shell: it holds for a deck started where it is set.
631
665
 
632
- 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.
666
+ 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`. On a machine with no npm at all, such as the desktop app on a computer without Node, the deck downloads its copy from the npm registry itself, checked against the sha512 the registry publishes, and there is no npx step. 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.
633
667
 
634
668
  Open **Usage → By session** and select a Claude Code or Codex row to inspect its whole-session cost estimate, input/output and cache tokens, model breakdown and activity dates. This also works for historical sessions no longer on the canvas. The whole session may extend beyond the period selected in Usage; logs missing from this machine cannot be recovered by the inspector. Its token breakdown also shows **Cached input reuse**, the share of the session's measured input that was read from cache.
635
669
 
@@ -667,10 +701,23 @@ platform's **data** directory, and the platform's **log** directory.
667
701
  `prefs.json` is the one to delete deliberately: it holds this deck's **Local
668
702
  network private key**, the one every deck you paired with has pinned. Leaving it
669
703
  behind leaves that identity on the machine. (`~/.agents-deck/` holds the managed
670
- tools and the deck's records about them, `radar-monitor-<port>.json` once
671
- Telemetry Radar has monitored — the destinations it resumes — and
672
- `radar-settings-<port>.json` once its automatic monitoring has been switched,
673
- but no key.)
704
+ tools and the deck's records about them, `radar-monitor-<port>.json` and
705
+ `radar-settings-<port>.json` once Telemetry Radar has monitored — the
706
+ destinations it resumes and the collectors it found — but no key.)
707
+
708
+ **Allow capture** changed the system, so undoing it takes an administrator too.
709
+ On macOS:
710
+
711
+ ```bash
712
+ sudo launchctl bootout system/dev.ccdeck.chmodbpf
713
+ sudo rm /Library/LaunchDaemons/dev.ccdeck.chmodbpf.plist "/Library/Application Support/ccdeck/ccdeck-chmodbpf"
714
+ ```
715
+
716
+ On Linux, give `tcpdump` back its packaged state:
717
+
718
+ ```bash
719
+ t=$(readlink -f "$(command -v tcpdump)"); sudo setcap -r "$t"; sudo chgrp root "$t"; sudo chmod 0755 "$t"
720
+ ```
674
721
 
675
722
  The data directory also holds Tool activity's `tool-audit/` folder — up to 90
676
723
  days of which tools and commands your agents ran, and how long they took — and
@@ -800,6 +847,12 @@ and starts again when you log in. `ccdeck --stop` ends it.
800
847
  - 💬 **Questions & ideas** — [GitHub Discussions](https://github.com/BarganConstantin/ccdeck/discussions)
801
848
  - 🐛 **Bugs & feature requests** — [GitHub Issues](https://github.com/BarganConstantin/ccdeck/issues)
802
849
 
850
+ ## Support ccdeck
851
+
852
+ ccdeck is free, open source, and maintained independently. If it helps you see which coding agent needs attention instead of checking terminal after terminal, [consider sponsoring its development](https://github.com/sponsors/BarganConstantin).
853
+
854
+ Sponsorships support bug fixes, documentation, and testing across macOS, Linux, and Windows. They're entirely optional — no sponsorship or payment is needed to use ccdeck.
855
+
803
856
  ## License
804
857
 
805
858
  ccdeck is licensed under the **GNU Affero General Public License v3.0 only (AGPL-3.0-only)**.
@@ -14,17 +14,22 @@
14
14
  // Every command takes `--json`: one object on stdout, `schemaVersion` first,
15
15
  // `ok` beside it, the human sentences left off. Exit codes are part of the
16
16
  // contract — see EXIT.
17
+ //
18
+ // `ccdeck tui` (bin/cli/tui.js) is the same commands kept on screen: it asks
19
+ // the deck through the helpers exported here, so a switch from it takes the
20
+ // route, the lock and the refusals a `ccdeck switch` does.
17
21
  import { spawn } from "node:child_process";
18
22
  import { hostname, userInfo } from "node:os";
19
23
  import { join } from "node:path";
20
24
  import { pathToFileURL } from "node:url";
21
25
  import { COMMANDS, isPortValue } from "../../src/server/args.mjs";
22
26
  import { isWsl } from "../../src/server/open-url.mjs";
27
+ import { overSsh } from "../../src/server/term.mjs";
23
28
  import { COMMAND, PKG_ROOT, PKG_VERSION } from "./package.js";
24
29
  import { G, P, UNICODE, cols } from "./screen.js";
25
30
  import { oneShotVoice, reportFlagRows } from "./one-shot.js";
26
31
 
27
- const load = (rel) => import(pathToFileURL(join(PKG_ROOT, rel)).href);
32
+ export const load = (rel) => import(pathToFileURL(join(PKG_ROOT, rel)).href);
28
33
 
29
34
  /** The picker, loaded only when somebody is about to be shown it. */
30
35
  async function pickAccount(rows, opts) {
@@ -63,6 +68,9 @@ export async function runCommand(flags) {
63
68
  case "usage": return usageCommand(flags, out);
64
69
  case "sessions": return sessionsCommand(flags, out);
65
70
  case "open": return openCommand(flags, out);
71
+ // The one that stays: a full screen over the same deck, until q. Loaded
72
+ // only when asked for, like the picker.
73
+ case "tui": return (await import("./tui.js")).runTui(flags, out);
66
74
  default: return out.fail(EXIT.USAGE, "unknown_command", unknownCommandText(String(flags.command)));
67
75
  }
68
76
  }
@@ -143,13 +151,13 @@ async function deckFor(flags) {
143
151
 
144
152
  /** Decks whose process is alive although none answered the challenge — slow
145
153
  * at boot, in a pause, on a loaded machine. A switch here would race theirs. */
146
- async function silentDecks(port) {
154
+ export async function silentDecks(port) {
147
155
  const { registeredDecks } = await load("src/server/running-deck.mjs");
148
156
  const decks = await registeredDecks().catch(() => []);
149
157
  return port == null ? decks : decks.filter(d => d.port === port);
150
158
  }
151
159
 
152
- async function ask(deck, opts) {
160
+ export async function ask(deck, opts) {
153
161
  const { askDeck } = await load("src/server/deck-client.mjs");
154
162
  return askDeck(deck, opts);
155
163
  }
@@ -182,7 +190,7 @@ function localNote(silent) {
182
190
  }
183
191
 
184
192
  /** What to say about a deck that did not answer as expected. */
185
- function deckTrouble(deck, r) {
193
+ export function deckTrouble(deck, r) {
186
194
  if (r.status === 404) {
187
195
  return `the deck on ${deck.port} (v${deck.version || "?"}) predates this command ${G.dash} \`${COMMAND} --new\` restarts it on v${PKG_VERSION}`;
188
196
  }
@@ -191,7 +199,7 @@ function deckTrouble(deck, r) {
191
199
  }
192
200
 
193
201
  /** Why a roster has nothing in it, in the words a person needs next. */
194
- function rosterTrouble(roster) {
202
+ export function rosterTrouble(roster) {
195
203
  switch (roster?.reason) {
196
204
  case "no_accounts":
197
205
  return `no Claude accounts yet ${G.dash} sign in with \`claude\`, then add it from the deck's Accounts panel or with \`cswap add\``;
@@ -403,7 +411,7 @@ const BEST_PICKS = Object.freeze({
403
411
  * read its panel makes, with its token. With no deck, read here. A deck that
404
412
  * predates the rules (404) or cannot say has none to follow.
405
413
  */
406
- async function autoRules(deck, accounts) {
414
+ export async function autoRules(deck, accounts) {
407
415
  const { bestRules } = await load("src/server/cswap-auto-choice.mjs");
408
416
  if (!deck) return bestRules(accounts).catch(() => null);
409
417
  const r = await ask(deck, { path: "/api/cswap-auto" });
@@ -421,7 +429,7 @@ function lanesSummary(a) {
421
429
 
422
430
  /** The switch, asked of the deck: its lock, its cache invalidation, its swap
423
431
  * log — the same route the panel's click takes. */
424
- async function switchThroughDeck(deck, num) {
432
+ export async function switchThroughDeck(deck, num) {
425
433
  // Longer than the deck's own thirty seconds for `cswap switch`, so it is the
426
434
  // deck's timeout that answers rather than this one cutting it off mid-switch.
427
435
  const r = await ask(deck, { method: "POST", path: "/api/claude-accounts/switch", body: { account: num }, timeoutMs: 45_000 });
@@ -431,7 +439,7 @@ async function switchThroughDeck(deck, num) {
431
439
 
432
440
  /** The switch with no deck to ask: claude-accounts.mjs's own, under the same
433
441
  * mutex, and recorded in the same swap log the deck's route writes. */
434
- async function switchHere(num) {
442
+ export async function switchHere(num) {
435
443
  const { switchClaudeAccount } = await load("src/server/claude-accounts.mjs");
436
444
  const result = await switchClaudeAccount(num);
437
445
  if (result.ok) {
@@ -505,7 +513,7 @@ async function sessionsCommand(flags, out) {
505
513
  * with no display has nowhere to open one at all.
506
514
  */
507
515
  export function remoteShell(env = process.env, platform = process.platform, wsl = () => isWsl(platform, env)) {
508
- if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY) return true;
516
+ if (overSsh(env)) return true;
509
517
  // WSL without WSLg has no DISPLAY either, and opens the Windows browser —
510
518
  // open-url.mjs knows how.
511
519
  return platform === "linux" && !env.DISPLAY && !env.WAYLAND_DISPLAY && !wsl();
package/bin/cli/help.js CHANGED
@@ -27,12 +27,17 @@ Commands:
27
27
  you first. --all adds the ended ones. Alias: ps
28
28
  open Open the deck in a browser. Over SSH, print the
29
29
  \`ssh -L\` line that opens it on your own computer
30
+ tui A full-screen view of the accounts and the sessions
31
+ waiting on you: move with the arrows, Enter
32
+ switches, b picks the best, a turns Auto-switch on
33
+ or off, + signs an account in, ? lists the keys,
34
+ q quits
30
35
  status, stop, logs The same as --status, --stop and --logs
31
36
 
32
- Every command takes --json (one object on stdout, with schemaVersion) and
33
- --port <n> to name a deck. Without a running deck, accounts, switch and usage
34
- read claude-swap's store directly. Exit codes: 0 done, 1 failed, 2 the
35
- command line was wrong, 3 no deck is running.
37
+ Every command takes --port <n> to name a deck, and all but tui take --json
38
+ (one object on stdout, with schemaVersion). Without a running deck,
39
+ accounts, switch, usage and tui read claude-swap's store directly. Exit
40
+ codes: 0 done, 1 failed, 2 the command line was wrong, 3 no deck is running.
36
41
 
37
42
  Options:
38
43
  -p, --port <number> Preferred port (default: 4317; falls back to random 4318–4400)
@@ -21,9 +21,10 @@ import { pathToFileURL } from "node:url";
21
21
  import { isPortValue } from "../../src/server/args.mjs";
22
22
  import { PRODUCT } from "../../src/server/brand.mjs";
23
23
  import { liveDecks, olderVersion, secondStart, versionNote } from "../../src/server/running-deck.mjs";
24
- import { link } from "../../src/server/term.mjs";
24
+ import { link, overSsh } from "../../src/server/term.mjs";
25
+ import { sshNote } from "../../src/server/way-back.mjs";
25
26
  import { COMMAND, PKG_ROOT, PKG_VERSION } from "./package.js";
26
- import { G, LINKS, P, sleep, write } from "./screen.js";
27
+ import { G, LINKS, P, cols, sleep, write } from "./screen.js";
27
28
  import { reportIncompleteFlags, reportUnknownFlags } from "./startup.js";
28
29
 
29
30
  /**
@@ -100,6 +101,7 @@ export async function settleSecondStart({ flags, workspace, persist, wantCodex,
100
101
  // looks like it did nothing at all, which is the other way to be confusing
101
102
  // about this — and it names the flag for the person who wanted a fresh one.
102
103
  write(`\n ${P.muted}${G.dash} no second deck was started ${G.dash} \`${COMMAND} --new\` replaces it with a fresh one${P.reset}\n`);
104
+ if (overSsh()) write(` ${P.muted}${G.dash} ${sshNote({ command: COMMAND, dash: G.dash, columns: cols() })}${P.reset}\n`);
103
105
  if (openBrowser) {
104
106
  write(`\n ${P.ok}${P.bold}${G.play} opening browser${G.ellipsis}${P.reset}\n\n`);
105
107
  try {
@@ -13,8 +13,8 @@ import { pathToFileURL } from "node:url";
13
13
  import { budget, bootDeadlineMs } from "../../src/server/boot-deadline.mjs";
14
14
  import { PRODUCT } from "../../src/server/brand.mjs";
15
15
  import { renameNotice } from "../../src/server/invoked-as.mjs";
16
- import { link } from "../../src/server/term.mjs";
17
- import { wayBackNote } from "../../src/server/way-back.mjs";
16
+ import { link, overSsh } from "../../src/server/term.mjs";
17
+ import { sshNote, wayBackNote } from "../../src/server/way-back.mjs";
18
18
  import { COMMAND, INVOKED_AS, PKG_ROOT, PKG_VERSION } from "./package.js";
19
19
  import { G, LINKS, P, cols, fileLink, row, step, write } from "./screen.js";
20
20
 
@@ -178,6 +178,29 @@ export async function respawnHooks({ wantClaude, installHooks, bootVersion }) {
178
178
  }
179
179
  }
180
180
 
181
+ /**
182
+ * What a respawn that found Claude Code says about the setup it then ran.
183
+ *
184
+ * That respawn is the restart src/server/cli-arrival.mjs asks for when Claude
185
+ * Code is installed while the deck runs, and it does the first boot's
186
+ * startupWork, which the first boot skipped for want of a Claude Code. It is
187
+ * reported here rather than by reportStartup because the deck is already in
188
+ * use: reportStartup ends the process over hooks it cannot install, which on a
189
+ * first boot is a deck that never started, and here would be a deck that went
190
+ * away from under an open window. A failure is said, and the deck keeps
191
+ * serving everything else, as a respawn that cannot update the hooks does.
192
+ */
193
+ export async function reportClaudeArrived(jobs) {
194
+ write(row({ mark: G.ok, label: "Claude Code", detail: `found ${G.dash} setting it up` }));
195
+ const hooks = await step(`installing Claude hooks${G.ellipsis}`, jobs.hooks);
196
+ if (hooks?.ok) {
197
+ write(row({ mark: G.ok, label: "Claude hooks", detail: fileLink(hooks.v.hookPath) }));
198
+ return;
199
+ }
200
+ write(row({ mark: G.fail, tone: P.err, label: "Claude hooks", detail: "not installed" }));
201
+ console.error(`\n ${PRODUCT}: ${String(hooks?.err?.message ?? hooks?.err ?? "the hooks could not be installed")}\n`);
202
+ }
203
+
181
204
  /** The same work, said out loud, in a fixed order — a boot whose rows arrive in
182
205
  * whatever order the network settled is a boot nobody can scan twice. */
183
206
  export async function reportStartup(jobs, { workspace, wantClaude, wantCodex, CODEX_SESSIONS_DIR }) {
@@ -503,6 +526,7 @@ export function reportReady({ url, persist, openBrowser, flags }) {
503
526
  write(`\n ${P.muted}${G.dash} ${wayBackNote({
504
527
  command: COMMAND, dash: G.dash, columns: cols(),
505
528
  })}${P.reset}\n`);
529
+ if (overSsh()) write(` ${P.muted}${G.dash} ${sshNote({ command: COMMAND, dash: G.dash, columns: cols() })}${P.reset}\n`);
506
530
  // Only when one is actually being opened. Under --no-open — which is how an
507
531
  // npx update relaunches, with a tab already waiting — this was announcing
508
532
  // something that never happened.