DEV Community

Cover image for One dashboard for every Claude Code and Codex session — installing and configuring ccdeck
Bargan Constantin
Bargan Constantin

Posted on

One dashboard for every Claude Code and Codex session — installing and configuring ccdeck

#opensource #claude #openai #cli

I build ccdeck. Every step below is also on ccdeck.dev/guides, checked against ccdeck 3.38.0.

Four agents running, and the machine has been quiet for twenty minutes. One of them stopped to ask something and I 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.

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 I actually have — what is running right now, which one is stuck, what is this costing — are the ones the scroll answers worst.

ccdeck draws the tree instead: one local page with every Claude Code and Codex session on the machine, sessions waiting on you at the top, every subagent and tool call live, and cost and quota beside them.

This post is the install-and-configure walkthrough.

ccdeck's canvas: sessions as cards, subagents as nodes, tool calls lit as they run

Before you start

  • Node.js 18 or newer and a browser — or none of that, if you take the desktop app below.
  • Claude Code, Codex CLI, or both. No account, API key or config file.
  • A choice about usage reports. From its first start the deck sends usage reports to api.ccdeck.dev: install and update events, one "active" a day, and errors, with your IP address and a device fingerprint. Your sessions, prompts, files, project names and paths are never sent. One switch under Appearance (the sun/moon button in the topbar) turns reports off and deletes what was sent, and AGENTS_DECK_NO_REPORTS=1 keeps them off from the very first start. The README's What it touches section lists everything that leaves the machine.

Option A — one command 

npx ccdeck
Enter fullscreen mode Exit fullscreen mode

The deck opens in your browser and gives you the prompt back. The start-up report tells you what it found:

  • 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, skipped when it did not.
  • server ready with the address — http://127.0.0.1:4317, unless something else holds that port, in which case it takes one between 4318 and 4400 and prints it. That line is the one to trust.

Running npx ccdeck again does not start a second deck: it prints deck already running and opens that deck's tab.

The first time a browser opens the deck, an eight-picture tour opens by itself. Enter moves on, Esc closes it; to see it again, press ? and click Take the tour.

The tour:
Demo data.

What it changed on your machine

For Claude Code, the deck adds one hook entry per event — ten of them — to ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json), running a small hook.js that POSTs each event to the deck on 127.0.0.1. Your own hooks and settings stay as they are.

The hook only reports. Claude Code's hook protocol gives a hook two ways to allow, deny or rewrite a tool call — its exit code and its stdout — and this one always exits 0 and writes nothing, so it has no way to answer at all. If no deck is running, the hook exits and your session is not slowed down.

For Codex, nothing is installed. The deck tails the rollout files Codex already writes under ~/.codex/sessions.

Your first session

Until something arrives, the canvas reads Waiting for Claude Code or Codex. Run claude or codex in any folder and give it something to do:

A session card for web-api, LIVE on Opus 5, with Read and Grep calls finished and a third call still running
Demo data. The pill reads LIVE while it works, DONE once it stops.

A session that was already running when the deck started shows up the next time it does something.

Keep it running — or stop it

Closing the terminal does not stop the deck; it runs in the background.

npx ccdeck --status   # what is running, on which port, watching which folder
npx ccdeck --logs     # the last lines a backgrounded deck wrote
npx ccdeck --stop     # the off switch
Enter fullscreen mode Exit fullscreen mode

A deck started with npx does not come back after a reboot. To have it start at login:

npx ccdeck --install
Enter fullscreen mode Exit fullscreen mode

That installs ccdeck globally with npm and adds a login item — a launchd agent on macOS, a systemd --user unit on Linux, a Task Scheduler logon task on Windows. From then on ccdeck works without npx. On Linux, systemd ends user services at logout unless lingering is on; --install prints the loginctl enable-linger command rather than running it for you.

Full guide: Install ccdeck with npx and see your first session.

Option B — the desktop app

Same deck, no Node.js, plus an icon in the menu bar (tray on Windows and Linux) that fills in when a session is waiting on you.

System File
macOS, Apple silicon ccdeck-mac-arm64.dmg
macOS, Intel ccdeck-mac-x64.dmg
Windows, x64 ccdeck-win-x64.exe
Debian / Ubuntu ccdeck-linux-amd64.deb
Any other Linux ccdeck-linux-x86_64.AppImage

The first launch has one quirk per system, because the builds are not notarised or code-signed yet:

  • macOS — System Settings → Privacy & Security → Open Anyway. Or install from a terminal with curl -fsSL https://ccdeck.dev/install.sh | sh, which checks ccdeck's signature and skips that prompt.
  • Windows — SmartScreen: More info, then Run anyway.
  • Linux AppImage — a browser saves it without the permission to run, so it does nothing until you run chmod +x ccdeck-linux-x86_64.AppImage. On GNOME you also need the AppIndicator extension for the tray icon.

The deck inside the app: a
Demo data.

Two things worth switching on:

  • Notifications while closed (icon menu, or the Sound menu in the topbar). Off by default. With it on and no deck page open, you get a system notification when a turn finishes or Claude Code asks for permission or input.
  • Start ccdeck when I log in — the app asks once, on first launch.

The app updates itself from GitHub releases, and installs a download only if it matches its checksum and carries ccdeck's own signatures.

Full guide: Install the ccdeck app on Mac, Windows or Linux.

Configure it

There is no config file. Everything is a flag, an environment variable, or a switch in the page.

Only one project 

