Codex App Link

scripts/codex-thread.mjs drives Codex threads from the terminal. It sends messages through the Codex desktop app, works whether or not the thread is in the foreground, and reads replies from Codex's own session files. By default, output is compact text, to save tokens in an agent's context:

• one line of key=value scalars;
• then the agent's reply (lastAgentMessage) as raw, unescaped text.

Add --json only when you need every field. Do not pipe JSON through jq into your context. Errors are one-line JSON on stderr, with exit code 1.

Set CT to the script inside this skill's base directory, fresh in every session:

CT=<skill-base-dir>/scripts/codex-thread.mjs
node $CT version        # confirms the version and path you are actually running

Never reuse a .../codex-app-link/<version>/... path remembered from an earlier session or a summary. Plugin updates install side by side, so an old path keeps running the old version and misses its fixes and scripts.

Requirements: macOS, the Codex desktop app (ChatGPT.app) running, and Node.js 22.5 or later (the script reads Codex's thread index through node:sqlite).

Multiple Codex instances: set CODEX_HOME to the instance's home (for example CODEX_HOME=~/.codex-work) on every command. The script then uses that instance's socket, thread index and session files. open codex://... always reaches the default instance (~/.codex), so for any other instance the script loads a thread by sending the codex://threads/<id> link as a GetURL Apple Event to the process that owns that instance's socket. The first use may trigger a macOS Automation prompt. If no process owns the socket, it fails with not-loaded-in-instance.

Command	Purpose
node $CT list [--limit N] [--cwd DIR]	Recent threads (id, title, cwd, updated)
node $CT status <id>	status (idle/active), current turnId, lastAgentMessage, loadedInApp
node $CT new --cwd DIR --text "..." [--timeout SEC] [-- <codex exec args>]	Create a thread with the CLI, run its first turn, then load it in the app. Returns threadId and finalMessage
node $CT send <id> --text "..." [--wait] [--timeout SEC]	Start a turn in an idle thread through the app. --wait blocks until it finishes and returns lastAgentMessage
node $CT send <id> --text "..." --steer	Add a message to the turn that is running now
node $CT wait <id> [--timeout SEC] [--settle SEC] [--stall SEC] [--until-question] [--expect REGEX]	Block until the thread is done (see "Waiting for results"). Prints result: done, stalled, timeout, question or paused (exit 0, 3, 4, 5 or 6), plus lastAgentMessage
node $CT read <id> [--last N]	Final replies of the last N turns
node $CT result <id> [--marker RESULT] [--turns N]	The latest RESULT block in recent replies (in or out of a code fence), parsed into key=value lines. Exit 6 if there is none
node $CT watch (<id>... | --tracked) [--expect REGEX] [--cursor FILE]	One event line per STARTED, QUESTION, APPROVAL, COMPACTED, MAINTENANCE (if configured), RESULT, PAUSED, DONE, STALLED, MISSING, FOUND or UNPARSED (a complete session line that failed to parse: an event may be lost, so read the thread), across several threads (see "Managing several threads")
node $CT track add <id> --name N [--role R] / track rm N / track list	The project's thread registry at <git root>/.codex-app-link.json. Every command then accepts the name in place of the ID
node $CT version	The plugin version, script path and registry path
node $CT questions <id> [--all] [--since ISO]	Formal questions the thread asked (request_user_input*), unanswered by default, with options and the answer. Exit 5 if any are pending
node $CT open <id>	Make the app load a thread without sending anything
node $CT access <id> full [--no-open]	Set the thread's access the way the composer's selector does (Full access). It applies from the next turn, or to the running turn. Use it after an app restart: the app reloads threads under a restricted profile (workspace write, network off)

Long messages: --file path or --stdin instead of --text.

Waiting for results: the only supported method

Run exactly this as a background command, and act when it exits:

node $CT wait <id> --timeout 10800        # run_in_background; one command, no loops

• It waits for the thread, not a turn. It returns when the thread has been continuously idle for --settle seconds (default 45). Codex often chains turns: compaction, auto-continue, or context maintenance by other plugins. A turn can also end without a normal completion event. The settle window absorbs chained turns, and nothing is pinned to a turn ID.
• It cannot hang silently:
  • result: "stalled" (exit 3): the thread claims to be active, but its session file has not been written for --stall seconds (default 2700, 45 min). Verify before acting: a silence of 15+ minutes is normal while a high-effort model reasons, or while a long command runs, because neither writes to the session file until it finishes. Check the last session-file write and running processes. If it is still writing or a process is running, restart wait. Treat the turn as dead only if it stays silent past the threshold with nothing running.
  • result: "timeout" (exit 4): the overall --timeout (default 3h) was reached. The current state is printed.
• On exit, read result and lastAgentMessage from its output, then judge the work yourself. Do not require a particular reply format.
• Questions don't end a wait unless you ask. Codex asks formal questions with request_user_input_async. It is accepted at once and the turn keeps running, so a plain wait never returns for it, and the worker proceeds on its own default. Use wait --until-question (result: "question", exit 5), or run codex-progress.py, which prints QUESTION lines. Then answer with send <id> --steer. Run questions <id> before closing out any handoff.

Never do any of these (each has caused missed completions):

• wait on a specific turn ID (wait --turn X, or send --wait followed by its turn);
• loop on a regex for an expected report string (e.g. RESULT slice=);
• write hand-rolled shell loops around wait or status.

--turn is still accepted, but it only lets an earlier finish count; it never blocks on that turn.

Watching progress live (process work)

wait reports only that a thread finished. For process work, meaning live QA tests, computer-use or UI driving, deploys and ops steps, also stream the thread's progress, so that a blocked approval prompt, a missing plugin runtime or a stalled step surfaces within minutes:

python3 <skill-base-dir>/scripts/codex-progress.py <id> 240   # run under a background monitor

It prints one line per new assistant note (NOTE), formal question (QUESTION, with its options), approval-request event (APPROVAL_WAIT) and turn end (TURN_END). After 240 seconds without a session write it prints a SILENT line; check it before acting, because a silent model may just be reasoning. Run it alongside wait, not instead of it. Ask the Codex worker to post a short progress note after every step. For implementation work (coding a scoped handoff, running tests, opening a PR), wait alone is enough. Stop the monitor when the turn ends.

Managing several threads: track, watch, result

When you run more than one worker, or anything long, use the manager kit rather than separate waits:

1. Name the threads once per project: node $CT track add <id> --name sol-b --role "worker: render". The registry is a small JSON file at the git root, so every later manager of the project inherits the roster. Commit it.

2. Run one watch for all of them, as a background monitor, and re-arm it when the monitor expires:

   node $CT watch --tracked --expect '^RESULT ' --cursor .codex-app-link.cursor.json
   

   --cursor saves offsets and turn state after every poll, so a re-armed watch resumes exactly where the last one stopped and loses nothing in between. Keep the cursor file out of git.

3. Act on each event:

   Event	What to do
   QUESTION	Answer now with send <name> --steer. The worker keeps going on its default otherwise
   PAUSED	The thread went idle without its result: a compaction pause, a "waiting for controller resume" stop, or a crash. Read its last reply, then resume it with send
   RESULT	Reported as soon as a reply containing a matching line is written, including mid-turn (one event per matching line, so chained work reports each result). Run node $CT result <name>, then verify the work yourself. Anchor --expect to the result line itself (for example '^\s*RESULT (handoff|research)='), so replies that merely mention it don't match
   STALLED	Check before acting: long reasoning and long commands write nothing
   COMPACTED, STARTED, MAINTENANCE	Context. MAINTENANCE appears only if you configured a maintenance controller's patterns (below)

| APPROVAL | It may need you in the app |

Context-maintenance controllers (optional). Some setups run a controller, such as Jevpact, that asks a worker to pause before compaction and sends a resume afterwards. Its wording is configurable, so the kit matches nothing by default. To see those steps as MAINTENANCE events, and to stop them counting as answers to questions, add the patterns your controller actually sends to the registry:

"automation": { "pause": "prepare to compact", "resume": "continue the existing unfinished assignment" }

(or pass --pause-pattern / --resume-pattern). Copy the patterns from a real message in your own rollouts, not from these examples. Whether or not a controller is present, a worker that goes idle without its RESULT shows up as PAUSED. A controller may skip its resume when it judges the work done, and can be wrong.

Ask every worker to end with a RESULT block (RESULT key=value …) and to treat only that block as the end of its task. --expect is what tells a finished worker from one that stopped short.

Managing a project through Codex threads

When the user onboards you as the manager of work that Codex threads carry out, read these once before acting:

• references/strategic.md: roles, likely thread configurations (including the recommended coordinator-plus-work-threads setup), onboarding questions, and how to read the state of a project from its threads.
• references/operational.md: the dispatch, review, wait, verify and merge loop, authority rules, and lessons from real orchestration.
• references/companions.md: how to use MSW, MSL and Timebox when the project has them, and how to offer them when it does not.

For a single message to a thread, the commands above are enough.

Orchestration pattern

1. new to create a worker thread, or take an existing thread ID from the user.
2. send, then start node $CT wait <id> as one background command and do other work until it exits (see "Waiting for results"). Use send --wait only for short foreground turns; it uses the same thread-level wait.
3. Give Codex file paths to read, not pasted content. Ask it to end its turn with a clear result line you can parse.
4. Report the thread ID to the user so they can open it in the app.

Rules

• Do not message a thread you did not create unless the user named it and asked you to. The user may be working in it.
• send refuses (thread-busy) while a turn is running. Use wait first. Use --steer only when the new instruction must change the running turn.
• Never run a CLI process on a thread (codex resume, codex exec resume) while the app owns it. Only one Codex process may hold a thread.
• New threads inherit ~/.codex/config.toml defaults (model, sandbox, approvals). Pass codex exec flags after -- to change them, for example -- --skip-git-repo-check outside a git repo, or -- -s workspace-write.
• Clean up test threads by archiving them in the app. codex archive <id> returned "failed to archive session", with no further detail, for threads the app had loaded (2026-10-06; cause unconfirmed).

How it works

• Sending: the app listens on a private socket, ~/.codex/ipc/ipc.sock. Each message is JSON with a 4-byte little-endian length in front. The script sends initialize, then thread-owner-discovery to find the app client that has the thread loaded, then thread-follower-start-turn (idle) or thread-follower-steer-turn (busy) to that client. This was learned from the Jevpact Codex plugin (plugins/jevpact/src/codex.js).
• Loading: the app only answers for threads it has loaded. When a thread isn't loaded, send and new open codex://threads/<id> with open -g. That loads it in the background, but can switch the thread shown in the app window. --no-open disables this. This only happens for the default instance; see "Multiple Codex instances" above.
• State: the thread index is ~/.codex/state_5.sqlite (table threads, read-only). Turn state and replies come from the thread's rollout JSONL: task_started means busy; task_complete (which carries last_agent_message) or turn_aborted means idle.
• Creating: new runs codex exec --json using the CLI bundled with the app (/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex, override with CODEX_BIN). The older codex on PATH (nvm) may reject the configured model.
• Queued messages: codex queue --thread <id> --message ... stores a message that runs only when a client loads the thread. Opening the thread delivers it at once, so check status after open before sending.

The socket protocol is private and undocumented. It was verified on 2026-10-06 against app CLI 0.160.0. If a Codex update breaks it, request-version-mismatch or no-handler-for-request errors appear. Re-check the method versions in the app bundle with strings app.asar | grep thread-follower-.

Troubleshooting

Error	Meaning / fix
app-not-running	Start the Codex desktop app (ChatGPT.app)
not-loaded-in-app	Deep link did not load the thread within 30s. Open the thread in the app manually and retry
A thread's commands fail with EPERM, no network, or no Simulator after the app restarted	The app reloaded it under a restricted profile. Run access <id> full, then check the next turn: the rollout's turn_context shows sandbox_policy danger-full-access
not-loaded-in-instance	No running app owns the CODEX_HOME instance's socket. Start that instance (or open the thread in it) and retry
thread-not-indexed	Wrong ID, or the thread was created on another machine
thread-busy	A turn is running. wait, or send --steer
thread-follower-start-turn-timeout, or not-loaded-in-app on a thread that loads late	The turn often did start anyway. Run status <id> before retrying; resending would deliver the message twice
request-version-mismatch / no-handler-for-request	The app's private protocol changed. See "How it works"
new returns exitCode: 1 and no finalMessage	The first turn failed. Read the rollout's task_complete event; often an unsupported model or a CLI version mismatch