Playbooks · Coding tasks
Queue a Codex message and resume the thread
Written November 2, 2026
Codex 0.166 adds queue --resume and doctor --network-only. Queue the follow-up to an unloaded thread, and diagnose a dead connection first.
What changed
Codex CLI 0.166.0, released 29 October 2026, added two commands for sessions that are not in front of you. codex queue --resume resumes unloaded threads after queueing a message, and codex doctor --network-only runs focused configuration, connectivity, and WebSocket diagnostics. The same release preserved acknowledged approval and permission settings when resuming or forking threads, and preserved reasoning-token accounting across resume and fork so a resumed thread does not compact prematurely. Before 0.166, queueing a message to a thread that was not loaded left you to resume it yourself; now one command can do both, and the doctor command can tell you whether a connection failure is yours to fix.
Queue first, then decide about resuming
codex queue puts a text message into an existing session. It takes a session UUID or exact session name with --thread and the message text with --message:
codex queue --thread <SESSION_ID> --message "Run the remaining checks"
That alone queues the message; nothing runs until the thread is loaded again. Add --resume and Codex also tries to resume the thread, on the local daemon or the selected --remote server:
codex queue --thread <SESSION_ID> --message "Run the remaining checks" --resume
The resume attempt is best-effort, and the command says so in its own help text: a failed resume produces a warning and the command still succeeds, with the message left queued. That is the behaviour to plan around. Queueing without --resume is the safe choice when you only want the message waiting — for example, queueing a follow-up to a session someone else will reopen. Queueing with --resume is the choice when you want the work to start now and you are prepared for it to stay queued if the thread cannot load. Image attachments are not supported, and queued messages use the existing thread's model: there is no --model on the queue command, so a queued follow-up cannot switch the thread to a different model.
Steps
- Check the version you run. Run
codex --version. The queue and doctor options described here need 0.166.0 or later. On an older install the flags do not exist, and the release notes are the record of when each arrived. - Name the thread exactly.
--threadtakes a session UUID or the exact session name. If several sessions share a name, use the UUID — a name that matches more than one session is ambiguous, and guessing which one receives your message is how a follow-up lands in the wrong thread. - Queue the message. Send the follow-up with
codex queue --thread <SESSION_ID> --message "...". Keep the message self-contained: the thread may resume hours later, and a follow-up that assumes context from a conversation you had elsewhere will read as a stranger's instruction. - Add
--resumeonly when you want it running now. With the flag, Codex tries to load the thread on the local daemon or the remote server you named. If the resume fails, read the warning, confirm the message stayed queued, and resume the thread yourself later — do not re-queue the same message, or it will arrive twice. - Confirm the preserved settings on the resumed thread. On 0.166.0, acknowledged approvals and permissions survive resume and fork, and reasoning-token accounting survives too. Check the resumed thread's approval state before it acts: preserved settings are the release note's claim, and the thread in front of you is the check.
- When Codex cannot connect, run the doctor before reinstalling.
codex doctor --network-onlyruns only the config, network environment, provider HTTP, and Responses WebSocket checks — the focused set, not the full diagnosis. Read each group in turn: a config failure is a settings file to fix, a network-environment failure is a proxy or DNS problem on your machine, a provider HTTP failure is the provider endpoint, and a WebSocket failure is the live channel Codex holds open. Reinstalling fixes none of those specifically, and it destroys the evidence of which one failed. - Use the full doctor when the focused checks pass. If
--network-onlyfinds nothing wrong and Codex still fails, run plaincodex doctorfor the full installation, config, auth, and runtime diagnosis. The focused run narrows the fault; it does not clear the installation.
Mistakes
- Re-queueing after a failed resume. A failed resume warns and still succeeds, with the message queued. Sending it again queues a duplicate.
- Assuming
--resumeguarantees the thread runs. It tries. The warning is the outcome when it cannot, not an error to work around by retrying the same command. - Queueing a model switch. Queued messages use the thread's existing model. To change models, resume the thread and change it there.
- Reading
doctor --network-onlyas a full health check. It covers config, network, provider HTTP, and WebSocket only. Auth, installation, and runtime health need the fullcodex doctor. - Reinstalling first. A connection failure is usually one of the four check groups. The doctor output names the group; a reinstall names nothing.
Limits
- No session was run to produce this page: the commands and their behaviour are from the 0.166.0 release notes and the installed binary's own help text, read on 2 November 2026. What a resumed thread does with a queued message on your machine is yours to observe.
- The behaviour described is for 0.166.0. Queue and doctor options have moved before — startup options left
codex queue --helpin this same release — and can move again. The version on your machine and the release notes are the authorities, in that order. - This page covers the local daemon and
--remoteserver paths named in the help text. Remote-server behaviour beyond the named endpoint forms was not checked.
Related playbooks
- Codex Security 0.10.0: resume a scan, cap a batch
- Message Threads cut Claude Code waits by a third
- ChatGPT and Codex share one token budget
- Don't resume an Agent SDK session from an untrusted ID
Sources
- https://learn.chatgpt.com/docs/changelog?type=codex-cli
- https://www.gradually.ai/en/changelogs/codex-cli/
Back to: Coding playbooks hub · Also: Build a command-line tool end to end with Codex · Check your Codex and Claude Code config for relay tampering · Run a reasoning task on a schedule with GitHub Agentic Workflows