ccdeck

Update ccdeck to the latest version

To update ccdeck, use the notice under the topbar that appears when npm has a newer release: click Update & restart on a deck started with npx, or Update now, then Restart now, on a global install; the deck comes back on the new version.

Claude Code and Codex Checked against ccdeck 3.81.3 on

You will

Before you start

Steps

  1. See which version is running

    The version chip, at the left end of the topbar, shows the version the deck runs. In a terminal:

    npx ccdeck --status

    It lists each running deck with its version. It does not say whether a newer release exists.

    More about the version commands

    --status also shows each deck’s pid, uptime and address, and marks the one a plain npx ccdeck would open with opens this one. It starts nothing.

    npx ccdeck --version answers a different question: it prints the version of the copy npx ran, not the version of the deck that is running.

  2. Read the update notice

    When npm has a newer release, the version chip turns amber, and a notice appears under the topbar.

    The left end of the topbar: the ccdeck mark and name, then the version chip reading v3.81.2 beside an amber dot. Under it, beside the top of the stripe on the left with its Accounts icon, the notice: ccdeck v3.81.3 is out — you are on v3.81.2, an Update & restart button, the words npx cannot upgrade in place, so the deck re-runs:, the command npx -y ccdeck@latest with COPY beside it, and a × at the end. Open the full-size picture
    Demo data The notice on a deck started with npx ccdeck. The newer release on npm was supplied to the page for this picture.

    No notice yet? Click the version chip: it asks npm at once and opens What’s new, where the menu behind ⋯, at its top right, gives the answer.

    More about update checks

    The deck asks npm when it starts, and about once an hour after that. While a deck tab is open, the page has it ask again every 15 to 20 minutes. Check for updates, in that ⋯ menu, asks again at once.

    When npm has a newer release, a line at the top of What’s new offers the notice’s own button, or its command. In the desktop app, Check for updates asks the app’s own updater instead.

    Hover over the chip to see what npm last answered. A deck started with AGENTS_DECK_NO_UPDATE_CHECK=1 or AGENTS_DECK_NO_INSTALL=1 never asks, and its What’s new has no Check for updates.

  3. Click the update button

    On a deck started with npx ccdeck, click Update & restart. The deck fetches the new version, then restarts on it, at the same address.

    On a global install, click Update now. npm installs the new version into the deck’s own copy, and the notice changes to a restart notice.

    Updates go to the newest release only. The deck never installs a version you choose, or goes back to an earlier one.

    More about updating from a terminal

    Run the command the notice shows; click it there to copy it. For a deck started with npx, npx -y ccdeck@latest stops the older deck, printing a line such as stopped the deck on 4317 with it was v3.81.2, and starts the new version. Nothing is installed globally.

    For a global install, run npm i -g ccdeck@latest. The running deck’s notice then changes to the restart notice, or running ccdeck replaces that deck with the new version in the same way.

    The ccdeck your terminal starts is a separate copy when the deck runs with npx or the desktop app. When it is an older global npm install in a folder you can write to, the deck updates it about five minutes after it starts, unless Update when idle is off. Otherwise Settings › About shows the command.

  4. Restart into the new version

    After a global install, the deck runs its old code until it restarts. A deck started with npx skips this step: its update is the restart.

    The left end of the topbar: the ccdeck mark and name, then the version chip reading v3.81.2 beside an amber dot. Under it, beside the top of the stripe on the left with its Accounts icon, the notice: v3.81.3 is installed — this deck still runs v3.81.2, a Restart anyway button, the words 2 agents are running — their events during the restart are lost, a switch turned on beside the words auto when idle, and a × at the end. Open the full-size picture
    Demo data Two agents are still at work, so the button reads Restart anyway. The installed update was supplied to the page for this picture.

    Click Restart now. While agents are running, it reads Restart anyway: their events during the restart are lost. The deck is down for a second or so, and the tab reconnects by itself.

    More about the restart

    The button also reads Restart anyway while the canvas is paused, when running agents cannot be seen.

    The deck comes back on the same port and redraws the canvas from its event log. The tab reloads into the new version’s page.

    Claude Code’s hook sends each event once and does not retry, so what it sends in the gap never reaches the canvas. A tool call caught in the middle stays drawn as running until the deck clears it.

  5. Choose whether the deck updates itself

    Click Settings at the right of the topbar, then General. Under Updates, the Update when idle switch turns automatic updates on and off. It is on until you turn it off.

    The switch beside auto when idle, in the restart notice, is the same switch.

    While it is on, a tab showing the notice restarts the deck once nothing has run for 30 seconds. While nobody is looking, the deck also updates and restarts by itself. With it off, the deck updates only when you click.

    More about updating while you are away

    The switch is a setting of the deck, not of your browser. A deck started with --no-persist never updates itself. Nobody is looking when no deck tab is both visible and in focus, no session is in the middle of a turn, and nothing has come from any session for 30 seconds. The deck does nothing in its first 5 minutes after starting, checks once a minute, and leaves an update that did not work alone for 30 minutes before it tries that one again.

    The words beside the switch count down to the restart. × puts the notice away for that version in this browser and stops the countdown, but not the updates while you are away. Clicking the version chip brings the notice back.

  6. Read what changed

    The first time this browser opens the updated deck, What’s new opens if a release since the last one it saw has notes.

    The What’s new dialog, headed v3.81.3, with a ⋯ button wearing its focus ring and a × at its top right. Its first line reads Changes since v3.81.2. Then the release’s summary, More reliable Codex switching and quieter account rows, and its one main change beside an accounts icon: More reliable Codex account switching, and under it: ccdeck retries temporary connection failures before switching the open Codex app. Below it, folded, 2 more improvements with Show details. At its foot, Release history with an arrow, Take the tour and, at the right, Done.
    Demo data Its first line says why it opened. The browser’s record of the last release it saw, with the deck’s answer that it is up to date and can restart, was supplied to the page for this picture.

    Click the version chip to open it again. Restart ccdeck, in its ⋯ menu, restarts the deck without an update.

    More about What’s new

    Opened from the chip, it shows the running release’s own notes. A release that marks its main changes shows up to three first, and the rest under Show details. After several releases, the newest comes first. Under Earlier in this upgrade, each older one shows what must stay in sight, such as a changed setting, or every note if it marks none; the rest wait under Other changes since v…. Release history, at its foot, opens every release’s notes on ccdeck.dev. Done, × or Esc closes it.

    Restart ccdeck is the same restart as the restart notice’s, with no warning about running agents. It is there only on a deck that can restart, and not while the desktop app has an update ready or What’s new offers Update now or Update & restart.

If something goes wrong

The notice shows a command to run yourself

This copy cannot update itself, or the update failed, and the notice says why. Copy the command and run it in a terminal.

The notice says to restart, and has no button

The deck was started with --no-persist, or cannot write its event log, so the page cannot restart it. Stop it with npx ccdeck --stop and start it again.

npx ccdeck opened the old deck again

The copy npx ran is not newer than the running deck. Run npx -y ccdeck@latest, not --new, which replaces every running deck with the copy you typed, even an older one.

The deck updated or restarted while you were away

Automatic updates are on. Turn off Update when idle in Settings › General: the deck then updates only when you click.

On Windows, an update says installed but the version stays old

Before 3.81.1, ccdeck could install the update into another Node.js on your PATH. Update the copy behind the ccdeck command once, in PowerShell, then close and reopen ccdeck:

npm install -g --prefix (Split-Path (Get-Command ccdeck.cmd).Source) ccdeck@latest

Something else? See Troubleshoot ccdeck: status, logs, port and hooks.

Next

All guides Troubleshoot Updating in the README