Skip to main content
← All posts
A 30s East Asian woman software engineer in a charcoal merino sweater at a dark walnut desk at dusk, editing a JSONL Codex CLI session file on a 14-inch matte black laptop, screen split between a plain text editor with a highlighted user turn in warm coral and a terminal listing the ~/.codex/sessions directory, warm brass desk lamp rim light, Monocle magazine editorial composition.
·6 min read

Edit Previous Codex CLI Message Without Losing Context

Codex CLI has no edit button. Here are three safe ways to edit a previous message, keep tool-call context intact, and avoid the two mistakes that break resume.

Codex CLI treats every chat as an append-only JSONL file, which means there is no built-in "edit this previous message" button like the ChatGPT web UI gives you. That does not mean you are stuck. The transcript lives on disk as plain events, so a careful rewrite plus a resume gives you the same effect without burning the rest of your session. This guide walks through three ways to edit a previous Codex CLI message, keep tool-call context intact, and avoid the two mistakes that silently nuke the thread.

If you have ever hit up-arrow seven times, found the prompt you wanted to fix, and realized Codex only replays prompts rather than rebranching the conversation, this is the fix. The CLI stores enough state that a two-minute file edit beats restarting from scratch, as long as you do it on a copy and preserve the event schema. Our file-location reference on where Codex CLI stores every session JSONL is the companion piece: keep it open in the next tab if you need the exact paths before you touch anything. Everything that follows assumes you have located the right session file and exited the live CLI before opening it.

The real reason edit feels missing in Codex CLI

The web ChatGPT edit affordance is a UI convenience, not a model capability. Behind the scenes it truncates the context at your edited turn and replays the conversation forward with the new prompt in place of the old one. Codex CLI exposes the raw mechanism rather than the convenience layer, which is why it looks like edit is missing. Every session is a JSONL file at ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl, and each line is one event: user turn, assistant reply, tool call, diff, or shell result.

Because the file is a sequence of ordered events, you have more power than the web UI gives you, not less. You can truncate at any turn, not only user ones. You can edit the assistant reply if you want to steer context without rerunning a tool. You can even splice in a synthetic turn to inject a reminder the model keeps forgetting. The constraint is that Codex only loads the file cleanly if the schema stays valid, which means you keep every top-level field the CLI originally wrote and resume from a copy rather than the live file.

The three safe ways to edit a previous message

There are three workable patterns, ranked from least to most invasive. Pick the lightest one that solves your problem, because every extra edit is one more place a schema mismatch can bite you. Only reach for the full rewrite when the earlier message set the whole conversation on the wrong track. The three patterns map to three failure modes: a small factual slip, a prompt that steered one answer wrong, and a seed prompt that poisoned every turn after it.

  • Append a correction turn: start a new user message with "Correction, I meant X" and let the model self-adjust. Cheapest, keeps the full trail, best for small factual slips.
  • Branch from the edited turn: duplicate the JSONL, truncate at the message you want to fix, rewrite that one line, resume Codex against the copy. Right default for most real edits.
  • Full rewrite with context carry: export the session to markdown, hand-edit the chronology, feed it back as a long system prompt in a fresh session. Use when the first few turns were wrong and everything downstream inherited the mistake.

The append pattern is underrated because it costs nothing and keeps the original artifact clean. The branch pattern is what you want nine times out of ten, since it preserves tool-call provenance up to the edit point. The full rewrite is a nuclear option that discards tool-call provenance, so only use it when the session is already past rescue. Each of these is reversible as long as you kept the original file untouched, which is why every workflow below starts with a copy.

The branch-from-session workflow step by step

Start by locating the live session file in ~/.codex/sessions/YYYY/MM/DD/. If you are mid-session, exit Codex cleanly before copying so the final event is flushed to disk. Make a working copy of the JSONL under a sibling name like rollout-<timestamp>-<id>-branch.jsonl, which keeps the original untouched as a rollback artifact. Open the copy in a plain text editor that can handle long lines, since each JSON event can run several kilobytes wide.

Find the user turn you want to edit by scanning for the "role":"user" events in order. Delete every event after that turn, including the assistant reply and any tool calls that followed. Rewrite only the content field inside the user event you kept, leaving all other fields intact: the role, the timestamp, the message id, and anything else the CLI wrote. Save the copy, then start a new Codex session that resumes from the branched file. Codex replays the ordered events as prior context, and the assistant produces a fresh continuation from your edited turn forward. For a deeper walkthrough of the raw JSONL event shape, our longer Codex CLI history guide covers each field type.

Keeping context intact when you rewrite

The two mistakes that silently break a branch are the same two that break any JSONL resume. First, do not edit the file that is currently open in a running Codex process, because the CLI holds a write handle and your changes will be overwritten by the next flushed event. Always exit first or branch to a copy. Second, keep the event schema intact on every line you touch, since the parser rejects partial events and silently truncates on malformed ones. The safest guardrail is to only rewrite the string inside the content field, never the surrounding JSON structure.

If your edit targets a turn that was followed by a tool call, decide whether you want that tool call to re-run or not. Dropping it means the assistant has no shell output in context, which usually produces a weaker reply. Keeping it means the context mentions results from a command that was answering the old question. The cleanest fix is to re-run the tool against your edited prompt in a fresh invocation and splice the fresh output back in, which our shorter file-paths quick-reference gives you the exact locations for. On schema questions, the OpenAI platform docs at platform.openai.com/docs are the authoritative source for the current event names.

FAQ

Can I edit a Codex CLI message without exiting the session?

No, and the failure mode is quiet. The CLI holds a write handle on the live JSONL and will overwrite any inline change on the next flushed event. Your edit vanishes and the session continues as if nothing happened. Exit cleanly first, branch to a copy, edit the copy, then resume Codex against the copy.

Does editing a previous message lose the tool-call history?

Only the tool calls after your edit point are lost, because those events get truncated along with everything else downstream. Everything before the edit stays in context exactly as it was. If you need a tool result from after the edit, re-run that command in the resumed session and splice the output back. Most workflows do not need the dropped calls, since the whole point of the edit was to steer the session in a different direction.

What if I only want to fix a typo in my last prompt?

Append a correction turn instead of branching. Something like "Correction, I meant Y instead of X" is cheaper, keeps the full artifact, and the model handles it fine for small changes. Reserve the branch workflow for prompts that steered the answer meaningfully off course, since every branch is one more file to manage. For a one-word typo, the append pattern is almost always the right call.

Where exactly are the session files on Windows?

Every session JSONL lives under %USERPROFILE%\.codex\sessions\YYYY\MM\DD\ with backslashes instead of forward slashes. The directory layout matches macOS and Linux so any branch script you write on one platform ports with a path swap. The prompt-history file sits separately at %USERPROFILE%\.codex\history\history.jsonl and is read-only for up-arrow recall. If either path is missing, confirm the CLI has run at least once and that persistence is enabled in config.toml.

Open your Codex sessions as clean, searchable markdown.

Free to start — no credit card.

Try Prism MD free →

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