{"slug": "one-dashboard-for-every-claude-code-and-codex-session-installing-and-configuring", "title": "One dashboard for every Claude Code and Codex session — installing and configuring ccdeck", "summary": "A developer has released ccdeck, an open-source local dashboard that visualizes every Claude Code and Codex session on a machine as a live tree, surfacing sessions waiting on input, subagent and tool-call activity, and cost and quota data. It installs via `npx ccdeck`, adds ten reporting-only hooks to Claude Code's settings.json, and tails Codex rollout files without modifying them; telemetry is limited to install/update events and errors, with sessions, prompts and paths never sent and an opt-out via AGENTS_DECK_NO_REPORTS=1.", "body_md": "I build [ccdeck](https://github.com/BarganConstantin/ccdeck). Every step below is also on [ccdeck.dev/guides](https://ccdeck.dev/guides/), checked against ccdeck 3.38.0.\n\nFour 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.\n\nAn 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.\n\nccdeck 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.\n\nThis post is the install-and-configure walkthrough.\n\n`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 `AGENTS_DECK_NO_REPORTS=1` keeps them off from the very first start. The README's \n\n```\nnpx ccdeck\n```\n\nThe deck opens in your browser and gives you the prompt back. The start-up report tells you what it found:\n\n`Claude hooks`` Codex sessions``watching` when the deck found Codex, `skipped` when it did not.`server ready`` 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.\nRunning `npx ccdeck` again does not start a second deck: it prints `deck already running` and opens that deck's tab.\n\nThe 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**.\n\n**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.\n\nThe 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.\n\n**For Codex**, nothing is installed. The deck tails the rollout files Codex already writes under `~/.codex/sessions`.\n\nUntil something arrives, the canvas reads *Waiting for Claude Code or Codex*. Run `claude` or `codex` in any folder and give it something to do:\n\n*Demo data. The pill reads LIVE while it works, DONE once it stops.*\n\nA session that was already running when the deck started shows up the next time it does something.\n\nClosing the terminal **does not** stop the deck; it runs in the background.\n\n```\nnpx ccdeck --status   # what is running, on which port, watching which folder\nnpx ccdeck --logs     # the last lines a backgrounded deck wrote\nnpx ccdeck --stop     # the off switch\n```\n\nA deck started with `npx` does not come back after a reboot. To have it start at login:\n\n```\nnpx ccdeck --install\n```\n\nThat 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.\n\nFull guide: [Install ccdeck with npx and see your first session](https://ccdeck.dev/guides/first-run/).\n\nSame 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.\n\n| System | File | \n|---|---|\n| macOS, Apple silicon | [ccdeck-mac-arm64.dmg](https://github.com/BarganConstantin/ccdeck/releases/latest/download/ccdeck-mac-arm64.dmg) | \n| macOS, Intel | [ccdeck-mac-x64.dmg](https://github.com/BarganConstantin/ccdeck/releases/latest/download/ccdeck-mac-x64.dmg) | \n| Windows, x64 | [ccdeck-win-x64.exe](https://github.com/BarganConstantin/ccdeck/releases/latest/download/ccdeck-win-x64.exe) | \n| Debian / Ubuntu | [ccdeck-linux-amd64.deb](https://github.com/BarganConstantin/ccdeck/releases/latest/download/ccdeck-linux-amd64.deb) | \n| Any other Linux | [ccdeck-linux-x86_64.AppImage](https://github.com/BarganConstantin/ccdeck/releases/latest/download/ccdeck-linux-x86_64.AppImage) | \n\nThe first launch has one quirk per system, because the builds are not notarised or code-signed yet:\n\n`curl -fsSL https://ccdeck.dev/install.sh | sh`, which checks ccdeck's signature and skips that prompt.` chmod +x ccdeck-linux-x86_64.AppImage`. On GNOME you also need the AppIndicator extension for the tray icon.\nTwo things worth switching on:\n\nThe app updates itself from GitHub releases, and installs a download only if it matches its checksum and carries ccdeck's own signatures.\n\nFull guide: [Install the ccdeck app on Mac, Windows or Linux](https://ccdeck.dev/guides/desktop-app/).\n\nThere is no config file. Everything is a flag, an environment variable, or a switch in the page.\n\n```\ncd ~/code/my-api && npx ccdeck --scope      # this folder and below only\nnpx ccdeck --workspace ~/code/my-api        # same, from anywhere\nnpx ccdeck                                  # every folder again\n```\n\nGuide: [Show one project's sessions](https://ccdeck.dev/guides/one-project/).\n\n```\nnpx ccdeck --no-codex    # Claude Code only\nnpx ccdeck --no-claude   # Codex only — no hooks, no accounts panel\nnpx ccdeck --claude      # force Claude capture if the deck did not find Claude Code\nnpx ccdeck --codex       # force Codex capture if ~/.codex is somewhere unusual\n```\n\n`CODEX_HOME` points the deck at a non-default Codex folder. Guide: [Set up ccdeck for Codex CLI](https://ccdeck.dev/guides/codex/).\n\n`npx ccdeck --port 4500`, or `AGENT_DAG_PORT=4500`.\n\n`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](https://ccdeck.dev/guides/waiting-on-you/).\n\n| Variable | What it does | \n|---|---|\n| `AGENTS_DECK_NO_REPORTS=1` | Never send usage reports | \n| `AGENTS_DECK_NO_LAN=1` | Keep **Local network** (account sharing between your machines, UDP 45317) off | \n| `AGENTS_DECK_NO_STATUS=1` | Don't read Anthropic's and OpenAI's status pages | \n| `AGENTS_DECK_NO_NOTIFY=1` | Never raise a desktop notification | \n| `AGENTS_DECK_NO_INSTALL=1` | Don't install or update claude-swap/ccusage, no update checks, no status pages, no reports | \n\nThe full list is in the README's [Options](https://github.com/BarganConstantin/ccdeck#options).\n\n| Key | Opens | \n|---|---|\n| `L` | Session list — waiting sessions first | \n| `W` | Next session waiting on you | \n| `A` | Claude accounts | \n| `U` | Usage: cost and quota | \n| `S` | This machine: CPU, memory, heat | \n| `V` /`M` | Sound menu / mute | \n| `?` | Help and the tour | \n\n`npx ccdeck` again: it opens the running deck's tab, or starts one.`npx ccdeck --claude`.`~/.claude/settings.json` is not valid JSON. Repair it or move it aside, then start again.`ccdeck: command not found`` npx` is not on your PATH. Put `npx ccdeck --install`.\nGuide: [Troubleshoot ccdeck](https://ccdeck.dev/guides/troubleshooting/).\n\n```\nnpx ccdeck@latest --uninstall --purge\n```\n\nThat 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](https://ccdeck.dev/guides/uninstall/).\n\nNext in this series: sharing your Claude Code accounts between your machines, and letting them repair each other's expired logins.", "url": "https://wpnews.pro/news/one-dashboard-for-every-claude-code-and-codex-session-installing-and-configuring", "canonical_source": "https://dev.to/bargan/one-dashboard-for-every-claude-code-and-codex-session-installing-and-configuring-ccdeck-3md2", "published_at": "2026-10-07 04:03:53+00:00", "updated_at": "2026-10-07 04:18:14.875483+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "mlops"], "entities": ["ccdeck", "Claude Code", "Codex", "Anthropic", "OpenAI", "BarganConstantin", "npm", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/one-dashboard-for-every-claude-code-and-codex-session-installing-and-configuring", "markdown": "https://wpnews.pro/news/one-dashboard-for-every-claude-code-and-codex-session-installing-and-configuring.md", "text": "https://wpnews.pro/news/one-dashboard-for-every-claude-code-and-codex-session-installing-and-configuring.txt", "jsonld": "https://wpnews.pro/news/one-dashboard-for-every-claude-code-and-codex-session-installing-and-configuring.jsonld"}}