ccdeck

Install ccdeck with npx and see your first session

To start ccdeck, run npx ccdeck in any terminal with Node.js 18 or newer: the deck opens in your browser at http://127.0.0.1:4317, adds its hook to ~/.claude/settings.json on its first run, and keeps running in the background after you close the terminal; npx ccdeck --stop stops it.

Claude Code and Codex Checked against ccdeck 3.81.3 on

You will

Demo data Your terminal shows a scroll. ccdeck draws the tree. Sessions waiting on you top the session list, longest wait first. Claude Code only. Codex is read from its rollout log, which records what happened rather than what is waiting now. Drawn as a reconstruction of the deck.

Before you start

Steps

  1. Start the deck

    Run this in any terminal. The deck opens in your browser and gives you the prompt back.

    npx ccdeck --ref=guides-first-run

    Its address is on the server ready line: http://127.0.0.1:4317, unless something else holds that port.

    More about the start-up report
    • Claude hooks, with a path: the hook Claude Code sends its events through is in place.
    • Codex sessions reads watching when the deck found Codex, and skipped when it did not.
    • When 4317 is taken, the deck tries up to ten random ports between 4318 and 4400, and prints the one it got. --port and a number asks for a port of your choosing.
    • Running npx ccdeck again starts no second deck. It prints deck already running and opens that deck’s tab.
    • Started over SSH, the deck adds a line naming ccdeck tui, which shows your accounts and the sessions waiting on you in that terminal.

  2. Take the tour, or close it

    The first time a browser opens the deck, a tour of eight pictures opens by itself. Press Enter to move on, or Esc to close it.

    The tour dialog, its header reading What the deck shows you and 1 / 8 beside a close button: a session list with api-server waiting on a Bash command, above the line Sessions waiting on you top the session list, longest wait first, a quieter line about the tone and the notification, the eight step dots and a Next button.
    Demo data The first of the eight.

    To see it again, click Take the tour on the empty canvas, or press ? and click it there. Watch video beside it opens this page’s film.

    The deck is in your browser’s language when ccdeck has it; Settings › General › Language changes that.

  3. See what the deck added for Claude Code Claude Code only

    On its first run the deck adds a hook to ~/.claude/settings.json. Claude Code sends its events through it to the deck. Your own hooks and settings stay as they are.

    It only reports. The hook cannot allow, deny or change a tool call.

    More about the hook

    It is one entry for each of up to twelve Claude Code events, marked "__agent-dag": true, running ~/.claude/agent-dag/hook.js with a three-second timeout. Ten are always there. StopFailure is added when every Claude Code the deck finds is 2.1.78 or newer, and UserPromptExpansion, for Skill activity, when every one is 2.1.116 or newer, unless the deck was started with AGENTS_DECK_SKILL_HOOK=0. With $CLAUDE_CONFIG_DIR set, the settings and the hook live there instead. The hook sends only to decks on 127.0.0.1, and exits when none is running.

    The deck writes the entries again on every start where it finds Claude Code, so one you delete by hand comes back. npx ccdeck --uninstall removes them. Codex gets no hook: the deck reads the files Codex writes under ~/.codex/sessions.

  4. Start a session

    Until a session sends something, the canvas reads Waiting for Claude Code or Codex, and Session not showing up? under it says how the deck hears from each CLI, or that it is not watching it. Run claude or codex in any folder, and give it something to do.

    One Claude Code session card for the folder web-api, marked LIVE, on Opus 5, its clock at 4 seconds, reading 3 tools and 1 in-flight, with Read and Grep calls finished and a third Read of router.ts still running beside it.
    Demo data Its pill reads LIVE while it works, and DONE once it stops.

    A session already working when the deck starts appears marked restored; a Claude Code one only on macOS and Linux.

  5. Stop the deck when you want it off

    Closing the terminal does not stop the deck. This stops every running deck:

    npx ccdeck --stop

    npx ccdeck --status shows what is running, and npx ccdeck brings the deck back.

    Windows over ssh. A deck started in an ssh session ends when that session closes. Start it from an ordinary Windows terminal, or let the login item in step 6 start it.

  6. Keep the deck across a reboot

    A deck started with npx does not start again when you log in. To have it start at login, run:

    npx ccdeck --install

    It installs ccdeck globally with npm and adds a login item. From then on, ccdeck works without npx, and the deck starts at login without opening a tab.

    Linux only. systemd ends your services at logout unless lingering is on. --install prints the command that turns it on, and does not run it for you.

    More about the login item
    • An npx run cannot have one: it would point into npm’s cache, which npm clears without warning.
    • Installed with npm i -g ccdeck, the first run adds it by itself, once per machine.
    • It is a launchd agent on macOS, a systemd user unit on Linux and a Task Scheduler logon task on Windows. A Linux machine that does not run systemd gets none, and the first start says so.
    • ccdeck --uninstall-service removes it and leaves ccdeck installed.

If something goes wrong

No tab opened, or the page says Server unreachable

Run npx ccdeck. If the deck is running, it opens its tab. If not, it starts the deck, and an open page reconnects by itself.

Claude hooks says not installed, and the deck exits

The deck could not update your Claude Code settings.json, and the line under it says why. If the file is not valid JSON, repair it or move it aside, then run npx ccdeck again.

Claude hooks or Codex sessions says skipped

The deck did not find that CLI. Install it and run it, and the deck finds it within 15 seconds and restarts itself. If it was installed already, start the deck with npx ccdeck --claude or npx ccdeck --codex, or for Codex set CODEX_HOME to its folder.

ccdeck: command not found

A deck started with npx does not put ccdeck on your PATH, though a few lines it prints leave npx out. Type npx in front, as in npx ccdeck --install.

npx ccdeck --install says npm cannot write to the global prefix

Do what the message says: run sudo npm i -g ccdeck, or point npm at a folder you own. Once ccdeck is installed, ccdeck --install-service adds the login item.

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

Next

All guides Troubleshoot Quick start in the README