ccdeck

Set up ccdeck for Codex CLI

To set up ccdeck for Codex CLI, run npx ccdeck, check that its report names your Codex folder and start codex in any folder: nothing is installed for Codex, each session gets a card, approvals stay in its terminal, and U opens the Usage panel with your Codex quota.

Codex only Checked against ccdeck 3.81.3 on

You will

Before you start

Steps

  1. Start the deck and find the Codex row

    Run this in any terminal:

    npx ccdeck --ref=guides-codex

    In the report it prints, Codex sessions watching and a folder mean the deck found Codex and reads the files there.

    Nothing is installed for Codex. There is no hook and no trust prompt. The deck reads the rollout file Codex writes for each session.

    More about the Codex folder

    The folder is $CODEX_HOME/sessions, or ~/.codex/sessions when CODEX_HOME is not set or is empty. A long path may be cut short with …. Starting the deck writes nothing in the Codex folder.

    The deck also reads the sessions folder of every other Codex account it lists, though the row names only this one.

    If Codex keeps its files in another folder, start the deck with the same CODEX_HOME, and the row names that folder: CODEX_HOME=~/codex-home npx ccdeck. In PowerShell, set it first: $env:CODEX_HOME="D:\codex"; npx ccdeck.

  2. Start a Codex session

    Run codex in any folder and give it something to do. The session’s card appears once Codex writes to its rollout file. It is named after the folder and opens as LIVE.

    More about when the card appears

    The deck looks for new lines every 1.5 seconds in the two newest day folders under sessions. A session that runs for days, or one you pick up with codex resume, is followed in its older folder too.

    A session mid-turn when the deck starts, its file written in the last 24 hours, appears at once, marked restored, with its prompt and model. That does not prove Codex is still running.

    Any other session already running appears the next time it writes. Either way, no earlier tool call is shown. Until its next turn, it has no model or approval policy: ? beside its name, ≥ before its time, a Codex chip, tokens but no cost. Nothing needs repairing.

    Two sessions in one folder are told apart by the last characters of their ids, after the folder’s name on their frames.

  3. Read a Codex card

    The pill reads LIVE while a turn runs. It turns DONE when Codex finishes the turn, or when you press Esc in Codex.

    The card of infra, a Codex session, marked LIVE, with a round button for its note and a context ring reading 15. It has no title row: its second row reads session, a GPT-5.5 chip and 9m 06s, then comes the line approvals not visible, then an empty strip of the last 60 seconds' tool starts, then 3 tools, 1 in-flight, 119.5k tok and 53¢. To its right, three tool bubbles: Shell for terraform and Edit for keys.tf with ticks, and a second Shell for terraform with a round dot in place of a tick, the mark of a call still running.
    Demo data The last row counts the calls, then gives the tokens and an estimated cost.

    Click the ring for the context breakdown. Its context-window figures are the Codex CLI’s own, from its most recent request.

    To open a call and read its input and response, see See Claude Code subagents and tool calls live.

    More about a Codex card

    A Codex card has no title row. A Codex child session gets a card of its own, joined to its parent’s, when the rollout names the parent. tok is Codex’s input, cached tokens included, plus its output. The cost is an API-price estimate: cached tokens at the cache rate, each part at the speed its settings recorded. The rollout does not record your bill. Session usage, in Usage’s By session, can price the whole session as one scenario.

    Codex’s tools get the deck’s names: Shell for exec, exec_command, shell and shell_command, Edit for apply_patch, Plan for update_plan, Web for run, stdin for write_stdin, and wait. Hover a bubble for Codex’s own name and input.

    A call counts as failed only when Codex’s result begins “Script failed”, or “Exit code:” with a number other than 0. So a failed command can show ✓: click its bubble to read the output.

  4. Watch the terminal for approvals

    Codex writes no approval request to its rollout files, so the deck cannot tell when a session stops to ask. A running card says approvals not visible when its approval policy can ask.

    Two Codex session cards, one above the other, both LIVE on GPT-5.5. The infra card has the line approvals not visible and reads 3 tools, 1 in-flight, 119.5k tok and 53¢. The billing card has no such line and reads 2 tools, 54.3k tok and 24¢.
    Demo data infra runs under on-request and says approvals not visible; billing runs under never, which cannot ask.

    A call waiting for your approval looks the same as one still running: its bubble keeps its pulsing dot.

    Claude Code only. A Codex session never gets the waiting rows, the count or the asking tone in See which Claude Code session is waiting for input.

    More about approvals not visible

    The line shows while the policy is untrusted, on-request or on-failure, or has not been read yet. It is not there at never, or on a DONE card. Hover it for the reason, which ends “Check the terminal.”

    With sound on, the deck plays its finish tone when a Codex turn ends, but never the asking tone. A call with no result shows in-flight… and (waiting…) in its dialog, and the deck never marks it failed for being quiet.

  5. Read your Codex quota

    Press U, or click the Usage icon on the stripe on the right.

    The Codex quota section of the Usage panel, with a Plus badge and just now. A 5-hour window bar at 38%, resets in 2h 14m, 17% under pace. A 7-day window bar at 21%, resets in 4d 3h, 20% under pace.
    Demo data One bar for each limit OpenAI reports, with when it resets and how the pace compares.

    With several Codex accounts, the section reads the default one: see Switch between multiple Codex accounts.

    After a week ends, a line under the bars says how full your last weeks ended. The chart icon in the panel’s header opens Quota history. Click Codex there for what was left of each window over time.

    To be notified when a window reaches 90%, and again at 100%, turn on Quota at 90% and 100% in Settings › Notifications. It starts off, and works whether the deck is open or not.

    More about the quota

    Each bar is named by its length: “5-hour window”, “7-day window”, “30-day window”, or “Rate limit” when OpenAI gives no length. Click the pace words to see how full a window should be by now. A line counts saved rate-limit resets; ccdeck only reports them.

    The deck reads the quota about once a minute while the page is open; the circular arrow in the panel’s header reads it now. With one login in $CODEX_HOME/auth.json, it refreshes it as the CLI does, only while the page is open or a quota notification is on, and shows a spend cap and credits if your plan has them. With Codex accounts added, or a login in the system keyring, it asks Codex itself, which may renew the login.

    When OpenAI’s status page reports an incident on a Codex component, a line under the section’s heading and a chip in the topbar say so.

  6. Run a deck for Codex only

    Where the deck finds no Claude Code, this happens by itself. Where Claude Code is installed, start the deck with --no-claude:

    npx ccdeck --no-claude --ref=guides-codex

    The deck installs no Claude Code hook and no claude-swap. The deck that starts when you log in does not get --no-claude. After a reboot, run npx ccdeck --no-claude again.

    An earlier Claude Code hook stays. --no-claude does not take it out, and the deck still accepts what it sends. npx ccdeck --uninstall removes it and the login item, and stops the deck: run npx ccdeck --no-claude again.

    More about a Codex-only deck and the switches

    The stripe on the left starts with Codex accounts, with no switch to Claude, and the Usage panel shows Codex quota only.

    • --codex reads Codex even before its folder exists. Sessions appear once Codex creates it, without a restart.
    • --no-codex stops the deck reading Codex. Given both, --no-codex wins.
    • --claude turns Claude Code capture on when the deck did not find Claude Code.
    • A start with other switches, or another CODEX_HOME, replaces the running deck.
    • The deck that starts when you log in gets none of these switches. On macOS and Linux it gets the CODEX_HOME set when the login item was made. On Windows it uses your saved user variables.

If something goes wrong

The report says Codex sessions skipped

The deck found no Codex folder when it started, or was started with --no-codex. Run codex once, and the deck finds its folder within 15 seconds. If Codex uses another folder, start the deck with CODEX_HOME set to it.

Codex is running, but no card appears

If the deck was started with --workspace or --scope, start the session inside that folder. Otherwise check that the Codex sessions row names the folder Codex writes to.

Every Codex session appears twice

An older deck left hooks in Codex’s hooks.json, and the report’s Codex hooks row says so. Run npx ccdeck --uninstall, then start the deck again. Uninstall also stops the deck and removes the login item, which ccdeck --install-service puts back on a global install.

Codex quota says “Quota unavailable.”

The line under it says why. Most often Codex is not signed in, or is signed in with an API key, which has no quota: run codex login.

A card stays LIVE after its terminal was closed

Codex writes nothing when a session closes. The deck ends that session after 90 minutes with no new line.

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

Next

All guides Troubleshoot Options in the README