Thread Lifecycle
Manage Codex sessions across start, resume, fork, compact, archive, delete, and handoff.
Experimental worktrees (0.154.0)
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.