Thread Lifecycle
Manage Codex sessions across start, resume, fork, compact, archive, delete, and handoff.
Written and reviewed by Eric Han · Co-founder & CTO, reopt
Worktrees on by default and the background server (0.156.0–0.157.0)
From 0.156.0, worktree support is enabled by default, and the agent command center can filter tasks by status and create worktree sessions directly. Since 0.155.0 the agents overview can hide, archive, and delete tasks, and deleting a clean managed worktree asks for confirmation. From 0.157.0, eligible interactive sessions start the local background server automatically, with recovery choices when server settings are incompatible. Use --no-daemon to bypass it and /daemon to update it (0.156.0). A conversation open in another app can be forked with f from 0.157.0, carrying its draft and queued prompts.
official changelog · 2026-09-26 KST
Experimental worktrees (0.154.0, history)
Use experimental --worktree or /worktree to isolate new/forked sessions. Check availability in the installed codex --help and /worktree menu. Verify the checkout path and branch, then inspect restored permissions on resume. A conversation open in another app appears as a read-only transcript with a retry option.
official changelog · 2026-09-12 KST
Key takeaways
- Long-running work needs thread hygiene; without lifecycle rules a session accumulates stale assumptions, duplicated plans, and unclear ownership.
- Know the lifecycle actions: Start for clean context, Resume after interruption, Fork to explore a variant, Compact to reduce context load, Archive for recoverable cleanup, Delete for permanent transcript removal, and Stop to summarize final state.
- In the 0.142.0-era baseline, check
/usagebefore long goals, scheduled reminders, or broad multi-agent delegation. - In 0.145.0–0.146.0, use paginated history, persisted names/search, pins, named
/newor/clear, side-conversation switching, and paginated forks to keep large thread catalogs navigable. - In 0.148.0, archive or restore from the resume picker, use
codex exec forkfor a non-interactive variant, and verify restored working directory, approval policy, and transcript preview. - In 0.149.0–0.150.0, manage local tasks with
codex agents, message an existing session withcodex queue, use task@mentions, and normalize automatic task titles with/rename. - Make handoffs explicit with current goal and acceptance criteria, files changed, commands already run and their results, known blockers, and the next safe action.
- If the thread no longer reflects actual repository state, stop and re-ground from files and git status before continuing.
Long-running work needs thread hygiene. Without lifecycle rules, the session accumulates stale assumptions, duplicated plans, and unclear ownership.
Lifecycle Actions
| Action | Use |
|---|---|
| Start | New task with clean context |
| Resume | Continue the same task after interruption |
| Fork | Explore a variant without disturbing the main path |
| Compact | Preserve useful state while reducing context load |
| Archive | Remove a completed or abandoned session from active lists while keeping it recoverable |
| Delete | Permanently remove the transcript and spawned descendant sessions |
| Stop | End a task and summarize final state |
0.140.0 to 0.142.0 Lifecycle Notes
/deleteandcodex delete <SESSION>permanently remove the transcript and spawned descendant sessions. Use/archivefor recoverable cleanup./importcan bring supported Claude Code setup, project files, and recent chats into Codex. After import, inspect/diff,/debug-config, and/status./usage daily|weekly|cumulativeshould precede long/goalsessions, scheduled reminders, and multi-agent delegation so token budgets are visible before work expands.
0.145.0 to 0.146.0 Lifecycle Notes
- Experimental paginated history resumes and searches large catalogs without loading every thread, while preserving names and supporting subagent and memory metadata.
/new [name]and/clear [name]name a fresh thread immediately; pin important threads and switch side conversations without closing them.- Forks can use paginated history, and ephemeral forks stay out of normal history lists.
- After replay, import, or fork, verify preservation of messages, final responses, errors, timestamps, and approval settings.
0.148.0 Lifecycle Notes
- Archive and restore sessions without leaving the resume picker.
- Use
codex exec forkto create a non-interactive variant of an existing thread. - Verify the restored working directory, approval policy, and transcript preview before the first turn.
/exportcreates a full Markdown conversation artifact; it does not replace archive or audit logs.
0.149.0 to 0.150.0 Lifecycle Notes
codex agentssearches, starts, opens, renames, and stops tasks on the shared local app-server daemon. The 0.150.1 CLI help also exposes--remote,--remote-auth-token-env,--no-alt-screen, and-C/--cdfor the working directory of new remote tasks.codex queue --thread <THREAD> --message <TEXT>sends a follow-up to an existing session.THREADmust be a session UUID or an exact session name. For a remote app-server use--remotewith aws:,wss:, orunix:endpoint and keep the bearer token in the environment variable named by--remote-auth-token-env.- Task
@mentions let agents read, create, and message tasks. Rename durable work to a team-readable title. - Resume and fork restore the permission profile, but verify both the active profile and working directory before editing.
# Local shared daemon
codex queue --thread <UUID_OR_EXACT_NAME> --message "Run the focused tests and report failures"
# Remote daemon; the option names the environment variable, not the token value
codex queue --remote wss://codex.example.internal \
--remote-auth-token-env CODEX_REMOTE_TOKEN \
--thread <UUID_OR_EXACT_NAME> \
--message "Continue from the last verified checkpoint"Do not use a fuzzy display-name match in automation. Prefer the UUID, and verify that the session's cwd and permission profile are the intended target before queueing a message.
Handoff Checklist
- Current goal and acceptance criteria.
- Files changed or expected to change.
- Commands already run and their results.
- Known blockers or open questions.
- Next safe action.
Failure Mode
If the thread no longer reflects the actual repository state, stop and re-ground from files and git status before continuing.