cd ~/code/my-api && npx ccdeck --scope      # this folder and below only
npx ccdeck --workspace ~/code/my-api        # same, from anywhere
npx ccdeck                                  # every folder again
Enter fullscreen mode Exit fullscreen mode

Guide: Show one project's sessions.

Only Claude Code, or only Codex 

npx ccdeck --no-codex    # Claude Code only
npx ccdeck --no-claude   # Codex only — no hooks, no accounts panel
npx ccdeck --claude      # force Claude capture if the deck did not find Claude Code
npx ccdeck --codex       # force Codex capture if ~/.codex is somewhere unusual
Enter fullscreen mode Exit fullscreen mode

CODEX_HOME points the deck at a non-default Codex folder. Guide: Set up ccdeck for Codex CLI.

Port

npx ccdeck --port 4500, or AGENT_DAG_PORT=4500.

Sounds and notifications

V opens the Sound menu: a tone for turn finished and one for Claude is asking, each with its own volume. M mutes from anywhere. Notifications while closed is in the same menu. Guide: See which session is waiting on you.

Turning things off

Variable What it does
AGENTS_DECK_NO_REPORTS=1 Never send usage reports
AGENTS_DECK_NO_LAN=1 Keep Local network (account sharing between your machines, UDP 45317) off
AGENTS_DECK_NO_STATUS=1 Don't read Anthropic's and OpenAI's status pages
AGENTS_DECK_NO_NOTIFY=1 Never raise a desktop notification
AGENTS_DECK_NO_INSTALL=1 Don't install or update claude-swap/ccusage, no update checks, no status pages, no reports

The full list is in the README's Options.

Keys worth learning

Key Opens
L Session list — waiting sessions first
W Next session waiting on you
A Claude accounts
U Usage: cost and quota
S This machine: CPU, memory, heat
V / M Sound menu / mute
? Help and the tour

When something does not work

  • No tab opened, or "Server unreachable" — run npx ccdeck again: it opens the running deck's tab, or starts one.
  • Claude hooks says skipped — the deck did not find Claude Code. Start it with npx ccdeck --claude.
  • Claude hooks says not installed and the deck exits — your ~/.claude/settings.json is not valid JSON. Repair it or move it aside, then start again.
  • ccdeck: command not found — a deck started with npx is not on your PATH. Put npx in front, or run npx ccdeck --install.

Guide: Troubleshoot ccdeck.

Uninstall 

npx ccdeck@latest --uninstall --purge
Enter fullscreen mode Exit fullscreen mode

That removes ccdeck's hook entries from ~/.claude/settings.json, removes its login item, stops every running deck and deletes its Local network private key. The app and the tools it installed for you (claude-swap, ccusage) are removed separately. Guide: Uninstall ccdeck.

Next in this series: sharing your Claude Code accounts between your machines, and letting them repair each other's expired logins.

Top comments (4)

Collapse
 
dorin_triboi_3aedb899bd1a profile image
dorin triboi •

Great walkthrough, this is how install docs should look. What I appreciated most: ccdeck adds its hook entries to settings.json without touching the ones already there. I have a bunch of my own hooks and it just slotted in next to them. And the fact that there's a clean --uninstall --purge makes trying it a no-brainer.
Two small ideas from daily use:

  • --scope for a repo plus its git worktrees. I often run each ticket in its own worktree, and it would be nice to see all of them as one project.
  • A threshold for notifications, e.g. "only notify me if a session has been waiting more than 2 minutes", so quick prompts I catch anyway don't ping me. Thanks for writing it all down so clearly!
Collapse
 
bargan profile image
Bargan Constantin •

Thanks Dorin! Leaving your own hooks alone is a hard rule for ccdeck, so it's good to hear it slotted in next to yours cleanly.

  • A repo plus its worktrees as one project. Today --scope is the current directory and --workspace <path> is any subtree, so worktrees count only when they live under that path. Keeping them inside the repo folder, or under one parent you pass to --workspace, works right now. Matching a repo and its worktrees through git itself is the better answer, and it's what the Git view I'm building already knows about.
  • A wait threshold before a notification. Good one, a quick prompt you catch anyway shouldn't ping you. The next release moves notifications into a Settings window, and an "only after N minutes" option belongs right there. It's on the list.

Thanks for reading it that closely!

Collapse
 
cristian_calaras_f2ca0013 profile image
Cristian Calaras •

ccdeck is a genuinely useful tool if you run multiple Claude Code or Codex sessions in parallel. The dashboard makes it much easier to see what’s running, what’s waiting for input, and roughly how much you’re spending.

The local-first approach is a big plus, and setup is surprisingly simple. That said, it’s still a relatively young project, and some rough edges remain — especially around Codex, where visibility is more limited than with Claude Code.

Overall, a practical tool that solves a real problem. If you regularly juggle multiple AI coding agents, it’s worth trying.

Collapse
 
bargan profile image
Bargan Constantin •

Thanks Cristian, that's a fair summary, rough edges included.

You're right about Codex, and the reason is worth saying: ccdeck reads Codex from its rollout log, and a rollout carries no "waiting on you" signal, so Codex sessions can't join the waiting queue the way Claude Code ones do. Since 3.38.2 a Codex session's hover card says outright that its approvals aren't visible. What the deck does show for Codex is the session on the canvas with its tool calls, plus its quota and cost in the Usage panel.

On "roughly how much": 3.38.3 fixed a real undercount (a subagent's reply was counted from its first streamed chunk), so the numbers are closer now.

Which Codex gap bothers you most? That's exactly the kind of thing that decides what I work on next.