ccdeck 3.82.3 → 4.0.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.
- package/LICENSING.md +42 -4
- package/README.md +183 -72
- package/THIRD_PARTY_NOTICES.md +243 -17
- package/bin/cli/login-item.js +5 -0
- package/bin/cli/tui.js +58 -4
- package/bin/deck.js +27 -1
- package/dist/web/assets/AccountBridge-OQHT5qmS.js +1 -0
- package/dist/web/assets/AccountSection-BpIHPhF3.js +1 -0
- package/dist/web/assets/BrowserWatchModal-DBdt52v7.js +1 -0
- package/dist/web/assets/FeedbackConversations-BJjgXI0-.js +1 -0
- package/dist/web/assets/IntegrationModal-DQ0vEz4X.js +7 -0
- package/dist/web/assets/IntegrationSkeleton-JCPbqp96.js +1 -0
- package/dist/web/assets/RadioPanel-Be6AkrKl.js +1 -0
- package/dist/web/assets/StageShell-Dq0JOQhd.js +4 -0
- package/dist/web/assets/TrafficRadar-7jqJbhaK.js +8 -0
- package/dist/web/assets/UsageHistoryModal-ckawZGoe.js +1 -0
- package/dist/web/assets/addon-unicode-graphemes-DW3WJwyh.js +18 -0
- package/dist/web/assets/addon-web-links-BWjmmSgS.js +12 -0
- package/dist/web/assets/addon-webgl-CLK4R-_u.js +75 -0
- package/dist/web/assets/app-40gNTTfq.js +361 -0
- package/dist/web/assets/app-BRjYF6oD.css +1 -0
- package/dist/web/assets/{index-B4c5MZCc.js → index-XIY3yFiN.js} +1 -1
- package/dist/web/assets/inspector-status-pane-BV_m7eBv.js +1 -0
- package/dist/web/assets/screens-9_ivqfcF.js +12 -0
- package/dist/web/assets/screens-DUniTTbC.css +1 -0
- package/dist/web/assets/stage-board-NF_wgGRA.js +2 -0
- package/dist/web/assets/use-account-BUmI-A8e.js +1 -0
- package/dist/web/assets/xterm-4jYizCpg.js +27 -0
- package/dist/web/assets/xterm-sheet-6GBZ9nXN.css +32 -0
- package/dist/web/index.html +16 -6
- package/package.json +13 -1
- package/release-notes.json +79 -0
- package/src/server/account-client.mjs +196 -0
- package/src/server/account-connect.mjs +238 -0
- package/src/server/account-flag.mjs +106 -0
- package/src/server/account-projects.mjs +1 -1
- package/src/server/account-service.mjs +532 -0
- package/src/server/account-status.mjs +293 -0
- package/src/server/account-store.mjs +137 -0
- package/src/server/account-sync.mjs +473 -0
- package/src/server/account-token-store.mjs +216 -0
- package/src/server/account-ui-fields.mjs +126 -0
- package/src/server/account-watch.mjs +1 -1
- package/src/server/browser-watch-log.mjs +1 -1
- package/src/server/browser-watch-store.mjs +1 -1
- package/src/server/ccdeck-account-routes.mjs +252 -0
- package/src/server/ccusage-install.mjs +2 -2
- package/src/server/ccusage-registry.mjs +4 -4
- package/src/server/ccusage-session.mjs +11 -0
- package/src/server/claude-accounts.mjs +1 -1
- package/src/server/claude-recovery.mjs +9 -4
- package/src/server/claude-settings-catalog.mjs +6 -6
- package/src/server/claude-settings.mjs +1 -1
- package/src/server/codex-auto.mjs +1 -1
- package/src/server/codex-cost-usage.mjs +7 -2
- package/src/server/codex-live-checkpoint.mjs +24 -9
- package/src/server/codex-live-engine.mjs +14 -4
- package/src/server/codex-live-handoff.mjs +53 -9
- package/src/server/codex-names.mjs +49 -0
- package/src/server/codex-translate.mjs +1 -1
- package/src/server/codex-ultrafast.d.mts +3 -0
- package/src/server/codex-ultrafast.mjs +5 -0
- package/src/server/codex-watch.mjs +25 -0
- package/src/server/command-panel-engine.mjs +300 -0
- package/src/server/command-panel-platform.mjs +99 -0
- package/src/server/cswap-auto-choice.mjs +1 -1
- package/src/server/cswap-auto-loop.mjs +1 -1
- package/src/server/cswap-install.mjs +21 -40
- package/src/server/deck-home.mjs +6 -0
- package/src/server/deck-prefs.mjs +53 -1
- package/src/server/detach.mjs +1 -1
- package/src/server/engine-download.mjs +277 -0
- package/src/server/engine-install.mjs +378 -0
- package/src/server/engine-package.mjs +267 -0
- package/src/server/event-log.mjs +7 -1
- package/src/server/event-pipeline.mjs +29 -1
- package/src/server/ghostty-handoff.mjs +81 -0
- package/src/server/index.mjs +143 -5
- package/src/server/installer.mjs +4 -1
- package/src/server/integrations/jira-write-guard.mjs +14 -208
- package/src/server/integrations/store.mjs +37 -19
- package/src/server/integrations/write-guard.mjs +223 -0
- package/src/server/intel-cpu-temperature.mjs +26 -0
- package/src/server/lifecycle.mjs +69 -6
- package/src/server/log-replay.mjs +4 -0
- package/src/server/login-service.mjs +116 -14
- package/src/server/macmon.mjs +1 -1
- package/src/server/npm-latest.mjs +1 -1
- package/src/server/org-telemetry.mjs +1 -1
- package/src/server/output-watch.mjs +4 -1
- package/src/server/panel-provenance.mjs +390 -0
- package/src/server/pinned-build.mjs +14 -0
- package/src/server/prefs-refusal.mjs +8 -1
- package/src/server/prefs-routes.mjs +60 -11
- package/src/server/pro-engine-client.mjs +339 -0
- package/src/server/pro-engine-install.mjs +294 -0
- package/src/server/pro-engine-terminal.mjs +308 -0
- package/src/server/project-discovery.mjs +139 -0
- package/src/server/provider-session-name.mjs +58 -0
- package/src/server/quota-closes.mjs +1 -1
- package/src/server/quota-history.mjs +1 -1
- package/src/server/reports.mjs +86 -21
- package/src/server/request-gates.mjs +34 -5
- package/src/server/restart-note.mjs +1 -1
- package/src/server/seed-boundary.mjs +489 -0
- package/src/server/session-counts.mjs +244 -0
- package/src/server/session-deck-names.mjs +143 -0
- package/src/server/session-enrichment.mjs +43 -6
- package/src/server/session-name-route.mjs +73 -0
- package/src/server/session-summary.mjs +12 -1
- package/src/server/session-transcript-routes.mjs +167 -0
- package/src/server/swap-log.mjs +1 -1
- package/src/server/system-metrics.mjs +57 -0
- package/src/server/terminal-bridge.mjs +485 -0
- package/src/server/terminal-folder.mjs +61 -0
- package/src/server/terminal-js-routes.mjs +752 -0
- package/src/server/terminal-routes.mjs +553 -0
- package/src/server/terminal-sessions.mjs +759 -0
- package/src/server/terminal-socket.mjs +403 -0
- package/src/server/terminal-target.mjs +928 -0
- package/src/server/thermal-metrics.mjs +13 -9
- package/src/server/tmux-control.mjs +1319 -0
- package/src/server/tmux-download.mjs +220 -0
- package/src/server/tmux.mjs +542 -0
- package/src/server/token-redact.mjs +42 -3
- package/src/server/tool-audit-report.mjs +44 -6
- package/src/server/tool-audit-routes.mjs +12 -1
- package/src/server/tool-audit.mjs +42 -8
- package/src/server/traffic-radar-monitor.mjs +1 -1
- package/src/server/traffic-radar-permission.mjs +1 -1
- package/src/server/transcript-gate.mjs +1 -1
- package/src/server/transcript-scan.mjs +15 -7
- package/src/server/transcript-turns.mjs +154 -0
- package/src/server/tui-network.mjs +1 -0
- package/src/server/tui-view.mjs +28 -0
- package/src/server/utf8-carry.mjs +159 -0
- package/src/server/uv-bootstrap.mjs +2 -2
- package/src/server/windows-acl.mjs +158 -0
- package/src/server/ws-frames.mjs +690 -0
- package/dist/web/assets/BrowserWatchModal-BmRTh_xT.js +0 -1
- package/dist/web/assets/IntegrationModal-C_f526aV.js +0 -7
- package/dist/web/assets/RadioPanel-D2rkf9cg.js +0 -1
- package/dist/web/assets/TrafficRadar-BOgVBLIN.js +0 -8
- package/dist/web/assets/UsageHistoryModal-BJPTFwM9.js +0 -1
- package/dist/web/assets/app-CbXmr9rC.css +0 -1
- package/dist/web/assets/app-DZdZoqJ6.js +0 -358
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
# ccdeck — a live dashboard for Claude Code and Codex
|
|
9
9
|
|
|
10
|
-
ccdeck is a free, open-source (AGPL-3.0) dashboard that runs on your machine and shows every Claude Code and OpenAI Codex CLI session, including ones started in a plain terminal: which Claude Code session needs input, each Claude Code subagent and every tool call as it runs, cost and quota left. Start it with `npx ccdeck` or the desktop app.
|
|
10
|
+
ccdeck is a free, open-source (AGPL-3.0) dashboard that runs on your machine and shows every Claude Code and OpenAI Codex CLI session, including ones started in a plain terminal: which Claude Code session needs input, each Claude Code subagent and every tool call as it runs, cost and quota left. Each session's terminal opens right in the deck, and up to four sit side by side in Workspace. Start it with `npx ccdeck` or the desktop app.
|
|
11
11
|
|
|
12
12
|
Step-by-step guides: [ccdeck.dev/guides](https://ccdeck.dev/guides/)
|
|
13
13
|
|
|
@@ -31,9 +31,9 @@ Or the desktop app, with the waiting count in your menu bar: **[macOS](https://g
|
|
|
31
31
|
|
|
32
32
|
*Generated sessions and invented quota and spend, drawn by the deck itself: `assets/canvas-demo.mjs` writes the log, `node assets/capture-hero.mjs` takes the shot. Click through for full size.*
|
|
33
33
|
|
|
34
|
-
which Claude Code session is blocked on you · tool calls · one canvas · cost · quota · local · sessions never leave
|
|
34
|
+
which Claude Code session is blocked on you · terminals in the deck · 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) · [Support](#support-ccdeck) · [FAQ](#questions-people-ask)
|
|
36
|
+
[ccdeck.dev](https://ccdeck.dev) · [Guides](https://ccdeck.dev/guides/) · [What you get](#what-you-get) · [Terminal](#terminal) · [Workspace](#workspace) · [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>
|
|
@@ -44,7 +44,7 @@ which Claude Code session is blocked on you · tool calls · one canvas · cost
|
|
|
44
44
|
|
|
45
45
|
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.
|
|
46
46
|
|
|
47
|
-
ccdeck answers that in one place: every session stopped on a human is at the top of the
|
|
47
|
+
ccdeck answers that in one place: every session stopped on a human is at the top of the Sessions list with the wait beside it, longest first, and the topbar names them beside a count that goes straight to the oldest one. The question stops being *which tab* and becomes *this one*, and that session's terminal opens right there, in the deck.
|
|
48
48
|
|
|
49
49
|
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.
|
|
50
50
|
|
|
@@ -54,55 +54,54 @@ ccdeck draws the tree instead. It is local and needs no configuration: it regist
|
|
|
54
54
|
|
|
55
55
|
One canvas. No tabs. No kanban.
|
|
56
56
|
|
|
57
|
-
The deck opens on these
|
|
57
|
+
The deck opens on these seven pictures the first time it runs — they are the whole tour, and `Take the tour` on an empty canvas brings them back.
|
|
58
58
|
|
|
59
59
|
<table>
|
|
60
60
|
<tr>
|
|
61
|
-
<td><img src="assets/guide/welcome-1.svg" width="440" alt="Sessions waiting on you
|
|
62
|
-
<td><img src="assets/guide/welcome-2.svg" width="440" alt="
|
|
61
|
+
<td><img src="assets/guide/welcome-1.svg" width="440" alt="Sessions waiting on you lead the session list, under Needs you."></td>
|
|
62
|
+
<td><img src="assets/guide/welcome-2.svg" width="440" alt="Click a card: its terminal opens beside the board, so you can answer there."></td>
|
|
63
63
|
</tr>
|
|
64
64
|
<tr>
|
|
65
|
-
<td align="center"><sub>Sessions waiting on you
|
|
66
|
-
<td align="center"><sub>
|
|
65
|
+
<td align="center"><sub>Sessions waiting on you lead the session list, under Needs you.</sub></td>
|
|
66
|
+
<td align="center"><sub>Click a card: its terminal opens beside the board, so you can answer there.</sub></td>
|
|
67
67
|
</tr>
|
|
68
68
|
<tr>
|
|
69
|
-
<td><img src="assets/guide/welcome-3.svg" width="440" alt="
|
|
70
|
-
<td><img src="assets/guide/welcome-4.svg" width="440" alt="
|
|
69
|
+
<td><img src="assets/guide/welcome-3.svg" width="440" alt="Workspace puts up to four sessions side by side. Ctrl+` switches to it."></td>
|
|
70
|
+
<td><img src="assets/guide/welcome-4.svg" width="440" alt="The Inspector shows every agent, subagent and tool call, with cost and time."></td>
|
|
71
71
|
</tr>
|
|
72
72
|
<tr>
|
|
73
|
-
<td align="center"><sub>
|
|
74
|
-
<td align="center"><sub>
|
|
73
|
+
<td align="center"><sub>Workspace puts up to four sessions side by side. <kbd>Ctrl+`</kbd> switches to it.</sub></td>
|
|
74
|
+
<td align="center"><sub>The Inspector shows every agent, subagent and tool call, with cost and time.</sub></td>
|
|
75
75
|
</tr>
|
|
76
76
|
<tr>
|
|
77
|
-
<td><img src="assets/guide/welcome-5.svg" width="440" alt="
|
|
78
|
-
<td><img src="assets/guide/welcome-6.svg" width="440" alt="
|
|
77
|
+
<td><img src="assets/guide/welcome-5.svg" width="440" alt="Left edge: Sessions, Accounts, Settings at its foot. Right: Usage and This machine."></td>
|
|
78
|
+
<td><img src="assets/guide/welcome-6.svg" width="440" alt="Switch Claude and Codex accounts. Paired machines repair each other's expired logins."></td>
|
|
79
79
|
</tr>
|
|
80
80
|
<tr>
|
|
81
|
-
<td align="center"><sub>
|
|
82
|
-
<td align="center"><sub>
|
|
81
|
+
<td align="center"><sub>Left edge: Sessions, Accounts, Settings at its foot. Right: Usage and This machine.</sub></td>
|
|
82
|
+
<td align="center"><sub>Switch Claude and Codex accounts. Paired machines repair each other's expired logins.</sub></td>
|
|
83
83
|
</tr>
|
|
84
84
|
<tr>
|
|
85
|
-
<td><img src="assets/guide/welcome-7.svg" width="440" alt="
|
|
86
|
-
<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>
|
|
85
|
+
<td colspan="2" align="center"><img src="assets/guide/welcome-7.svg" width="440" alt="Run claude or codex in any folder, or use New session. It appears here."></td>
|
|
87
86
|
</tr>
|
|
88
87
|
<tr>
|
|
89
|
-
<td align="center"><sub>
|
|
90
|
-
<td align="center"><sub>Run <code>claude</code> or <code>codex</code> in any folder. It shows up here on its own.</sub></td>
|
|
88
|
+
<td colspan="2" align="center"><sub>Run <code>claude</code> or <code>codex</code> in any folder, or use New session. It appears here.</sub></td>
|
|
91
89
|
</tr>
|
|
92
90
|
</table>
|
|
93
91
|
|
|
94
92
|
| | |
|
|
95
93
|
|---|---|
|
|
96
|
-
| **Blocked on you** | A permission prompt, or a finished turn waiting for your next instruction, sorts that session to the top of the
|
|
97
|
-
| **
|
|
94
|
+
| **Blocked on you** | A permission prompt, or a finished turn waiting for your next instruction, sorts that session to the top of the Sessions list 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, and the session's name beside it, with how long it has waited and on what — one click from its card. Claude Code only — the deck reads Codex from its rollout log, and a rollout carries no such signal. |
|
|
95
|
+
| **Its terminal, in the deck** | Click a session's card and its terminal opens in a pane beside the board: type to Claude Code or Codex there, resume a session that ended, or start a new one in any folder. **Workspace** puts up to four side by side. See [Terminal](#terminal) and [Workspace](#workspace). |
|
|
96
|
+
| **What each session is doing** | The note tied to each session's card — and the line under its row in the Sessions list — says it while it works: the sentence the newest reply wrote, or the description on the command it ran. Once the turn is over it keeps the last thing the session did, until Claude Code's recap takes its place. A background session (`claude --bg`, or one started from `claude agents`) shows Claude Code's own line instead, read from its job folder in `~/.claude/jobs`: the question it is stuck on and the reply Claude Code suggests, or the headline of what it got done. No model is called for any of it. A Codex session, read from its rollout log, has the note only while a turn runs, and it says the first line of the prompt that began the turn: no line is taken from a Codex reply, and no recap follows. |
|
|
98
97
|
| **Live DAG** | Nodes are agents and edges are spawns; each agent's latest tool calls sit beside its node and light up while they run. In-flight edges animate, settled ones dim. |
|
|
99
|
-
| **Both providers, one canvas** | Claude Code through hooks, Codex through its rollout log. The model
|
|
98
|
+
| **Both providers, one canvas** | Claude Code through hooks, Codex through its rollout log. The card names a Codex session, and the Inspector shows each session's model (`Opus 5`, `GPT-5.5`). Codex child sessions are connected when their rollout records an explicit parent. Each thread keeps its own tool calls and token totals. |
|
|
100
99
|
| **Cost and quota, live** | Spend per model and per session, plus Claude and Codex quota windows as they refill. |
|
|
101
100
|
| **Tool activity** | Which tools and commands your Claude Code and Codex agents ran on this machine, over the last day or up to 90 days: how many calls, how long they took, which ones fail. Kept on this machine and nowhere else. |
|
|
102
|
-
| **Skill activity** | Which skills your agents used, whether you typed them or the agent called them, how often and when last — from
|
|
101
|
+
| **Skill activity** | Which skills your agents used, whether you typed them or the agent called them, how often and when last — from **More** on the right stripe, below Tool activity. Kept on this machine and nowhere else. |
|
|
103
102
|
| **Jira beside your agents** | Connect Jira Cloud or Jira Server / Data Center in **Settings › Integrations**, and a Jira control joins the left stripe (`I`). It opens a board's backlog laid out the way Jira's Backlog page lays it out — active sprints first, then the future ones and the backlog, in Jira's rank order, with the board's own quick filters, *Only my issues* and *Hide done* — and an issue's description, comments, attachments and sub-tasks beside the list. Browsing only reads; from an issue's details you can add a comment or change its status, and on a Scrum board ordered by Rank you can also drag issues, or use **Move**, to reorder them or send them to another sprint or the backlog (see [What it touches](#what-it-touches)). |
|
|
104
103
|
| **GitHub and GitLab beside your agents** | Connect GitHub, or GitLab.com or your own GitLab, with a personal access token in **Settings › Integrations**, and its control joins the left stripe. It opens the screens you already work through on GitLab — Branches, Merge requests (Pull requests), Pipelines (Actions) and Issues, for one project or across them — with the merge request, branch, pipeline with its jobs and the failed job's last log lines, or issue beside the list. Paste a link to open it. Read-only: it never comments, approves, merges or re-runs anything. |
|
|
105
|
-
| **Double-click to inspect** | Any
|
|
104
|
+
| **Double-click to inspect** | Any card opens its prompt, tool calls, token usage and timing in the Inspector. A single click opens its session's terminal pane; with the terminal turned off, it selects the card and frames its session. |
|
|
106
105
|
| **Survives restarts** | Events are appended to this platform's log directory (see `--history` below) and replayed on open. |
|
|
107
106
|
| **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. |
|
|
108
107
|
| **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). |
|
|
@@ -111,13 +110,62 @@ The deck opens on these eight pictures the first time it runs — they are the w
|
|
|
111
110
|
|
|
112
111
|
Step by step: [See which Claude Code session is waiting for input](https://ccdeck.dev/guides/waiting-on-you/) · [See Claude Code subagents and tool calls live](https://ccdeck.dev/guides/read-a-session/)
|
|
113
112
|
|
|
113
|
+
## Terminal
|
|
114
|
+
|
|
115
|
+
Your sessions' terminals are inside the deck, for Claude Code and Codex alike, on Linux, macOS and Windows. Click a session's card on the board, or **Open** under its title in the Inspector, and its terminal opens in a pane beside the board, with the keys in it: type to the agent as you would in any terminal. **✕** closes the pane, and the session keeps running.
|
|
116
|
+
|
|
117
|
+
What the pane does depends on where the session runs:
|
|
118
|
+
|
|
119
|
+
| The session | The pane |
|
|
120
|
+
|---|---|
|
|
121
|
+
| was started in the deck | attaches to it |
|
|
122
|
+
| runs in your own tmux (Linux, macOS) | joins that tmux pane, at its size |
|
|
123
|
+
| is a Claude Code background session | attaches to it |
|
|
124
|
+
| runs in another terminal | says so. Quit it there, and the pane offers **Reopen here**, with the same conversation |
|
|
125
|
+
| has ended | offers **Reopen here**, which resumes the same conversation |
|
|
126
|
+
|
|
127
|
+
Ending an agent yourself (`/exit` or `Ctrl+D`) closes its pane, and the session stays in the list. After a crash or a kill, the pane keeps its last frame and offers **Reopen here**.
|
|
128
|
+
|
|
129
|
+
**New session** starts Claude Code or Codex in a folder: **+ New session** above the board while a pane is open, or **+** at the top of the Sessions list in Workspace. One field, *Search projects or enter a path*, searches your projects and the folders you used before, and takes a full path. The deck checks the folder before it starts, and says so if the agent cannot open it. For Claude Code it also offers the model, the permission mode and a new git worktree. `Ctrl+Enter` (`⌘+Enter` on a Mac) starts.
|
|
130
|
+
|
|
131
|
+
**Next ask.** With a pane open, **Next ask** in the bar under the terminal, or `N` with the keys on the board, opens the next session waiting on you, with the keys in its pane. It never moves on by itself, so a `1` you type always answers the prompt you are looking at.
|
|
132
|
+
|
|
133
|
+
**Text size.** The terminal has its own text size, apart from the page's: **Aa** in the pane's header, or `Ctrl+=`, `Ctrl+-` and `Ctrl+0` while the pane has the keys (`⌘` on a Mac). Every pane in this browser uses the same size.
|
|
134
|
+
|
|
135
|
+
| Key | Does |
|
|
136
|
+
|---|---|
|
|
137
|
+
| click a card | open its session's terminal pane, with the keys in it |
|
|
138
|
+
| `J` `K`, then `Enter` | with a pane open: step through the sessions beside it, then type into one |
|
|
139
|
+
| `N` | with a pane open: the next session waiting on you |
|
|
140
|
+
| `Ctrl+Shift+X` (`⌃⇧X` on a Mac) | give the keys back to the board |
|
|
141
|
+
| ``Ctrl+` `` (Control on a Mac too) | switch between Board and Workspace, from inside a terminal too |
|
|
142
|
+
| `Ctrl+=` `Ctrl+-` `Ctrl+0` (`⌘` on a Mac) | larger, smaller and normal terminal text |
|
|
143
|
+
|
|
144
|
+
In a browser tab, the browser keeps `Ctrl+W`, `Ctrl+T` and `Ctrl+N` for itself; **⤢** full screen, or the [desktop app](#desktop-app), gives them to the session.
|
|
145
|
+
|
|
146
|
+
**On by default.** **Settings › General › Experimental › Command Panel** turns the terminal off. That closes the panes, not their sessions: they keep running, and are back when you turn it on again. On Linux and macOS, a session started here runs in the deck's own tmux, apart from yours, which is what keeps it running when its pane closes or the deck restarts; that needs tmux 3.2 or newer installed on the machine — `brew install tmux` on a Mac, your distribution's `tmux` package on Linux. Without it, the pane says **tmux · not found on this machine** (or **tmux · older than 3.2 on this machine**), and **Check again** looks again once it is installed. Windows on ARM has no terminal yet; the rest of the deck works there as usual.
|
|
147
|
+
|
|
148
|
+
**The engine.** The terminal runs through ccdeck's terminal engine, a separate program under its own licence that comes with ccdeck: npm installs the one for this machine, and the desktop app carries it. It is checked against ccdeck's signature before every start. **Settings › General › Experimental** shows its version under **Terminal engine**, with **Check for an update** and **Remove the engine**. When ccdeck came without it — an install made with `--omit=optional`, or a git checkout — the pane says **The terminal needs its engine** and offers **Install the engine**, which downloads that same package from the npm registry, or **Install from a file…**. See [What it touches](#what-it-touches) and [License](#license).
|
|
149
|
+
|
|
150
|
+
## Workspace
|
|
151
|
+
|
|
152
|
+
**Workspace**, beside **Board** in the top bar (``Ctrl+` ``), puts sessions side by side: up to four panes, with the Sessions list on the left.
|
|
153
|
+
|
|
154
|
+
- **Open one beside the others**: press `⇧↵` on its row in the Sessions list, or drag the row onto a pane's edge. Dropped on the middle of a pane, it shows there instead.
|
|
155
|
+
- **One pane has the keys**, and the others keep running. `Enter` on a row shows that session in the pane with the keys, ready to type; `1` to `4` move the keys to that pane, counted left to right, then top to bottom.
|
|
156
|
+
- **✕** empties a pane, and its session keeps running. **⤢** fills the Workspace with one pane. The lines between panes, and the Sessions list's edge, drag to resize.
|
|
157
|
+
- **Rename** a session where its name is drawn: double-click it, press `F2` on its row, or use the pencil in the pane's header. The name shows everywhere in the deck, and is saved in the session's own conversation too, where Claude Code and Codex keep a session's name.
|
|
158
|
+
- **Chat | Term**: a Claude Code or Codex session's pane offers both. **Chat** shows the conversation, and you can reply from it while the session's terminal is open here; **Term** is the terminal itself.
|
|
159
|
+
|
|
160
|
+
A window too narrow for the panes shows the one with the keys, and a strip names the others. Phones have no Workspace: a session you tap opens in a pane of its own, with **‹** back to the board, and **More** in the dock has **Open the Command Panel**.
|
|
161
|
+
|
|
114
162
|
## Quick start
|
|
115
163
|
|
|
116
164
|
```bash
|
|
117
165
|
npx ccdeck
|
|
118
166
|
```
|
|
119
167
|
|
|
120
|
-
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
|
|
168
|
+
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 board fills in live; click its card to open its terminal in the deck.
|
|
121
169
|
|
|
122
170
|
The deck keeps running after you close the terminal, and starts again when you
|
|
123
171
|
log in. **`ccdeck --stop` is the off switch**; `Ctrl+C` only cancels a start that
|
|
@@ -126,19 +174,21 @@ holds the terminal the way every version before 3.20 did.
|
|
|
126
174
|
|
|
127
175
|
Sessions already working when ccdeck starts can appear with a **restored** marker. Codex recovery reads recent unfinished turns from local rollouts; an absent ending does not confirm that its process is still running. On macOS and Linux, Claude recovery verifies a busy session against its process-start identity. **Settings › General** has a separate startup-recovery switch for each provider. Earlier tool calls are not replayed. [Recovery behavior and limits](docs/features/session-recovery.md).
|
|
128
176
|
|
|
129
|
-
The panels open from
|
|
177
|
+
The panels open from two stripes, one on each edge of the window, each door on the side its panel opens. The left stripe holds **Sessions** and **Accounts**, then a door for each connected Jira, GitHub or GitLab; **More** at its foot holds Account capacity, the Reset calendar, Explore integrations and Radio, and **Settings** sits under it. The right stripe holds the **Inspector**, then **Usage** and **This machine**; **More** at its foot holds Usage history, Tool activity, Skill activity, Browser watch and Telemetry Radar. Each panel shows or hides beside the canvas, and several can be open at once. Point at a door, or Tab to it, and its hint names its key — `L`, `A`, `D`, `U`, `S`, `H`, `B` — while the single-key shortcuts are on; Account capacity, the Reset calendar, Tool activity, Skill activity, Telemetry Radar and Radio have none. **Hide words**, at the foot of the left stripe, folds both stripes to their icons. **Search** in the top bar (⌘K or Ctrl+K, which works with the single keys off) opens any of them, a setting or a session by name. On a phone the board is a full-width stack of cards, and the panels are in a dock along the bottom: Accounts, Sessions, Usage and Machine, with the rest, Settings included, behind its **More**.
|
|
178
|
+
|
|
179
|
+
**The board** draws each session as a card, grouped by project, and a card's colour says its state. The top bar counts the sessions working and done, and **Board | Workspace** beside Search switches the view. The **⋯** among the canvas controls holds the board's commands — **Re-arrange the canvas** (`R`), **Clear the deck…** (`C`), **Open the Command Panel** and **Keyboard shortcuts** (`?`) — and which kinds of tool call the cards show. The board always stays live: nothing pauses it. `J` and `K` walk the cards, `N` goes to the next session waiting on you (`Shift+N` back), and `P` peeks at the selected card without opening anything. **The Sessions list** reads like an inbox: **Needs you** first, longest wait first, then **Done · new**, **Working** and **Done**; a row stays put while your pointer is in the list. **The Inspector** is about the session in focus, in three tabs, **Agents**, **Time** and **Context**, with its next step under the title: **Answer** for a session waiting on you, **Open** for any other, and **Show recap** beside it once a Claude Code session has finished.
|
|
130
180
|
|
|
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 **
|
|
181
|
+
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 **Fit all**, after you have panned or zoomed, which fits every session on screen again and keeps new ones in view.
|
|
132
182
|
|
|
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**,
|
|
183
|
+
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**, at the foot of the left stripe (on a phone, in the dock), 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 thirteen color themes, Ink the newest, a light one with warm paper surfaces and charcoal text — 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 thirteen, 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. With **While the deck is closed** on in **Settings › Notifications** (off until you turn it on), a session that finishes its turn sends a notification while the deck is out of sight, as one waiting on you does. `?` 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, digits and `?` 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
184
|
|
|
135
|
-
**Radio**,
|
|
185
|
+
**Radio**, in **More** at the foot of the left stripe (pressing the character on the canvas plays it too), 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
186
|
|
|
137
|
-
**Tool activity**,
|
|
187
|
+
**Tool activity**, in **More** at the foot of the right stripe, below Usage history, is a page of which tools and commands the Claude Code and Codex agents on this machine used. For the last 24 hours, 7, 30 or 90 days, and both CLIs or one, it lists each tool's calls, its total and usual time and its failures, sortable by any of them and searchable, under up to three findings worth a look: the tool that takes the most time, one that fails often, the slowest. A row opens that tool's details beside the list: who used it, its calls per day, its latest and slowest calls. A shell command counts per operation — `git status`, `git push` and `npm run build` are rows of their own — and an MCP tool under its own name. A call's time runs from the agent starting the tool to its result, so it includes any wait for your approval, and Claude Code and Codex time their tools differently. **Skill activity**, the next row in that menu, lists the skills those agents used, ranked by uses, with when each last ran: a skill Claude calls, a slash command you type (when every Claude Code on the machine is 2.1.116 or newer — see [How it works](#how-it-works)), a skill you pick in Codex, and one Codex picks itself, counted when it reads that skill's instructions. The same command run again in a session with the same arguments, such as a `/loop` tick, is a repeat and is left out of the count. A skill opens its details: its uses per day, the projects it ran in, and its latest uses, each linking to its session while that is still on the canvas. It counts what the deck captures from the first time it runs at 3.42.0 or later — earlier sessions are not read back — and it is kept apart from the canvas: Clear empties the canvas and leaves the tool history. What it keeps, and where, is in [What it touches](#what-it-touches).
|
|
138
188
|
|
|
139
|
-
No config file. No account. What your sessions contain — your prompts, the replies, the files they touch — is never reported anywhere. The deck does send usage reports, on by default: its version, your system, your IP address and a device fingerprint, rough counts such as how many sessions ran in a day, the provider names (Jira, GitHub or GitLab) for any locally saved tracker connections, and the errors it hits. Only these three provider names are included in the daily connection snapshot — never tracker URLs, connection IDs, account details or tokens. The snapshot says what is configured, not whether a connection is still valid. It has no switch for them; `AGENTS_DECK_NO_REPORTS=1` keeps them off from the first start.
|
|
189
|
+
No config file. No account. What your sessions contain — your prompts, the replies, the files they touch — is never reported anywhere. The deck does send usage reports, on by default: its version, your system, your IP address and a device fingerprint, rough counts such as how many sessions ran in a day, the provider names (Jira, GitHub or GitLab) for any locally saved tracker connections and how many of each are saved, and the errors it hits. Only these three provider names and a count of each, capped at 50, are included in the daily connection snapshot — never tracker URLs, connection IDs or names, account details or tokens; when the deck cannot read its list of connections, the snapshot says only that. The snapshot says what is configured, not whether a connection is still valid. It has no switch for them; `AGENTS_DECK_NO_REPORTS=1` keeps them off from the first start.
|
|
140
190
|
|
|
141
|
-
**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.
|
|
191
|
+
**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. A [terminal pane](#terminal) is a different thing on purpose: it is the session's own terminal, so what you type there reaches the agent, as it would in any terminal.
|
|
142
192
|
|
|
143
193
|
What the deck does write, and the short list of what does leave the machine, is in [What it touches](#what-it-touches).
|
|
144
194
|
|
|
@@ -146,7 +196,7 @@ Step by step: [Install ccdeck with npx and see your first session](https://ccdec
|
|
|
146
196
|
|
|
147
197
|
### Desktop app
|
|
148
198
|
|
|
149
|
-
The same deck as an app: it starts the deck itself and puts an icon in the menu bar (the tray on Windows and Linux) that counts the Claude Code sessions stopped on a permission prompt or a question — the number sits beside the icon on macOS, and in the icon's tooltip and menu on Windows and Linux. With **Notifications while closed** ticked in that menu, which starts off, it also sends a notification while the window is closed wherever an open page would have played a sound, with the deck's own tone on macOS. The app also shows the [account notifications](#accounts), silently and whether its window is open or closed. It needs no Node.js. The deck it starts is given whichever of the variables in the environment table further down your login shell sets — `AGENTS_DECK_NO_REPORTS` and `CLAUDE_CONFIG_DIR` among them — however the app was opened, as a deck started from a terminal would be. If a deck from `npx ccdeck` is already running, the app uses that one rather than starting a second, and replaces it only when it is older than the one the app carries.
|
|
199
|
+
The same deck as an app: it starts the deck itself and puts an icon in the menu bar (the tray on Windows and Linux) that counts the Claude Code sessions stopped on a permission prompt or a question — the number sits beside the icon on macOS, and in the icon's tooltip and menu on Windows and Linux. With **Notifications while the deck is closed** ticked in that menu, which starts off, it also sends a notification while the window is closed wherever an open page would have played a sound, with the deck's own tone on macOS. The app also shows the [account notifications](#accounts), silently and whether its window is open or closed. It needs no Node.js, and it carries the terminal engine for its system, so the [terminal](#terminal) needs nothing more than tmux 3.2 or newer on Linux and macOS. The deck it starts is given whichever of the variables in the environment table further down your login shell sets — `AGENTS_DECK_NO_REPORTS` and `CLAUDE_CONFIG_DIR` among them — however the app was opened, as a deck started from a terminal would be. If a deck from `npx ccdeck` is already running, the app uses that one rather than starting a second, and replaces it only when it is older than the one the app carries.
|
|
150
200
|
|
|
151
201
|
| System | Download |
|
|
152
202
|
| --- | --- |
|
|
@@ -167,17 +217,37 @@ The app keeps itself current from this repository's releases, and installs an up
|
|
|
167
217
|
|
|
168
218
|
Step by step: [Install the ccdeck app on Mac, Windows or Linux](https://ccdeck.dev/guides/desktop-app/)
|
|
169
219
|
|
|
220
|
+
### Starting in a project
|
|
221
|
+
|
|
222
|
+
**New session** offers folders from current sessions and recent choices, followed
|
|
223
|
+
by nearby Git repositories. Open **Worktrees** to see linked checkouts grouped
|
|
224
|
+
by repository. Search by project, worktree name, branch or path. You can also
|
|
225
|
+
choose another folder or enter a full path. Enter selects a folder. Start
|
|
226
|
+
(or ⌘/Ctrl+Enter) launches the chosen agent in that folder.
|
|
227
|
+
|
|
228
|
+
Discovery looks in Desktop, Documents, Developer, Projects, repos, Code, src and
|
|
229
|
+
workspace under your home folder, including lowercase Projects/Code variants.
|
|
230
|
+
It checks directory entries and Git worktree metadata. Hidden folders, dependencies
|
|
231
|
+
and nested symlinks are skipped during the folder scan. Linked worktrees registered
|
|
232
|
+
with an indexed repository can appear even when they live outside the scanned folders.
|
|
233
|
+
The scan goes at most three levels deep, with directory, entry and result caps
|
|
234
|
+
and a short time budget; a partial-result message appears if a cap is reached
|
|
235
|
+
or a directory cannot be read because of its permissions.
|
|
236
|
+
Results are cached for 30 seconds. A folder outside these locations can always
|
|
237
|
+
be chosen explicitly.
|
|
238
|
+
|
|
170
239
|
## Requirements
|
|
171
240
|
|
|
172
241
|
- 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
|
|
173
242
|
- Claude Code CLI or OpenAI Codex CLI (or both)
|
|
174
243
|
- Optional: [claude-swap](https://github.com/realiti4/claude-swap) for the Accounts panel; the deck can install it for you
|
|
244
|
+
- For the [terminal](#terminal) on Linux and macOS, tmux 3.2 or newer: `brew install tmux` on a Mac, your distribution's `tmux` package on Linux. Its engine is nothing to install: npm brings the terminal engine for this machine with ccdeck, and the desktop app carries it. Windows on ARM has no terminal yet
|
|
175
245
|
- Nothing else. On Apple Silicon the deck fetches [`macmon`](https://github.com/vladkens/macmon) itself for the temperature rows; see below.
|
|
176
246
|
|
|
177
247
|
### Claude Telemetry Radar (macOS, Linux and Windows)
|
|
178
248
|
|
|
179
|
-
Open **Telemetry Radar** from
|
|
180
|
-
phone. Three views keep configuration, observed traffic and saved files separate:
|
|
249
|
+
Open **Telemetry Radar** from **More** at the foot of the right stripe, or from
|
|
250
|
+
**More** in the dock on a phone. Three views keep configuration, observed traffic and saved files separate:
|
|
181
251
|
|
|
182
252
|
- **Monitor** lists decoded messages and unreadable connection observations.
|
|
183
253
|
The empty view shows one workspace. History controls and filters appear under
|
|
@@ -323,10 +393,12 @@ policy, firmware and thermal constraints; it does not identify overheating or
|
|
|
323
393
|
measure lost turbo boost. A 0% row means Windows reports no cap below nominal,
|
|
324
394
|
not that every hardware-level thermal restriction has been ruled out. Missing
|
|
325
395
|
counters stay unavailable. No driver or administrator access is required.
|
|
326
|
-
| macOS, Intel | `ioreg` for the GPU, `pmset -g therm` for throttling | nothing |
|
|
396
|
+
| macOS, Intel | `osx-cpu-temp` for the CPU proximity sensor, `ioreg` for the GPU, `pmset -g therm` for throttling | optional `brew install osx-cpu-temp` for CPU degrees; GPU and throttling need nothing |
|
|
327
397
|
| macOS, Apple Silicon | `macmon`, which the deck fetches for you | nothing |
|
|
328
398
|
|
|
329
|
-
|
|
399
|
+
Intel CPU degrees use an existing `osx-cpu-temp` installation from either Homebrew prefix. It runs without `sudo`; ccdeck does not install it automatically. A missing tool or unavailable sensor leaves the CPU row absent.
|
|
400
|
+
|
|
401
|
+
Apple Silicon needs a different 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.
|
|
330
402
|
|
|
331
403
|
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.
|
|
332
404
|
|
|
@@ -387,6 +459,10 @@ On Windows, Share reports when the profile's permissions prevent export. **Secur
|
|
|
387
459
|
|
|
388
460
|
For conversations that accept direct input, ccdeck waits for observed tools and approvals, pauses responses through the native interrupt API, verifies the new login, then submits one Continue in each paused conversation. Supported subagents move with their parent: parents pause first, then the same child conversations resume before their parents. A naturally finished response stays idle.
|
|
389
461
|
|
|
462
|
+
When a supported direct-input conversation has a running tool, ccdeck asks it to finish that call and record a checkpoint before starting more work. It switches accounts only after confirming the checkpoint, then continues the same conversation once. Commands are not cancelled, approvals are not answered, and uncertain activity stays waiting. During a pending switch, the Accounts panel names the account still in use above the list; the selected default is not confirmation that the running conversation has changed accounts.
|
|
463
|
+
|
|
464
|
+
A different account can also continue the latest direct-input response stopped by Codex's explicit usage-limit error within the last five minutes, including a limit reached during the handoff. ccdeck confirms the new login before sending one continuation and rechecks that no newer input or response has replaced that failure. An unchanged account, old failure, user interruption, other error or unconfirmed send does not authorize automatic retry. This is tied to a new account switch; restarting ccdeck does not scan old failures and resume them.
|
|
465
|
+
|
|
390
466
|
Parent-owned multi-agent v2 children use a cooperative pause instead. ccdeck asks their existing active parent to let current tools finish and collect checkpoints of unfinished work. Only after those responses end does it change the account and ask the parent to resume the same agents with Codex’s native follow-up tool. The row shows when child resumption is still pending; success requires observing their new live turns. Finished original assignments stay finished. A running answer or tool may finish before its checkpoint takes effect. If the parent is unavailable or its activity cannot be inspected safely, the switch waits. An active V2 parent whose children are idle waits for inspectable child activity or natural completion. A checkpoint unconfirmed after two minutes, or a follow-up unconfirmed after one minute, requires checking the conversation. Uncertain requests are never resent, and new handoffs cannot erase unfinished recovery records. ccdeck never changes network permissions or answers an approval for you.
|
|
391
467
|
|
|
392
468
|
Live switching uses Codex's experimental host-managed authentication with ChatGPT accounts stored in private `auth.json` files. The live connection keeps access tokens in server memory and leaves source-profile renewal to native Codex; it does not copy authentication files. Explicit Share/Import is the separate credential-copying action described above. ccdeck must stay open to renew this live login; it saves only account IDs and ownership metadata for recovery after restart. A login made directly in Codex pauses ccdeck's control instead of being changed back. After a restart or lost connection, automatic recovery requires a native workspace ID; email alone is insufficient. If Codex cannot attest that identity, the panel offers **Reconnect selected account** after you check `/status`. This explicitly reapplies the selected login to the shared server. A second ccdeck instance cannot control the same daemon simultaneously. `AGENTS_DECK_NO_CODEX_LIVE=1` disables this connection. Keyring-only profiles, independent stdio servers and other daemons are outside this adapter. If the native switch fails, the panel reports that the default was saved while the app stayed on its account. Check the app's own `/status` after switching. Active native handoffs keep a private `codex-live-handoff.json` journal containing thread/turn IDs and send phases, never prompts or credentials. A lost response, changed login, competing client input or restart during an uncertain Continue requires checking the conversation; ccdeck does not repeat that send automatically. The Accounts row distinguishes waiting, completed switching and an unconfirmed continuation. Independent frontend Stop/input can race the native protocol, which has no atomic handoff or expected-idle start; strict cancellation coordination requires frontend cooperation.
|
|
@@ -401,17 +477,19 @@ Opening Radio asks the public [Radio Browser](https://www.radio-browser.info/) d
|
|
|
401
477
|
|
|
402
478
|
Account switching changes the login used by supported Codex sessions, and managed terminal continuation can submit Continue. The deck also writes 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.
|
|
403
479
|
|
|
480
|
+
A [terminal pane](#terminal) is where the deck does write to a session, because that is what a terminal is for: what you type there, and a reply sent from **Chat**, reaches that session as it would from any terminal. **New session** starts `claude` or `codex` in the folder you chose, with the options you picked. **Rename** keeps the name in `session-names.json`, in the deck's data directory, and also writes it into the session's own conversation: a title line appended to Claude Code's transcript, or Codex's thread name, set through Codex itself. The terminal engine lives in `engine/`, in the same data directory.
|
|
481
|
+
|
|
404
482
|
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.
|
|
405
483
|
|
|
406
484
|
**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.
|
|
407
485
|
|
|
408
|
-
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
|
|
486
|
+
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**, with its **Clear…** button; 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)).
|
|
409
487
|
|
|
410
|
-
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 or one of the two quota notifications is on, quota reads to Anthropic and OpenAI signed with your own credentials — that is where those numbers live. While the page is open, and while the desktop app has a session running or waiting, it also reads Anthropic's and OpenAI's public status pages (`status.claude.com`, `status.openai.com`), unsigned, about every three minutes, and once a minute at most while a page is not answering, so an outage on their side shows as a chip in the topbar instead of looking like a fault on yours. While the machine panel is open, on a machine with Claude Code, it times the way to Claude every thirty seconds — a DNS lookup of `api.anthropic.com` and a TCP handshake on port 443, with nothing sent over it — for the panel's latency reading. While the Browser Watch panel is open, it looks up the address of Claude's browser relay, `bridge.claudeusercontent.com`, about every thirty seconds — a DNS query to your resolver — to tell whether a running browser holds a connection to it. The [desktop app](#desktop-app) also asks this repository's GitHub releases for its own updates. With **Local network** on, which it is unless you switch it off, the deck also announces itself to other decks on your local network over UDP (port 45317) and pairs with the ones that answer — see [Local network](#local-network). The deck also sends usage reports to `api.ccdeck.dev`: an install event (naming the ccdeck.dev page the command was copied from, when the command says so with `--ref`, which the site's copy buttons add; a page name and nothing else, sent once; and saying how ccdeck was installed: the macOS one-line `curl` install, the Windows PowerShell one-line `irm` install, a downloaded installer, npx or npm — the one-line installs leave a one-word file, `install-via`, beside the deck's data, which the first report reads and then deletes), an update event (saying how the new version arrived: the deck's own update, the desktop app's updater, npx, npm or a source checkout), one "active" a day, one "uninstall" when you run `ccdeck --uninstall` (which asks, at a terminal, one skippable question about why, from a short list), one "activated" when a new install's first session arrives (how long after the install, in rough buckets such as "under five minutes", and whether it was a Claude or a Codex session), one "rated" if you answer the one question the deck asks about itself after about a week of use — "How useful is ccdeck to you?", 0 to 10, which you can skip — with the number you picked and how many days you had used the deck, as a range (nothing is sent for a question you put off or leave), and the errors it runs into, with every path outside ccdeck's own code, project folder names, the machine name in every web address, every IP address and the machine name a network error carries (the loopback, such as `127.0.0.1:4317`, stays, so a local port error still reads as one), email addresses and keys scrubbed out (a line of ccdeck's own code keeps its place in the package, such as `ccdeck/src/server/tail.mjs:42`, or in the page, such as `<deck>/assets/index-abc.js:1:2345`, so the error still says where it happened). Each carries the version, your OS and CPU architecture, the channel (desktop, npm or a source checkout), your IP address and the machine's rough shape — the OS release on macOS and Windows (such as `macos-15` or `windows-11`), on Linux the distribution and its version as the system names them (such as `ubuntu-24.04` or `arch`, or `omarchy` on Omarchy) and whether it runs under WSL (an error report leaves these three out), the number of CPU cores, the amount of RAM, the locale, the language you chose in the deck's own settings (such as `ro` or `pt-BR`; an error report leaves it out), the shell, the terminal, and the Claude Code and Codex versions. The install, update, active, activated, rated and uninstall reports also carry the runtime and a device fingerprint (a stable hashed machine id); an error report carries neither. The first four also say whether the Claude hooks went in and Codex is being watched, with the daily "active" also carrying how many sessions, subagents and projects you ran on the last day you used the deck, that day's date, and which of the deck's own features you used that day — fixed names such as "usage history" or "account switch", a yes for each and nothing about what you did with them, and whether you had the deck open in the desktop app's window, a browser tab or `ccdeck tui` (a window or tab left open counts for every day it stays open) — plus how the deck held up and what it runs with: how long this run took to start, that day's peak memory and how many events it took in, each as a rough bucket such as "under two seconds" or "256–512 MB", the Claude and Codex plan as its category only (such as "Max 5x" or "Plus", read from the file each CLI keeps beside its login, and nothing else from it), and how many Claude accounts and paired machines the deck holds, as counts — and which trackers have a connection saved in the deck when the report goes out, as the names Jira, GitHub or GitLab and nothing else about them: not the address, the account, the token or
|
|
488
|
+
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`, the [terminal engine](#terminal) from the npm registry only when it is missing and you press **Install the engine** in a terminal pane or **Install** in **Settings › General** (the package's details and that one package, checked against ccdeck's signature before it runs; otherwise npm installs the engine with ccdeck and the desktop app carries it, so the deck fetches nothing for it), and, while the page is open or one of the two quota notifications is on, quota reads to Anthropic and OpenAI signed with your own credentials — that is where those numbers live. While the page is open, and while the desktop app has a session running or waiting, it also reads Anthropic's and OpenAI's public status pages (`status.claude.com`, `status.openai.com`), unsigned, about every three minutes, and once a minute at most while a page is not answering, so an outage on their side shows as a chip in the topbar instead of looking like a fault on yours. While the machine panel is open, on a machine with Claude Code, it times the way to Claude every thirty seconds — a DNS lookup of `api.anthropic.com` and a TCP handshake on port 443, with nothing sent over it — for the panel's latency reading. While the Browser Watch panel is open, it looks up the address of Claude's browser relay, `bridge.claudeusercontent.com`, about every thirty seconds — a DNS query to your resolver — to tell whether a running browser holds a connection to it. The [desktop app](#desktop-app) also asks this repository's GitHub releases for its own updates. With **Local network** on, which it is unless you switch it off, the deck also announces itself to other decks on your local network over UDP (port 45317) and pairs with the ones that answer — see [Local network](#local-network). The deck also sends usage reports to `api.ccdeck.dev`: an install event (naming the ccdeck.dev page the command was copied from, when the command says so with `--ref`, which the site's copy buttons add; a page name and nothing else, sent once; and saying how ccdeck was installed: the macOS one-line `curl` install, the Windows PowerShell one-line `irm` install, a downloaded installer, npx or npm — the one-line installs leave a one-word file, `install-via`, beside the deck's data, which the first report reads and then deletes), an update event (saying how the new version arrived: the deck's own update, the desktop app's updater, npx, npm or a source checkout), one "active" a day, one "uninstall" when you run `ccdeck --uninstall` (which asks, at a terminal, one skippable question about why, from a short list), one "activated" when a new install's first session arrives (how long after the install, in rough buckets such as "under five minutes", and whether it was a Claude or a Codex session), one "rated" if you answer the one question the deck asks about itself after about a week of use — "How useful is ccdeck to you?", 0 to 10, which you can skip — with the number you picked and how many days you had used the deck, as a range (nothing is sent for a question you put off or leave), and the errors it runs into, with every path outside ccdeck's own code, project folder names, the machine name in every web address, every IP address and the machine name a network error carries (the loopback, such as `127.0.0.1:4317`, stays, so a local port error still reads as one), email addresses and keys scrubbed out (a line of ccdeck's own code keeps its place in the package, such as `ccdeck/src/server/tail.mjs:42`, or in the page, such as `<deck>/assets/index-abc.js:1:2345`, so the error still says where it happened). Each carries the version, your OS and CPU architecture, the channel (desktop, npm or a source checkout), your IP address and the machine's rough shape — the OS release on macOS and Windows (such as `macos-15` or `windows-11`), on Linux the distribution and its version as the system names them (such as `ubuntu-24.04` or `arch`, or `omarchy` on Omarchy) and whether it runs under WSL (an error report leaves these three out), the number of CPU cores, the amount of RAM, the locale, the language you chose in the deck's own settings (such as `ro` or `pt-BR`; an error report leaves it out), the shell, the terminal, and the Claude Code and Codex versions. The install, update, active, activated, rated and uninstall reports also carry the runtime and a device fingerprint (a stable hashed machine id); an error report carries neither. The first four also say whether the Claude hooks went in and Codex is being watched, with the daily "active" also carrying how many sessions, subagents and projects you ran on the last day you used the deck, that day's date, and which of the deck's own features you used that day — fixed names such as "usage history" or "account switch", a yes for each and nothing about what you did with them, and whether you had the deck open in the desktop app's window, a browser tab or `ccdeck tui` (a window or tab left open counts for every day it stays open) — plus how the deck held up and what it runs with: how long this run took to start, that day's peak memory and how many events it took in, each as a rough bucket such as "under two seconds" or "256–512 MB", the Claude and Codex plan as its category only (such as "Max 5x" or "Plus", read from the file each CLI keeps beside its login, and nothing else from it), and how many Claude accounts and paired machines the deck holds, as counts — and which trackers have a connection saved in the deck when the report goes out, as the names Jira, GitHub or GitLab and how many of each are saved, as a count capped at 50, and nothing else about them: not the address, the account, the token, or a connection's id or name (when the deck cannot read its list of connections, the report says only that). The fingerprint is a one-way hash of stable machine traits, never those traits in the clear; everything else is coarse counts and short tokens — no path, no project name, no free text. These reports are no longer anonymous: the install id is random, but the fingerprint follows this machine and the server records the IP the report arrives from. What still never leaves is your sessions, prompts, files, project names and paths. The deck has no switch for them; `AGENTS_DECK_NO_REPORTS=1` keeps them off from the first start. While the deck runs it also sends a tiny heartbeat a minute or two after it starts and every few minutes after that, the install id and nothing else, so the count of decks running right now, and how many hours a day a deck stays open, can be seen. **Send feedback** (the Feedback button in the topbar's corner, on a phone too) sends what you write, and any screenshots and contact you add, to the same place, with the ccdeck version and your system (such as `darwin-arm64`), which the dialog names before you send, and, while the usage reports are on, the same device fingerprint they carry, which it does not show; `AGENTS_DECK_NO_REPORTS=1` keeps the fingerprint home and the feedback still goes. As with a report, the server records the IP address it arrives from. The people who make ccdeck read it there and may open a public issue from it, never with the contact you gave or your screenshots. `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; the terminal engine is not fetched either, and the engine can still be installed from a package file you pick.
|
|
411
489
|
|
|
412
490
|
**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.
|
|
413
491
|
|
|
414
|
-
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
|
|
492
|
+
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** in the selection bar (up to 50 top-level issues). **Move…**, in an issue's **⋯**, 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. In an issue's details, **Add a comment** and then **Add comment** posts a comment, and the button that shows its status, then **Apply**, makes one of the transitions Jira offers; one marked *(open in Jira)* needs fields the deck cannot fill. These actions save changes in Jira using your account’s permissions; browsing does not write. Subtasks and epics cannot be moved here, and moving does not change workflow status. A done issue can move between sprints, but not to the backlog, where Jira hides it: change its status first. **Move** puts the issues at the end of the destination, read from Jira's full order rather than the rows on screen; dropping them on an issue's top or bottom half puts them before or after it. A failed or interrupted move refreshes the board; check the result before trying again because Jira may have saved part of the action.
|
|
415
493
|
|
|
416
494
|
Jira comments, status changes and moves retain a small private write receipt in `integrations/jira-write-guard/` until the result is acknowledged. It contains connection and issue identifiers and the operation state, never comment text or tokens. This prevents accidentally repeating a write after a lost response or restart; if the result is uncertain, check Jira before acknowledging it. Native file locking coordinates writes across local processes. If the platform or data filesystem cannot provide that locking, Jira writes are unavailable while browsing remains usable. The native library is bundled with ccdeck, including its supported macOS, Windows and Linux x64/arm64 binaries.
|
|
417
495
|
|
|
@@ -421,7 +499,7 @@ Local network, Claude accounts, Usage and the empty canvas each carry a small **
|
|
|
421
499
|
|
|
422
500
|
## Browser Watch
|
|
423
501
|
|
|
424
|
-
|
|
502
|
+
**Browser watch**, in **More** at the foot of the right stripe (`B`), answers one question: **did something drive your browser while you were away?** Chromium marks the most common way a program goes to an address: a page loaded with the DevTools protocol's `Page.navigate` (what Playwright and Puppeteer navigate with), or by an extension's `tabs.update`, carries the `FROM_API` flag in `visits.transition`, on top of its type (`LINK`, `TYPED` and the rest). So a run of those, in a stretch when nobody opened a page by hand in that profile, is a finding worth showing. The deck has no idle timer: it goes by the history alone.
|
|
425
503
|
|
|
426
504
|
**What it misses.** Not every way a program opens a page sets the flag. A tab opened straight at an address (`Target.createTarget` over the DevTools protocol, or an extension's `tabs.create`), a link a program clicks, and a URL handed to the browser by `open` or `xdg-open` carry none (tested on Google Chrome 155 on macOS and Brave 1.95 on Linux, against Chromium's source). Those pages are not reported, and because any visit without the flag counts as a person at the browser, they can also cancel a finding close to them.
|
|
427
505
|
|
|
@@ -437,6 +515,8 @@ Step by step: [Detect browser automation while you were away](https://ccdeck.dev
|
|
|
437
515
|
|
|
438
516
|
The Accounts panel shows Claude accounts managed by [claude-swap](https://github.com/realiti4/claude-swap) and configured Codex profiles. With both CLIs on a machine, the Claude | Codex switch at the top of the panel (`A`) chooses which you see; it changes the view, not the account in use. On a deck with only Codex, the control on the stripe is **Codex accounts**, also on `A`. Codex profiles support adding accounts, isolated quota checks, a persistent default for new sessions and an **Auto-switch** of their own, shown even with one Codex account: off until you turn it on, it moves the default to another account with room once the default passes your threshold, with the same **Next account**, **Set as home** and **Hold out of rotation** as Claude's. The Claude controls described below continue to use claude-swap.
|
|
439
517
|
|
|
518
|
+
The account you are on stays whole at the top of the panel. Every other account sits under **Other accounts**, one row that says how many of them a switch could reach and opens into the list; point at it for their names. The accounts you can switch to now come first, then the ones not read yet, then the ones waiting on a window or a rate limit, then the ones whose week is spent, and last the ones no switch can reach (held out of rotation, or signed out). Inside each group they keep their slot order. There is no sort menu. While your pointer or keyboard is in the list, the rows stay where they are, and a new reading moves them only once you leave.
|
|
519
|
+
|
|
440
520
|
**Codex continuation:** with Codex Auto-switch enabled, the updated terminal
|
|
441
521
|
integration can continue a managed interactive `codex`, an explicit-ID
|
|
442
522
|
`codex resume <id>`, or `codex exec --json` task on another account after a
|
|
@@ -478,24 +558,24 @@ session to rearm it. Native terminal/protocol resumption was verified against a
|
|
|
478
558
|
local simulated provider and authenticated cross-account inference on macOS.
|
|
479
559
|
Native Windows/Linux TUI behavior remains a separate acceptance check.
|
|
480
560
|
|
|
481
|
-
|
|
561
|
+
For managed installs and upgrades, ccdeck supports claude-swap versions from 0.26 up to, but below, 2. When PyPI can be reached, it installs the exact compatible version it resolved. If the version lookup fails, installation falls back to `claude-swap~=0.26` (0.x). What `cswap --version` reports afterwards has to be that version, or the deck says so and leaves the panel dark rather than driving a copy it cannot account for — this is the tool that holds your Claude logins. The daily upgrade uses the same supported version interval, and what it left behind is written to `~/.agents-deck/cswap-upgrade.json`.
|
|
482
562
|
|
|
483
563
|
The active account is the one Claude Code is signed in to, as `cswap list` shows it, even after a `/login` made outside the deck; when that login is not one of your accounts, the panel says so above the list, with **Add account**.
|
|
484
564
|
|
|
485
565
|
**Switch** on an account's row makes it the active one. New sessions start on it; sessions already running are not restarted, and pick it up on their next message — up to about 30 seconds later on macOS. Because every session on the machine shares that one login, the deck will not switch to an account whose saved login claude-swap has already seen refused: it asks claude-swap to read the account first when a read is due, and if the login has expired the row says so, with **Sign in again**, and nothing moves. When it cannot tell — offline, or claude-swap does not answer in time — the switch goes ahead. **Auto-switch**, off until you turn it on, does the same without a press: about once a minute the deck runs claude-swap's own engine, which, once the active account passes your threshold (90% unless you choose another) of its 5-hour or 7-day window, moves Claude Code to the account with the most room left. Every account keeps its own limits; when no other account is under the threshold, nothing switches. Auto-switch also moves Claude Code off an account whose login has expired, once Claude Code has signed it out and claude-swap's stored copy of it no longer works either, to the account with the most room under the threshold that claude-swap has not set aside and no local `cswap run` session is using; the expired one stays in the list, waiting for you to sign it in again. When Claude Code sessions stop on an expired login or a usage limit, Auto-switch runs once right away instead of waiting for its next minute, and the cards say `Stopped · login expired` or `Stopped · usage limit` until the session does something again: type `continue` in each one once a working login is active. A session running in the background (`claude --bg`, agent view) gets **Continue** on its card instead, enabled once the active account's usage reading shows a working login with room since the stop: it runs Claude Code's own [`claude stop` and `claude --resume <session> --bg`](https://code.claude.com/docs/en/sessions) in the session's folder, and the card says how that went. **Continue stopped background sessions**, in **Settings › General**, off until you turn it on, presses it for you, once per stop; a session that stops again right after is left for you. **Custom…**, last in the threshold picker, takes any whole percent from 50 to 99 and refuses anything else under the field without saving it; the threshold is claude-swap's own setting, kept on this machine.
|
|
486
566
|
|
|
487
|
-
Two choices change where Auto-switch goes, and do nothing while it is off. **Next account**,
|
|
567
|
+
Two choices change where Auto-switch goes, and do nothing while it is off. **Next account**, in the popover that opens from **Auto-switch**'s name, is **Most room left** — claude-swap's own pick, and the default — or **Soonest weekly reset**: the account whose 7-day window resets soonest, as long as that is within 95 hours, so quota that is about to reset is used first. With it, the deck also moves below the threshold, to an account that resets at least an hour sooner than the one in use, and never sooner than half an hour after the last move. **Set as home**, in an account's **⋯**, marks the row with a small house: Auto-switch takes you there, does not move you off it before the threshold, and comes back once its 5-hour window has reset. Only an account comfortably under the threshold, read in the last 15 minutes, signed in, in rotation, not set aside by claude-swap and not in use in a local `cswap run` session is moved to. An account reported as active on another paired device remains eligible for Home and Soonest weekly reset. If Home has stale readings, Auto-switch asks claude-swap to collect before choosing a weekly alternative; if Home is still unavailable afterward, it uses the alternative. A switch you make yourself is left alone until that account reaches the threshold, or until you set a home or pick a rule again. When no account fits either rule, claude-swap decides, as before. Both choices are kept on this machine. These rules are Claude's. Codex's Auto-switch has the same two choices, more simply: **Soonest weekly reset** counts only when the account in use passes the threshold, and Auto-switch comes back home once home has room again, not after a 5-hour window.
|
|
488
568
|
|
|
489
|
-
A small **shield** on an account's row says that account's organization turns on Claude Code's telemetry export, before you switch to it
|
|
569
|
+
A small **shield** on an account's row says that account's organization turns on Claude Code's telemetry export, before you switch to it. Point at it or focus it for the whole sentence — the organization, what is sent, where to, and how long ago the deck saw it; a click opens the same sentence as **Organization telemetry**, on touch too. A Team or Enterprise organization can turn this on for every member, and Claude Code applies it without asking in the VS Code panel, the desktop app and `claude -p`. The deck learns it from `~/.claude/remote-settings.json`, which describes whichever organization last fetched it, so it records the file only once it was written after claude-swap's last switch and the live login is that account's; an organization it has not seen that way yet shows nothing, which means unknown, not off. While Auto-switch is on, that sentence also says how to keep it off such an account: **Hold out of rotation**, in the account's ⋯ menu.
|
|
490
570
|
|
|
491
|
-
**Account capacity**,
|
|
571
|
+
**Account capacity**, in **More** at the foot of the left stripe, says how many accounts are ready and what their 5-hour and 7-day windows have left. **Reset calendar**, beside it in that menu, lays out today and the next six days, with each account's 7-day reset on the day it falls, and marks the readings that need refreshing.
|
|
492
572
|
|
|
493
|
-
**Account notifications** are four switches in **Settings › Notifications** (the
|
|
573
|
+
**Account notifications** are four switches in **Settings › Notifications** (at the foot of the left stripe, or `Cmd+,`; `Ctrl+,` on Windows and Linux), each on its own and none of them tied to **While the deck is closed**: they are sent whether the deck is open or not, because nothing on the page says them. The desktop app shows them as ccdeck, without a sound.
|
|
494
574
|
|
|
495
|
-
- **Account
|
|
575
|
+
- **Account switched**, on unless you turn it off. When Auto-switch moves Claude Code, or Codex's default, to another account, one notification says where to and, when the engine's own reading shows it, why: `Switched to work · personal@example.com reached 90%`, `Back on work · your home account` or `Switched to side · weekly limit resets in 1d 7h`, with an account's alias when it has one. A switch away from an expired login says so: `Switched to work · personal@example.com's login expired, sign in again to use it`; and when no other account is ready to take over, that is said once rather than every minute. When the account it moved to belongs to an organization the deck has seen turn telemetry on, a second line says what it sends from the next session, and where: `Acme's telemetry is on for new sessions: it sends your prompts and tool details to 192.0.2.16:4317`. A switch you make yourself is not announced: the row you pressed becomes the active one, and the shield beside its name says what its organization sends.
|
|
496
576
|
- **Quota at 90% and 100%**, off until you turn it on. When a window of the Claude or Codex account you are on reaches 90%, and once more at 100%: Claude's 5-hour, 7-day and per-model windows, and every Codex window the Usage panel shows, the extra limits included — `5-hour usage reached 90% · resets in 2h 14m`. Only the account in use is watched, not every account you have stored. When reaching it is what makes Auto-switch move the account, the switch notification says it and this one is not sent, unless the switch notification is off.
|
|
497
|
-
- **Quota
|
|
498
|
-
- **Sessions stopped
|
|
577
|
+
- **Quota back**, off until you turn it on. When one of those windows that had reached 90% starts over: `5-hour window available again`. A window that never got that high resets without a word.
|
|
578
|
+
- **Sessions stopped by a login or a limit**, on unless you turn it off. When Claude Code sessions stop on an expired login or a usage limit, one notification for all of them says how many stopped and to type `continue` in each. When the Auto-switch run that follows moves the account, the switch notification says it instead, so one incident is one notification.
|
|
499
579
|
|
|
500
580
|
Each is said once per window. The deck writes what it has said to `account-notify.json`, beside its settings, so a restart does not say it again, and nothing said about one account counts for another. With either quota switch on, the deck reads the quota of the accounts in use about every two minutes even while no page is open — the same reads, through the same caches and limits, as the Usage panel's. `AGENTS_DECK_NO_NOTIFY=1` keeps all four off.
|
|
501
581
|
|
|
@@ -503,7 +583,7 @@ Each is said once per window. The deck writes what it has said to `account-notif
|
|
|
503
583
|
|
|
504
584
|
**`share`** on an account produces a `ccdeck2:…` blob to paste into another deck's **`+` → Paste a share**.
|
|
505
585
|
|
|
506
|
-
|
|
586
|
+
**⋯ › Share accounts with another deck**, 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.
|
|
507
587
|
|
|
508
588
|
**On macOS, the login itself lives in the Keychain.** If ccdeck is running from SSH, a LaunchAgent, or another session that cannot open that Keychain, the account may still be valid while this process cannot read or share it. ccdeck does not call that login expired: the account's row says **Keychain unreadable**, and Local network says **cannot share here**. It refuses clipboard and LAN exports from it, and tells you to start ccdeck from a Terminal window on the Mac itself. Once claude-swap can read the Keychain again, the account becomes shareable normally.
|
|
509
589
|
|
|
@@ -514,7 +594,7 @@ An import adds what is missing and leaves a working account exactly as it is. Th
|
|
|
514
594
|
|
|
515
595
|
**Rename**, **Move to slot…** and **Remove** are on the same row menu. Removal takes two clicks and cannot be undone. Removing the active account leaves Claude Code signed in as it; when that login is the expired one, the deck moves Claude Code to the working account with the most room left that claude-swap has not set aside and no local `cswap run` session is using, or says that none could take over.
|
|
516
596
|
|
|
517
|
-
Step by step: [Switch between multiple Claude Code accounts](https://ccdeck.dev/guides/claude-accounts/) · [Copy
|
|
597
|
+
Step by step: [Switch between multiple Claude Code accounts](https://ccdeck.dev/guides/claude-accounts/) · [Copy a Claude or Codex login to another machine](https://ccdeck.dev/guides/move-an-account/)
|
|
518
598
|
|
|
519
599
|
## From the terminal
|
|
520
600
|
|
|
@@ -533,7 +613,7 @@ ccdeck open the deck in your browser — over SSH, the line th
|
|
|
533
613
|
ccdeck tui all of the above, and the machine, on one screen that stays up
|
|
534
614
|
```
|
|
535
615
|
|
|
536
|
-
**`ccdeck tui`** keeps the accounts, the sessions waiting on you and the machine 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. **m** opens the selected account's actions, as in the deck's account menu: set or clear home (⌂), hold out of Auto-switch's rotation (‖) or put back, rename, move to another slot, and remove, which asks first; **h**, **o**, **n**, **v** and **x** reach them straight from the list. While nobody is waiting on you, the room goes to the machine's charts: all cores and the busiest one, memory, swap, queued work, temperature and throttling, live, or the last hours by the minute with **t**. 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.
|
|
616
|
+
**`ccdeck tui`** keeps the accounts, the sessions waiting on you and the machine 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. **m** opens the selected account's actions, as in the deck's account menu: set or clear home (⌂), hold out of Auto-switch's rotation (‖) or put back, rename, move to another slot, and remove, which asks first; **h**, **o**, **n**, **v** and **x** reach them straight from the list. While nobody is waiting on you, the room goes to the machine's charts: all cores and the busiest one, memory, swap, queued work, temperature and throttling, live, or the last hours by the minute with **t**. With no deck running it reads claude-swap's store and **d** starts one in the background. When the deck restarts underneath it, the screen finds the new one and keeps updating. 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.
|
|
537
617
|
|
|
538
618
|
**Codex accounts**: once the deck has one, the title reads **Claude | Codex** and **←** / **→** move between the tabs, as in any tab bar (**c** jumps to Codex's list and back). There **Enter** makes the selected account Codex's default, **a** turns Codex Auto-switch on or off, and **m** offers sign in again, rename, set or clear home (⌂), hold out of rotation and remove, for accounts added in the deck. **+**, or **Enter** on a signed-out account, shows a sign-in link and a code: open the link in any browser, a phone included, type the code there, and the sign-in finishes by itself.
|
|
539
619
|
|
|
@@ -541,7 +621,7 @@ ccdeck tui all of the above, and the machine, on one screen t
|
|
|
541
621
|
|
|
542
622
|
**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.
|
|
543
623
|
|
|
544
|
-
`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.
|
|
624
|
+
`swap` and `use` are other names for `switch`, `account` and `ls` for `accounts`, `quota` for `usage` 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.
|
|
545
625
|
|
|
546
626
|
**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.
|
|
547
627
|
|
|
@@ -576,17 +656,17 @@ Four pictures, which are also the guide the section opens from `See how it works
|
|
|
576
656
|
</tr>
|
|
577
657
|
</table>
|
|
578
658
|
|
|
579
|
-
**On each machine, in order:** open the Accounts panel (`A`), press **Local network** at its foot,
|
|
659
|
+
**On each machine, in order:** open the Accounts panel (`A`), press the sliders button beside **Local network** at its foot, and tick the logins this machine may hand out. The section is on unless somebody switched it off. The two decks find each other over a UDP beacon on port 45317 and ask each other to pair; press `accept` where it is asked, and from then on every paired deck is asked once a minute for the ticked logins this deck is missing or has expired.
|
|
580
660
|
|
|
581
|
-
**When they do not find each other** — a VPN, a guest network, two subnets —
|
|
661
|
+
**When they do not find each other** — a VPN, a guest network, two subnets — **Add a deck**, the link button 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.
|
|
582
662
|
|
|
583
|
-
**What is shared, and with whom.** Nothing until you tick a login, and then only that login, and only with paired decks. A login ticked on one deck arrives on every deck paired with it: added where it is missing, repaired where it has expired, and never in place of one that still works. The deck asks the machines it finds, and a machine that is asked waits for somebody there to press `accept` unless its `Say yes to every deck that asks` switch, in the same dialog, is on. That switch starts on, so your own machines pair without a press. It also means a deck the switch pairs can add the logins ticked on it to this machine, and Auto-switch, if it is on, may later move Claude Code or Codex to one of them — so on a network you do not own, turn the switch off. What still takes a person is the tick: a paired deck is handed nothing until somebody ticks a login here. A login that arrives from a deck somebody here accepted
|
|
663
|
+
**What is shared, and with whom.** Nothing until you tick a login, and then only that login, and only with paired decks. A login ticked on one deck arrives on every deck paired with it: added where it is missing, repaired where it has expired, and never in place of one that still works. The deck asks the machines it finds, and a machine that is asked waits for somebody there to press `accept` unless its `Say yes to every deck that asks` switch, in the same dialog, is on. That switch starts on, so your own machines pair without a press. It also means a deck the switch pairs can add the logins ticked on it to this machine, and Auto-switch, if it is on, may later move Claude Code or Codex to one of them — so on a network you do not own, turn the switch off. What still takes a person is the tick: a paired deck is handed nothing until somebody ticks a login here. A login that arrives from a deck somebody here accepted, paired by invite or reached by its typed address is ticked here too, so this machine can repair the next one; a deck the switch paired is handed only the logins a person ticked on this deck, never the ones that were ticked by arriving, so untick and tick such a login again to hand it to those decks as well — and what a deck the switch paired brings here is not ticked here at all. 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.
|
|
584
664
|
|
|
585
665
|
**A ticked login goes out even while this machine is signed in to it** (since 3.48.1). That has a cost: a Claude login renews once, so two machines on one copied login race at each renewal and the one that renews second is signed out (“Login expired”). The deck does not warn just because a paired deck is on the same account; if a login does expire, its row says **Login expired** like any other. To keep the login in use on this machine, turn off **Send the login this deck is using too** in the same dialog. The dialog then marks it **in use here · not sent** when it is ticked, a paired deck reads it as **in use there** (or does not see it, while this deck hides which account it is on), and it goes out like any other ticked login as soon as this machine switches to another account; a paired deck that already holds a copy of that login, from before this machine switched to it, can still renew it first and sign this machine out. A deck updated from an earlier version starts with the switch on, whatever it showed before: only a choice made on 3.48.1 or later is kept.
|
|
586
666
|
|
|
587
667
|
On a Mac, **cannot share here** is different from **expired here**. It means this ccdeck process cannot read the Keychain copy, so that machine is not used as a credential source and another deck does not keep trying to “repair” the same healthy slot every minute. A LAN import is checked after it lands too; if the receiving Mac still cannot read the Keychain, the round reports that problem instead of claiming the login was repaired.
|
|
588
668
|
|
|
589
|
-
Step by step: [Repair
|
|
669
|
+
Step by step: [Repair Claude and Codex logins across machines](https://ccdeck.dev/guides/local-network/)
|
|
590
670
|
|
|
591
671
|
## Options
|
|
592
672
|
|
|
@@ -726,8 +806,8 @@ Environment:
|
|
|
726
806
|
| `CODEX_HOME` | Override `~/.codex` |
|
|
727
807
|
| `AGENTS_DECK_NO_CODEX_LIVE` | Set to `1` to disable switching an existing native shared Codex app-server |
|
|
728
808
|
| `CCDECK_CODEX_HOMES` | JSON array of additional absolute Codex home directories to monitor and list in Accounts; restart ccdeck after changing it |
|
|
729
|
-
| `AGENTS_DECK_NO_INSTALL=1` | Never install or update claude-swap / ccusage or the terminal's `ccdeck`, never ask npm about releases, never read the status pages, and never send reports or feedback |
|
|
730
|
-
| `AGENTS_DECK_NO_DOWNLOAD=1` | Never download the `uv` binary, but keep the managed installs |
|
|
809
|
+
| `AGENTS_DECK_NO_INSTALL=1` | Never install or update claude-swap / ccusage or the terminal's `ccdeck`, never download the terminal engine, never ask npm about releases, never read the status pages, and never send reports or feedback |
|
|
810
|
+
| `AGENTS_DECK_NO_DOWNLOAD=1` | Never download the `uv` binary, `macmon` or the terminal engine, but keep the managed installs |
|
|
731
811
|
| `AGENTS_DECK_NO_UPDATE_CHECK=1` | Don't ask npm about releases, but keep everything else |
|
|
732
812
|
| `AGENTS_DECK_NO_STATUS=1` | Don't read Anthropic's and OpenAI's status pages, so no incident chip appears |
|
|
733
813
|
| `AGENTS_DECK_NO_FRESHEN=1` | Never nudge claude-swap to collect usage early |
|
|
@@ -738,7 +818,7 @@ Environment:
|
|
|
738
818
|
| `AGENTS_DECK_CSWAP` | Full path to `cswap`, when it lives somewhere unusual |
|
|
739
819
|
| `AGENTS_DECK_CLAUDE` | Full path to the `claude` CLI |
|
|
740
820
|
| `AGENTS_DECK_CCUSAGE` | Full path to your own `ccusage`, used ahead of everything else |
|
|
741
|
-
| `AGENTS_DECK_SKILL_HOOK` | Set to `0` to leave out the `UserPromptExpansion` hook, which lets Skill activity count the slash commands you type. On by default, and added only where every Claude Code found is 2.1.116 or newer
|
|
821
|
+
| `AGENTS_DECK_SKILL_HOOK` | Set to `0` to leave out the `UserPromptExpansion` hook, which lets Skill activity count the slash commands you type. On by default, and added only where every Claude Code found is 2.1.116 or newer. Unset, empty or `1` is on; any other value turns it off |
|
|
742
822
|
| `CLAUDE_SWAP_BACKUP` | Override the claude-swap store root the Accounts panel reads |
|
|
743
823
|
| `CCDECK_HOME` | Put everything the deck writes — its state and its log — under this directory instead of the platform default. Wins over every rule below it |
|
|
744
824
|
| `CLAUDE_CONFIG_DIR` | Override `~/.claude` — the hook entry, the event log and everything else the deck writes move with it |
|
|
@@ -752,7 +832,7 @@ Open **Usage → By session** and select a Claude Code or Codex row to inspect i
|
|
|
752
832
|
|
|
753
833
|
For Codex, **Estimate using** compares ccusage's automatic estimate with Standard, Fast or Flex scenarios. Automatic pricing follows recorded settings where available and may use the current Codex config for unmarked usage. Scenarios apply one mode to the whole session, use ccusage's model-specific multipliers, and never change Codex settings or billing. Requested modes do not confirm the tier actually billed. This requires a ccusage version that supports the chosen report; older copies show an update message rather than silently substituting another mode. See [ccusage's Codex pricing behavior](https://ccusage.com/guide/codex/).
|
|
754
834
|
|
|
755
|
-
|
|
835
|
+
**Quota history**, at the foot of the Usage panel, opens the Claude and Codex quota readings the deck has already taken for the account in use, window by window over time, with a dashed line for even use until the reset — a guide, not a forecast. Recording it adds no requests; the readings are kept in `quota-history.json` in the data directory for 35 days, up to 2 MB. Under each 7-day bar, a line says how full the last weeks were when they reset: the deck keeps the last reading of each window, for every account, in `quota-closes.json` for 400 days, and up to 45 minutes before a 7-day window resets it asks for one fresh reading if the last is over an hour old — one collection a week per account.
|
|
756
836
|
|
|
757
837
|
Step by step: [See Claude Code and Codex cost and quota left](https://ccdeck.dev/guides/cost-and-quota/)
|
|
758
838
|
|
|
@@ -772,17 +852,30 @@ Apart from that block, it removes the hook entries and nothing else. The forward
|
|
|
772
852
|
(`~/.claude/agent-dag/hook.js`), the discovery directory around it, the events
|
|
773
853
|
log, the deck's own state, Tool activity's history included, and the tools
|
|
774
854
|
ccdeck installed for you — claude-swap, ccusage, and a `uv` binary if it had to
|
|
775
|
-
fetch one — are all left in place
|
|
855
|
+
fetch one — are all left in place. claude-swap has its own uninstaller, below;
|
|
856
|
+
ccusage and `uv` live in `~/.agents-deck/` and go with that folder.
|
|
776
857
|
|
|
777
|
-
|
|
858
|
+
Four directories hold ccdeck's own files, and the second one matters most:
|
|
778
859
|
`~/.claude/agent-dag/` (the forwarder and the discovery directory), the
|
|
779
|
-
platform's **data** directory,
|
|
860
|
+
platform's **data** directory, the platform's **log** directory, and
|
|
861
|
+
`~/.agents-deck/` (the tools the deck manages).
|
|
780
862
|
|
|
781
863
|
| | macOS | Windows | Linux |
|
|
782
864
|
|---|---|---|---|
|
|
783
|
-
| data — `prefs.json`, `tool-audit/` | `~/Library/Application Support/ccdeck` | `%LOCALAPPDATA%\ccdeck\Data` | `$XDG_DATA_HOME/ccdeck` |
|
|
865
|
+
| data — `prefs.json`, `tool-audit/`, `engine/` | `~/Library/Application Support/ccdeck` | `%LOCALAPPDATA%\ccdeck\Data` | `$XDG_DATA_HOME/ccdeck` |
|
|
784
866
|
| log — `events.jsonl` | `~/Library/Logs/ccdeck` | `%LOCALAPPDATA%\ccdeck\Log` | `$XDG_STATE_HOME/ccdeck` |
|
|
785
867
|
|
|
868
|
+
`engine/` holds the terminal engine, and `engine-minimum-version` beside it the
|
|
869
|
+
oldest engine the deck will run again. **Settings › General › Experimental › Remove the engine**
|
|
870
|
+
empties `engine/`, and the engine installs again the next time a terminal opens.
|
|
871
|
+
All of them stay after `npm uninstall -g ccdeck`; delete them
|
|
872
|
+
with the data folder.
|
|
873
|
+
|
|
874
|
+
`--uninstall` stops the deck, not the sessions it started. On Linux and macOS, a
|
|
875
|
+
session started in a [terminal pane](#terminal) runs in the deck's own tmux and
|
|
876
|
+
keeps running after the deck stops: end each one first, with `/exit` or `Ctrl+D`
|
|
877
|
+
in its pane.
|
|
878
|
+
|
|
786
879
|
`prefs.json` is the one to delete deliberately: it holds this deck's **Local
|
|
787
880
|
network private key**, the one every deck you paired with has pinned. Leaving it
|
|
788
881
|
behind leaves that identity on the machine. (`~/.agents-deck/` holds the managed
|
|
@@ -808,8 +901,8 @@ The data directory also holds `quota-history.json`, `quota-closes.json` and
|
|
|
808
901
|
Tool activity's `tool-audit/` folder — up to 90 days of which tools and
|
|
809
902
|
commands your agents ran, and how long they took. None of them holds a key, so
|
|
810
903
|
`--uninstall` leaves them, and so does `--purge` below, which deletes only the
|
|
811
|
-
files that can hold one. **Clear
|
|
812
|
-
history
|
|
904
|
+
files that can hold one. **Clear…** on **Clear
|
|
905
|
+
history** under **Settings › Data › Tool history** empties the tool history
|
|
813
906
|
while the deck runs; deleting the folder removes it.
|
|
814
907
|
|
|
815
908
|
`uv tool uninstall claude-swap` (or `pipx uninstall claude-swap`) removes the
|
|
@@ -837,7 +930,7 @@ Step by step: [Uninstall ccdeck and remove its Claude Code hook](https://ccdeck.
|
|
|
837
930
|
|
|
838
931
|
## Updating
|
|
839
932
|
|
|
840
|
-
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. To ask immediately,
|
|
933
|
+
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. To ask immediately, press **Check for updates** in What's new (**Open** beside What's new in **Settings › About**, or the version chip, which the topbar shows only when there is news about the version), which runs the same check under the same limits and offers the same update as the banner below. In the desktop app, whose deck leaves updates to the app, **Check for updates** asks the app's own updater instead, and What's new says where that check stands.
|
|
841
934
|
|
|
842
935
|
What the banner offers depends on how this copy was installed:
|
|
843
936
|
|
|
@@ -854,6 +947,8 @@ Nothing is installed unless you click, or, with **Update when idle** on (Setting
|
|
|
854
947
|
|
|
855
948
|
**The `ccdeck` your terminal starts** is a separate copy whenever the deck runs from the desktop app, npx or a checkout, and it does not move when they do. When the first `ccdeck` on your PATH is older than the deck, the deck runs the same install for it — `npm install -g --prefix <its prefix> ccdeck@latest`, into the prefix that copy lives in — five minutes after it starts, without waiting for an idle moment, since nothing of the deck's restarts. It does that only for a global npm install of `ccdeck` whose folders you can write, under the same switch (the desktop app shows none, and keeps it on), and never with `AGENTS_DECK_NO_INSTALL=1`. A root-owned prefix, pnpm, yarn or bun, or an old `agents-deck` or `agent-dag` install is left to you: **Settings › About** shows the command, and why an automatic install failed when one did. An install that failed is tried again after half an hour.
|
|
856
949
|
|
|
950
|
+
**The terminal engine updates with ccdeck.** Each ccdeck version names the engine version it runs. An npm update installs that engine beside the new ccdeck, and the desktop app's update carries it. The deck moves it into `engine/` the next time a terminal asks for it, after the same checks, and never goes back to an older engine. **Check for an update**, under **Terminal engine** in **Settings › General › Experimental**, installs the version this ccdeck names when the one in place is older.
|
|
951
|
+
|
|
857
952
|
### Windows update says installed but the version stays old
|
|
858
953
|
|
|
859
954
|
Newer ccdeck versions target the npm prefix of the running copy and verify its version after installation. A different Node installation on PATH no longer redirects that update into another copy.
|
|
@@ -870,7 +965,7 @@ For the **desktop app**, run the latest [Windows installer](https://github.com/B
|
|
|
870
965
|
|
|
871
966
|
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.
|
|
872
967
|
|
|
873
|
-
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.
|
|
968
|
+
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. **Update when idle**, in **Settings › General › Updates**, turns that off; the deck keeps the choice in its `prefs.json`, so every tab and the next start agree. Under `--no-persist` a restart is refused outright — with no event log there is nothing to replay, and the canvas would be gone.
|
|
874
969
|
|
|
875
970
|
Step by step: [Update ccdeck to the latest version](https://ccdeck.dev/guides/update-and-restart/)
|
|
876
971
|
|
|
@@ -936,12 +1031,21 @@ limit resumes on another account with one Continue, and **Continue stopped
|
|
|
936
1031
|
background sessions** (**Settings › General**) presses Continue for you.
|
|
937
1032
|
Otherwise Auto-switch only changes the account in use; running Claude Code
|
|
938
1033
|
sessions pick it up on their next message.
|
|
1034
|
+
A [terminal pane](#terminal) is different on purpose: it is the session's own
|
|
1035
|
+
terminal, so what you type there, or reply from **Chat**, reaches the agent as
|
|
1036
|
+
it would in any terminal.
|
|
939
1037
|
|
|
940
1038
|
**Does it need an account, an API key or a config file?**
|
|
941
1039
|
None of the three. `npx ccdeck` and it runs.
|
|
942
1040
|
|
|
943
1041
|
**macOS, Linux, Windows?**
|
|
944
|
-
All three, and each release is tested on all three.
|
|
1042
|
+
All three, and each release is tested on all three. The [terminal](#terminal)
|
|
1043
|
+
works on all three too; Windows on ARM has none yet.
|
|
1044
|
+
|
|
1045
|
+
**Is all of it open source?**
|
|
1046
|
+
ccdeck is, under the AGPL-3.0. The terminal engine that comes with it is a
|
|
1047
|
+
separate program under its own licence; [License](#license) says how the two
|
|
1048
|
+
fit together.
|
|
945
1049
|
|
|
946
1050
|
**What is the difference between `ccdeck`, `agents-deck` and `agent-dag`?**
|
|
947
1051
|
One deck, three names on npm. `ccdeck` is the one to use; the other two are the
|
|
@@ -976,6 +1080,13 @@ Copyright © 2026 [Bargan Constantin](https://github.com/BarganConstantin).
|
|
|
976
1080
|
See [LICENSE](./LICENSE) for the full license text and
|
|
977
1081
|
[LICENSING.md](./LICENSING.md) for licensing history and additional details.
|
|
978
1082
|
|
|
1083
|
+
The terminal engine that comes with ccdeck is not part of ccdeck's code, and the
|
|
1084
|
+
AGPL does not cover it: it is a separate program under its own licence, which
|
|
1085
|
+
its package carries as `LICENSE`, beside `THIRD-PARTY-NOTICES` for the
|
|
1086
|
+
open-source code it contains.
|
|
1087
|
+
[LICENSING.md](./LICENSING.md#the-terminal-engine) says how the two fit
|
|
1088
|
+
together.
|
|
1089
|
+
|
|
979
1090
|
ccdeck bundles third-party code under permissive licences (MIT, ISC,
|
|
980
1091
|
BSD-3-Clause). Those licences are theirs, not ccdeck's, and their notices are
|
|
981
1092
|
preserved in [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
|