ccdeck

Install the ccdeck app on Mac, Windows or Linux

The ccdeck desktop app is the same dashboard without Node.js: download it for macOS, Windows or Linux, and a dot appears on its menu bar or tray icon when a Claude Code session stops on a permission prompt or a question.

Claude Code and Codex Checked against ccdeck 3.81.3 on

You will

Before you start

Steps

  1. Download the file for your computer

    There is no build for Windows or Linux on ARM.

    Not sure which Mac? In Terminal, this prints arm64 on Apple silicon and x86_64 on Intel.

    uname -m

  2. Install it

    • macOS. Open the .dmg and drag ccdeck into Applications. Run it from there, not from the disk image, so that it can update itself.
    • Windows. Run ccdeck-win-x64.exe. It is not code-signed, so SmartScreen stops it: click More info, then Run anyway.
    • Debian or Ubuntu. Open the .deb with your software installer, or run sudo apt install ./ccdeck-linux-amd64.deb in its folder.
    • Other Linux. Make the AppImage executable, or it does nothing. In its folder:
    chmod +x ccdeck-linux-x86_64.AppImage && ./ccdeck-linux-x86_64.AppImage

    More about terminal installs

    On macOS, run curl -fsSL https://ccdeck.dev/install.sh | sh. It downloads the build for your Mac’s processor, refuses it unless it carries ccdeck’s signature, and puts it in /Applications, or in ~/Applications when that is not writable. Then it quits a running ccdeck and opens the new one.

    On Windows, run irm https://ccdeck.dev/install.ps1 | iex in PowerShell. It downloads the newest installer, refuses it unless its SHA-512 is the one the release lists, and runs it silently: it closes a running ccdeck and opens the new one.

    Neither macOS nor SmartScreen stops an app installed this way, because a file fetched from a terminal carries no quarantine flag or Mark of the Web. The Windows check proves the download is whole; the installer itself is still not signed.

    Each also leaves the word curl or irm in an install-via file in ccdeck’s folder, read by ccdeck’s first usage report.

  3. Open ccdeck

    Open it from Applications, the Start menu or the applications menu. The window opens on the deck, and the icon appears in the menu bar or the tray.

    macOS stops the first launch. ccdeck is not notarised by Apple. Open System Settings, then Privacy & Security, and click Open Anyway for ccdeck.

    The deck’s page at 1440 by 900, the size the app’s window first opens at. The topbar shows the version, a “1 waiting” chip followed by web-api, 6m, Bash, and Search, Settings and Feedback at its right. Narrow stripes of icons, in groups split by short rules, run down the left and right edges. The session list, open beside the left one, has web-api, waiting 6 minutes on Bash, above infra, a Codex session on GPT-5.5, and data-pipeline. On the canvas, web-api’s card says Needs you, data-pipeline’s group is done, and infra’s has no title. Open the full-size picture
    Demo data As a browser shows it; in the app, the topbar is the window’s title bar.

    The icon’s menu opens with a click on macOS, or a right-click on Windows and Linux. Closing the window does not quit the app: click Quit ccdeck in that menu.

    More about the window, the icon and the deck
    • On Windows and Linux the title bar ends in the window’s buttons; its three-line button at the left opens the application menu.
    • Opened again, the window comes back as you closed it, maximized or full screen too.
    • The mark alone: nothing is running. A ring in its corner: a session is running. A dot: one is waiting on you. An exclamation mark: the app has lost the deck.
    • On macOS, the number waiting is beside the icon. On Windows and Linux, the tooltip has it, and a left click opens the window.
    • Only Claude Code sessions are counted: Codex’s log does not say when one waits.
    • On macOS, with its window closed, the app is not in the Dock or Cmd + Tab. Quit ccdeck stops the deck too, if the app started it.
    • A deck started by npx ccdeck can stay: the app uses it, or replaces it if older.

  4. Choose whether it starts at login

    The first time, the app asks one question, ccdeck lives in the menu bar. Leave Start ccdeck when I log in ticked, or click it to clear it, then click OK.

    More about the second question

    If the npm version set up a login item of its own, the app asks a second question, Another ccdeck starts when you log in. Replace it with the app sets the app to start at login, then removes that login item, since the app starts the deck itself. If the app cannot be set to start, the npm item stays. Keep it leaves it in place.

    On Linux, the box and Start at login in the icon’s menu write ~/.config/autostart/ccdeck-desktop.desktop, which GNOME, KDE and Xfce read at login.

  5. Turn on notifications for a closed window

    They start off. Click Notifications while closed in the icon’s menu so that it is ticked, or turn on the same switch in Settings › Notifications: click Settings at the right of the topbar.

    Settings open at Notifications. Down the left, under a Search settings field: General, Appearance, Text & density, Keyboard, Notifications, Sounds, Integrations, Data, Claude Code, Radar and About. On the right, under the heading Notifications, the group While the deck is closed: Notifications while closed switched on, with the note With the ccdeck window closed, get a notification wherever a sound would have played. Below it, the group Accounts, with the line For the Claude and Codex accounts you’re on, whether or not the deck is open, and four switches, each with a line under it saying when it fires: Account auto-switched on, Quota at 90% and 100% and Quota reset off, and Sessions stopped on login or limit on. Open the full-size picture
    Demo data The switch in the window, turned on. The deck’s permission to raise notifications was supplied to the page for this picture.

    Then, while no deck page is open, the app notifies you when a turn finishes or Claude Code asks for permission or input.

    More about the notifications

    Each one is titled with the session’s folder name. Its text is the agent’s last message, cut at 160 characters, or Claude Code’s own sentence. A Codex turn can notify only that it ended, because its rollout log carries no message to quote.

    Clicking a notification opens the window. On macOS it plays the deck’s own tones; on Windows and Linux, the system’s sound. A session’s prompts are repeated at most once every two minutes, and at most three notifications go out in any minute: the rest arrive as one, such as “2 more sessions need you”.

    The account notifications, such as auto-switch moving Claude Code or Codex to another account, have their own switches in Settings › Notifications, and do not need this one. The app shows them without a sound, whether its window is open or closed.

  6. Restart when an update is ready

    The app downloads and checks new releases from GitHub by itself. When one is ready, the topbar’s version chip shows both versions.

    The deck in a small window, dimmed behind What’s new. Its topbar has the version chip reading v3.81.3 → v3.81.4, a Restart to update button beside it, the “1 waiting” chip, and Search, Settings and Feedback at its right end. What’s new, headed v3.81.3, opens with the line “ccdeck v3.81.4 is downloaded and verified.”, then “Changes since v3.81.2.”, the heading More reliable Codex switching and quieter account rows, one note, More reliable Codex account switching, and 2 more improvements behind Show details. At its foot are Release history and a second Restart to update button. Open the full-size picture
    Demo data The chip, and What’s new with the update ready. The ready update was supplied to the page for this picture.

    Click Restart to update beside the chip, in What’s new or in the icon’s menu. Otherwise it installs when you quit, leaving ccdeck closed, or by itself once the window has been closed or out of focus for a full minute.

    With the .deb, it waits for Restart to update, which asks for your administrator password.

    It waits for your agents, for a day at most. Then it installs even mid-turn: your agents carry on, but the canvas misses the second or two the deck is gone.

    More about updates
    • The app looks about 15 seconds after each start and every six hours. To look now, click the update row in the icon’s menu, or ⋯ in What’s new, then Check for updates.
    • While an update waits, the app looks again every half hour, for a newer one.
    • Later, on the app’s “ccdeck v… is ready” notice, holds it off for 24 hours.
    • Each download must match its checksum and carry two signatures by ccdeck’s update key, one over its name and version: it installs only as the version it was released as, and only if newer. A download failing a check is not installed.
    • After a restart the app makes by itself, its window comes back only if it was open before.
    • On Linux, while a locked screen has taken the tray away, the app does not restart by itself: it waits for the unlock, then another full minute.

If something goes wrong

Linux: there is no icon

On GNOME, install or turn on the AppIndicator extension. An icon that went away comes back when the app restarts itself, once its window has been closed or out of focus for a minute. Until then, open ccdeck again for the window.

The menu says No deck running

The deck stopped, after ccdeck --stop for example. The app does not restart it by itself: click Start the deck in the icon’s menu.

No notification arrives with the window closed

Check that Notifications while closed is ticked. Then close every deck page: the app’s window, which opens at login too, and any browser tab on the deck.

ccdeck in a terminal is older than the app

The app updates only its own copy. Settings › About says under Terminal command whether the deck is updating it, or which command to run.

You removed the app, and its hook is still there

Removing the app leaves it in Claude Code’s settings: see Uninstall ccdeck and remove its Claude Code hook.

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

Next

All guides Troubleshoot Desktop app in the README