Field guide / 13 min
Control a long-running CLI session
Plan, steer, queue, compact, inspect, and resume without losing the task boundary.
Codex CLI exposes keyboard-first controls for live work plus top-level commands for saved-session lifecycle. Plan mode improves ambiguous work; status and diff expose state; compact preserves key context; review creates a dedicated inspection pass. Resume, fork, archive, unarchive, and permanent delete keep persisted work explicit.
Verified terminal sequence
- ›
/plan Map the change, risks, and verification before editing - ›
/status - ›
/diff - ›
/compact - ›
/review - $
codex resume --last - $
codex fork --last - $
codex archive <SESSION_ID> - $
codex unarchive <SESSION_ID> - $
codex delete <SESSION_ID>
Working principles
Plan only when it helps
Use /plan for ambiguity, migrations, or risk—not as ceremony before every one-line edit.
State stays observable
/status and /diff expose configuration and working-tree effects before context or scope drifts.
Steer versus queue
Interrupt the current direction only when new information changes it; queue independent follow-up work.
Persisted sessions need lifecycle hygiene
Resume continues history, fork branches it, archive hides inactive work, and delete is permanent. Confirm the target session and checkout before each operation.
Field procedure
- 01
Enter plan mode
Ask Codex to map files, risks, choices, and verification without editing.
- 02
Confirm permissions and context
Use /status before implementation, especially after changing directories or permission mode.
- 03
Steer with evidence
Send a correction into the active turn when a discovered constraint invalidates the current path.
- 04
Inspect and compact
Use /diff frequently; use /compact after long noisy work while retaining decisions and remaining tasks.
- 05
Review or resume
Run /review before acceptance. Resume saved work only after confirming repository state still matches the transcript.
- 06
Manage saved work deliberately
Use fork when you need a separate direction, archive/unarchive for reversible housekeeping, and delete only after identifying the exact session.
PASS / FAIL
Acceptance checklist
- The plan names verification.
- /status matches intended permissions.
- /diff is reviewed before completion.
- Queued requests do not silently expand the active task.
- A session is archived before any permanent deletion is considered.
WATCH / REJECT
Failure patterns
- Using compact to hide unresolved failures.
- Queuing a destructive follow-up without context.
- Resuming a session against a materially changed checkout.
- Deleting a saved session when archive would be sufficient.