
Codex CLI: Branch Conversations & Edit Previous Messages (2026 Guide)
A hands-on walkthrough for branching a Codex CLI conversation, editing earlier messages without losing tool-call context, and resuming from any turn.
Codex CLI is fast, but it has no branch button and no edit button. When you want to go back three turns, change a prompt, and try again without blowing away the tool calls that got you there, you are on your own. This guide shows the safe ways to branch a conversation and rewrite an earlier message, which files to touch, and the two silent mistakes that will break your resume. If you want to find or export older sessions first, our earlier guide covers where Codex CLI stores every chat on disk, and a shorter companion walks through the file paths and quick read commands. Start with one of those if your sessions directory is a mystery, then come back here.
Why Branching Codex CLI Is A Manual Job
Every Codex session is a single append-only JSONL file. Each turn is one line: a user message, an assistant reply, a tool call, or a tool result. Resume works by replaying the whole file back into the model as prior context, which is why the design assumes a conversation is linear. There is no built-in UI to fork a session or rewrite a line, because the shipped product treats history as immutable.
In practice, long sessions drift. A bad instruction four turns ago quietly poisons every answer after it, and once the drift sets in, prompting your way out rarely works. You want the tool calls and file reads from turns one through three, but a different user message at turn four. That is a branch, and until the CLI grows a command for it, you make it yourself with a file copy and a text editor. The official OpenAI Codex CLI docs describe the resume flag in detail but do not cover branching, so the rest of this guide is the missing manual.
The session file layout matters here because every edit rule flows from it. Codex writes to ~/.codex/sessions/<session-id>.jsonl, one file per conversation, with turns in strict chronological order. Open one and you will see entries like {"role":"user","content":"..."} followed by {"role":"assistant","content":"..."} and then tool-call and tool-result pairs. Resume reads top to bottom and feeds every line back as prior context, which means removing a tool result while keeping its tool call confuses the model about what it already did. Edit a user turn but leave the old assistant reply below it, and the model thinks it already answered the new question. Both failures are silent, which is the whole reason this guide exists.
Method 1: Branch By Copying The Session File
This is the safest method and the one I use daily. The core idea is simple: never edit the live session, always work on a copy, and let the original stand as the point you branched from. Done right, the original session stays intact, you get a second timeline with all the earlier tool calls preserved, and if the branch goes badly you throw it away without consequence. The whole dance takes about twenty seconds once the shell function is set up.
The flow is short enough to memorise, and the steps below are the entire procedure. Each one takes a second or two in practice, and the whole sequence is safe to abort at any point before the final resume. Read it once, then do it once, and it becomes muscle memory. The commands assume macOS or Linux, though the Windows equivalents are trivial substitutions:
- Find the session with
ls -lt ~/.codex/sessions | head, which sorts newest first. - Copy it to a fresh UUID:
cp ~/.codex/sessions/old.jsonl ~/.codex/sessions/$(uuidgen).jsonl. - Open the copy in a plain text editor and scroll to the turn you want to branch from.
- Delete every line below that turn and save the file.
- Run
codex resume <new-session-id>and you are inside the forked conversation.
If you branch often, save that copy step as a shell function so you do not retype it. The three-line version lives in a gist linked from the Codex CLI community thread and takes about ten seconds to adapt. A good branching function also stamps a short human-readable suffix on the new filename, which makes a sessions folder with four live branches far less confusing when you come back the next morning. Give each branch a two-word suffix describing what you changed and your future self will thank you.
Method 2: Edit A User Message In Place
Sometimes you do not want a branch, you want the same session with one earlier user turn rewritten. This is riskier because resume uses the full file, so a sloppy edit corrupts the conversation in ways that only surface three turns later. The rules below keep the edit honest and the context intact. Follow them in order and the model will behave as if you had phrased the message right the first time. If you skip steps, you will spend the next hour debugging why the model is answering a question nobody asked.
Only edit lines where role is user, never touch assistant or tool lines, and change the content field only while leaving the timestamp and role untouched. After editing, delete every assistant and tool line that came after the edited turn so the model is forced to regenerate its response against the new text. Keep tool calls from earlier turns intact, because those are the context you are preserving and the whole reason you chose edit instead of a full restart. If you need a deeper pass on this exact pattern, our earlier post on editing a previous Codex CLI message without losing context walks through two further variants.
A correct edit looks like this. Lines one through five stay untouched, carrying a user turn, an assistant reply, a tool call, a tool result, and a second assistant reply. Line six is your rewritten user message, with only the content field changed. Lines seven onward are deleted entirely, including any tool chatter the model produced in response to the old wording. Resume, and the model answers the new line six with full memory of what it did in lines one through five, which is exactly the shape you wanted.
The edge case worth calling out is a branch point that lands in the middle of a tool-call sequence. Codex CLI expects every tool call to be followed by its matching tool result, and cutting between them will either crash resume or produce a hallucinated result on the next turn. The rule is always cut after a tool result, never between a tool call and its result, and if you must branch exactly on a tool call, delete the call too and let the model reissue it on resume. You lose one roundtrip and keep correctness, which is almost always the right trade.
Mistakes That Will Break Resume
Two patterns cause the vast majority of broken resumes, and both are invisible until the conversation has already drifted. The first is editing assistant turns, which feels harmless but quietly rewrites history from the model's perspective. The model believes its own past outputs, so if you rewrite an assistant reply, every turn after it is built on a lie and the whole session drifts. The fix is simple: treat assistant lines as read-only, always. The second is orphan tool calls, which happen when a tool_call line is left in the file without its matching tool_result on the next line. Some Codex CLI versions crash on resume when they see this, and the worse versions keep running and quietly invent a result, which poisons every subsequent answer. Always keep tool calls paired with their results, and when in doubt delete the pair together.
A small workflow goes a long way when you branch often. Name your branches with a short suffix on the filename rather than relying on raw UUIDs, since four UUID filenames in the sessions folder are nearly impossible to tell apart under time pressure. Keep a scratch note with one line per branch describing what changed, delete the branches you did not keep within a day, and export the winning branch to markdown and save it somewhere outside the sessions folder. That exported markdown becomes your reference for next week, and reading it in a clean reader like Prism MD is far less painful than rereading raw JSONL. For a deeper look at why these failures stay invisible until much later, the JSONL spec primer is a five-minute read and worth it before you start editing session files.
FAQ
Does Codex CLI have a built-in branch command?
No. As of November 2026 there is no codex branch command and nothing on the public roadmap that behaves like one. Branching is a manual file operation on the session JSONL, and the workflow in this guide is the closest thing to an official path. Expect this to stay true until the CLI ships a UI for forked timelines, which it has not signalled yet.
Can I edit a user message using the Codex CLI itself? No, the CLI has no edit mode and no in-place rewrite command. You edit the session file directly on disk while Codex is not running, and you follow the Method 2 rules above to keep resume honest. The lack of an edit mode is deliberate: the design assumes history is append-only, so the authors did not build affordances for rewriting it. The workaround is the whole reason this guide exists.
Will branching affect the original session?
Not if you copy the file first. Method 1 leaves the original untouched and gives you a parallel timeline you can throw away without consequence. Methods based on in-place edits do modify the original, so make a backup before you cut. A one-second cp is cheap insurance against an hour of lost context.
What happens if I edit a session file while Codex CLI is still running? The outcome is unpredictable and usually bad. Close the CLI completely before editing a session file, then reopen it with the resume flag once your edits are saved. Some versions cache the file in memory and overwrite your edits on exit, which is a frustrating way to lose ten minutes of careful surgery. Treat the CLI and the file like two writers that must never hold the pen at the same time.
Codex CLI treats conversations as linear, but your actual work is not, and the shipped product leaves the gap between those two facts for you to close. Copy the session file before you cut, cut cleanly on turn boundaries so every tool call keeps its matching result, never rewrite assistant turns under any circumstance, and name your branches so you can tell them apart the next morning. Those four rules cover ninety percent of branching work and will keep resume honest for as long as the current session format sticks around. The remaining ten percent is judgment, and judgment comes from doing it a few times and watching what breaks when you skip a step.
Related reading
Ready to read your own AI documents?
Open ChatGPT, Claude, Gemini, or any markdown file in the reader built for the way models write.
- ✓Renders code, math & Mermaid out of the box
- ✓Works offline once you've opened a doc
- ✓Free forever for personal reading


