Troubleshoot ccdeck: status, logs, port and hooks

Before you start

• A terminal on the same machine as the deck, with the deck’s CLAUDE_CONFIG_DIR, CCDECK_HOME, CODEX_HOME and CCDECK_CODEX_HOMES if you set any. Otherwise --status can miss the deck, and npx ccdeck can start another one or replace it.
• With ccdeck installed globally, leave npx out of the commands.

Steps

1. Check which deck is running

   This lists each running deck, its address and the folder it watches.

   $npx ccdeck --status

   no deck is running means none runs for this config folder: npx ccdeck starts one.

   More about the desktop app and --stop

   • The desktop app uses a deck that is already running, 4317 first. It replaces that deck only when it is older than the one the app carries.
   • npx ccdeck --stop stops every deck, the app’s too. The app’s menu then reads No deck running, and the app starts one again only when you click Start the deck.
   • refusing to stop every deck when you asked for one. means the value after --port is missing or is not a port number, so nothing was stopped. Use the port --status prints.
   • could not stop pid <n> on <port> means that deck was asked, then killed, and is still running. --status shows what is left.
   • restarting after a crash in --status is a deck about to come back by itself. --stop stops it too.

2. Read what the deck last wrote

   The deck runs in the background and logs what it would print. This shows the last 200 lines.

   $npx ccdeck --logs

   Look for two lines:

   • not registered: no Claude Code events arrive until the deck says registered again, which it does by itself.
   • the deck has stopped 5 times in 10 minutes: it kept crashing and stays stopped. Read the lines above it, then run npx ccdeck.
   More about where the log lives

   • macOS: ~/Library/Logs/ccdeck
   • Windows: %LOCALAPPDATA%\ccdeck\Log
   • Linux: $XDG_STATE_HOME/ccdeck or ~/.local/state/ccdeck

   CCDECK_HOME moves it. With CLAUDE_CONFIG_DIR set, it is the agent-dag folder inside that one. nothing logged yet means no deck has written a log there. The desktop app’s own deck writes deck-app.log instead, which --logs does not read.

3. Check that the deck watches Claude Code and Codex

   The deck’s start-up report has a row for each. skipped means it is not watching that one:

   • Claude hooks skipped: start the deck with npx ccdeck --claude.
   • Codex sessions skipped: set CODEX_HOME to the folder Codex uses, or start with npx ccdeck --codex.

   One installed later is noticed within about 15 seconds, and the deck restarts to watch it. A Codex session under a CODEX_HOME you set appears once the deck starts with it in CCDECK_CODEX_HOMES.

   Claude Code only. A deck and a session started with different CLAUDE_CONFIG_DIR values never meet. Start the deck from a shell with the same value as your sessions.

   More about the other rows, and late sessions

   • Claude hooks with a path: the hook is written, as agent-dag/hook.js in the Claude config folder the deck used.
   • Codex sessions watching with a folder: the folder the deck reads Codex’s files from.
   • Codex hooks left by an older deck: Codex sessions can arrive twice. npx ccdeck --uninstall takes those hooks out. It also removes the Claude Code hook and any login item, and stops the deck. npx ccdeck then writes the hook again, and ccdeck --install-service puts the login item back.
   • Claude hooks not installed, and the deck stops: it will not rewrite a Claude Code settings.json it cannot read. Fix the file or move it aside, or start with npx ccdeck --no-claude.

   A session already running when the deck started appears the next time it does something, with ? beside its name. A busy one appears at once, also marked restored; for Claude Code, only on macOS and Linux.

4. Check the folder the deck watches

   A deck started with --workspace <path>, or with --scope in a folder, draws only sessions inside that folder.

   

   To watch the whole machine, run npx ccdeck with no flags: it replaces the scoped deck. Show one project's Claude Code and Codex sessions has more.

5. Open the deck at its address

   A tab where no deck answers says Server unreachable, Disconnected from server or Lost connection to the ccdeck server. Run this:

   $npx ccdeck --ref=guides-troubleshooting

   It opens the running deck’s tab, or starts a deck. The address is on its server ready line. A tab at that address reconnects by itself.

   More about the port, and too many tabs

   The deck asks for port 4317, or the one given with --port or AGENT_DAG_PORT. It moves only when something that is not one of your decks holds that port, and then tries up to ten random ports from 4318 to 4400. A browser keeps the tour, your panel choices and your text size per address, so they start over on a new one.

   If no port can be had, the start fails with all ports tried — none available. On Windows, a reserved port range is the usual cause: the message names netsh interface ipv4 show excludedportrange protocol=tcp, and a --port outside every range it lists gets past it.

   A tab that says Too many ccdeck tabs are open connects by itself once you close another ccdeck tab: the browser keeps at most six live connections to one address.

6. Check the quota and cost readings

   Press U, or click the Usage icon on the stripe on the right. A quota the deck could not read says why.

   

   Do what the line says, then click the circular arrow in the panel’s header.

   Is it you or Claude? When Anthropic or OpenAI reports an incident, a topbar chip, such as Claude · partial outage, says so and links to their status page.

   More about the other quota and cost lines

   • No quota to show.: that Claude Code install signs in with an API key, Bedrock or Vertex, so it has no quota window.
   • Anthropic asked the deck to wait and Waiting for the next allowed read clear by themselves.
   • API-key login: Codex signs in with an API key, which has no ChatGPT quota to show.
   • ChatGPT API unreachable also shows when the API answers with an error, so it does not prove the network is down.
   • Usage history (H) says ccusage failed, and which copy: install ccusage yourself, or point AGENTS_DECK_CCUSAGE at it.
   • not priced on a card: this build has no published rate for that model, so only its tokens are counted.
   • A script that reads the panel’s figures from the deck, such as /api/quota, gets 401. Send the token in ~/.claude/agent-dag/<pid>.json, with the pid --status prints, as an x-ccdeck-token header.

If something goes wrong