Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

  1. 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.
  2. Name the thread exactly. --thread takes 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.
  3. 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.
  4. Add --resume only 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.
  5. 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.
  6. When Codex cannot connect, run the doctor before reinstalling. codex doctor --network-only runs 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.
  7. Use the full doctor when the focused checks pass. If --network-only finds nothing wrong and Codex still fails, run plain codex doctor for the full installation, config, auth, and runtime diagnosis. The focused run narrows the fault; it does not clear the installation.

Mistakes

Limits

Related playbooks

Sources

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