Show one project's Claude Code and Codex sessions

Before you start

• Node.js 18 or newer, and Claude Code, Codex, or both.
• A terminal open in the project’s folder, or the folder’s path.

Steps

1. Start the deck for one folder

   In a terminal in the project’s folder, run:

   $npx ccdeck --scope --ref=guides-one-project

   Or name the folder from any terminal: npx ccdeck --workspace ~/code/web-api. The deck captures the sessions in that folder or any folder under it.

   This stops a deck that watches every folder. Only one deck runs at a time. Step 6 brings it back.

   More about the folder

   • With both flags, --workspace wins.
   • A relative path is read against the folder you run the command in, and links are followed. A folder that does not exist yet is accepted.
   • Put a path with a space in quotes. A ~ inside the quotes is not expanded, so write "$HOME/code/web api".
   • Letter case is ignored on macOS and Windows. On Linux, a folder whose name differs only in case is another folder.
   • Nothing in the page changes the folder. To watch another, start the deck again with that folder.
   • One deck runs at a time for each CLAUDE_CONFIG_DIR you run Claude Code with.

2. Check which folder the deck watches

   The terminal report’s first row, workspace, names the folder. (all) there means every folder. The new browser tab names it too, until a session in the folder is drawn.

   

   After that, the page no longer names the folder. npx ccdeck --status prints it from any terminal.

   To come back to this deck, run the same command. The report says ccdeck brings this deck back. Here it does not: a plain npx ccdeck replaces it with a deck for every folder.

   More about the report

   • When the start stopped another deck, the first line says so: stopped the deck on 4317 · pid … · it was started with different settings.
   • The folder is absolute, with links followed.
   • Running the command for the same folder again prints deck already running and opens the deck’s tab.
   • --status never marks a deck for one folder opens this one, because a plain start would replace it.
   • The new tab first replays the sessions the log holds from the folder, and none from other folders.

3. Start a session in the folder

   Run claude or codex in the folder, or in any folder under it. The session appears as on any deck. A session outside the folder never reaches the deck: it is not drawn, not written to the log, and plays no tone.

   A session already working in the folder when the deck starts appears marked restored, a Claude Code one only on macOS and Linux. Any other session that was already running appears the next time it does something. Both are marked ? and ≥.

   More about which sessions reach the deck

   The ? sits beside the session’s name and the ≥ before its time, because the deck did not see it begin. A restored card leaves out the tool calls made before the deck started. Restore unfinished sessions, in Settings › General, turns restoring off for each CLI.

   Claude Code and Codex are filtered in different places. Claude Code: ccdeck’s hook still runs for every session on the machine, and sends each event only to a deck whose folder holds the session’s folder. Codex: the deck reads the folder recorded at the top of each new rollout file, and does not read a file whose folder is outside its own.

4. Know what the folder does not filter

   • The Usage panel’s today, month and all figures and the Usage history dialog (H) come from ccusage, which covers sessions in every folder.
   • Accounts, quota windows and the This machine panel are the same as on a deck that watches every folder.
   • Tool activity and Skill activity, on the stripe on the right, show the history ccdeck keeps on this machine, other folders’ calls included; this deck adds only its folder’s.

   Clearing empties the whole log. With the default log, clearing the canvas (C) also erases what the log holds for other folders. The dialog, Clear the deck?, does not mention them. Step 5 gives the deck a log of its own.

5. Give the deck its own log, if you want one

   $npx ccdeck --scope --history ~/web-api-events.jsonl --ref=guides-one-project

   The deck then reads and writes that file in place of the default log, so clearing empties only that file. To come back to this deck later, run the whole command again, --history included.

   More about the log

   • The report’s log row names the file.
   • While this deck runs, the folder’s sessions are not written to the default log. A deck that later watches every folder does not replay them.
   • --no-persist keeps no log at all.
   • The log file is part of what a start compares, and so is a port asked for with --port. A start with another file or port stops the running deck: it does not run beside it.

6. Go back to every session

   Run the deck with no folder flag:

   $npx ccdeck --ref=guides-one-project

   It stops the deck for one folder and starts one whose workspace row reads (all). Sessions that ran outside the folder while only that deck was up were never recorded, and do not come back.

   More about going back

   • The report shows the same stopped the deck on … line. npx ccdeck --status now marks the deck opens this one.
   • --all is accepted and changes nothing: a plain start already watches every folder.
   • The new deck replays the default log, up to its newest 2,000 hook events. Sessions still running appear as in step 3.
   • See Claude Code subagents and tool calls live says what a restart brings back.

If something goes wrong

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