Keeping Editor and CLI Context in Sync

A file open in your editor and the same file as Codex sees it on disk are two separate views of the same underlying data, and they can genuinely diverge — an unsaved edit in your editor that Codex's filesystem read won't see, or a Codex-made change that your editor hasn't yet noticed and reloaded. Neither divergence is dangerous on its own, but working from a stale view of either side is a reliable source of confusing, hard-to-diagnose mistakes.

Why this divergence happens at all

Codex reads and writes files directly on disk; your editor maintains its own in-memory representation of open files, typically synced to disk on save (or, depending on your editor's settings, sometimes not even then without an explicit save action). If you have unsaved changes in your editor when Codex reads a file, Codex sees the last-saved version, not your in-progress edits — a gap that's invisible unless you're specifically thinking about it, and one that can lead Codex to propose a change based on an outdated understanding of what the file actually currently contains.

The most common failure mode: editing while Codex is also working

Making your own manual edits to a file in the same window of time a Codex session is also actively working can produce exactly the kind of confusing divergence this page is about — Codex might overwrite your unsaved manual edit without ever having seen it, or your manual edit might conflict with a change Codex just made that your editor hasn't reloaded yet. The safest practice, especially for anything beyond trivial concurrent edits, is avoiding manual edits to files a session is actively working on until that session's current turn has completed.

Making sure your editor picks up Codex's changes

Most modern editors detect and offer to reload a file that's changed on disk since it was opened, but it's worth confirming this is actually happening as expected rather than assuming it — an editor silently showing a stale, pre-Codex-change version of a file, with no visible indication anything's out of sync, is exactly the scenario that produces a confused review where you're reading code that no longer matches what's actually on disk.

Saving before starting a Codex session, every time

The simplest, most reliable habit for avoiding this entire class of problem: save any unsaved manual edits before starting or continuing a Codex session, every single time, without exception. This ensures Codex is always reading the actual, current state of your work rather than a stale on-disk version that's missing your latest unsaved changes — a small, consistent discipline that eliminates most of the divergence this page describes before it ever has a chance to happen.

What happens to editor state Codex can't see

Codex has no visibility into your editor's UI state — which file you have open, your cursor position, unsaved selections or in-progress multi-cursor edits — none of that is part of what Codex reads from disk. This is worth remembering specifically if you're mid-way through a delicate manual edit and considering starting a Codex session on the same file: your in-progress editor state isn't context Codex has any access to, only what's actually saved to disk.

Reloading after a large multi-file Codex change

After a Codex session makes changes across several files, it's worth explicitly confirming your editor has reloaded every touched file, not just the one you happen to currently have in view — an editor that's only refreshed the actively-viewed file while several other changed files sit stale in background tabs can produce a misleading picture if you later switch to one of those tabs expecting it to already reflect current changes.

Why this matters more in a fast-moving agentic workflow than it used to

Version control workflows have always had some version of this problem — files changing on disk from a source other than your own editor, whether a colleague's push or a build tool's generated output. What's different with a fast-moving Codex session is the frequency: changes can happen every few seconds across a working session, which makes staying actually synced a more continuous, active concern than it was when disk changes from outside your editor were a comparatively rare event.

A simple standing habit that covers most of this

Save before starting, confirm your editor's reload behavior is actually working as expected, and avoid manual edits to files mid-session unless you're deliberately pausing to make one. These three habits, consistently applied, cover the overwhelming majority of the divergence scenarios this page describes, without needing any special tooling beyond what your editor and Codex already provide.

Signs worth watching for that something has drifted out of sync

A Codex response that references code you're confident you already changed, a diff that seems to be modifying a version of a file that doesn't match what your editor is currently showing, or an edit that appears to silently undo a change you made moments ago are all worth treating as a sync problem first, before assuming Codex made an error or misunderstood the task. Confirming both sides are looking at the identical, current file state is a fast, cheap check that resolves a surprising fraction of otherwise confusing-looking session behavior.

Why this is worth internalizing rather than treating as a rare edge case

It's tempting to treat editor-CLI divergence as an unusual event that only matters in unusual circumstances, but the underlying condition — two independent views of the same file, updated at different times by different actors — is present in every single Codex session that touches a file you also have open. Most of the time it resolves itself invisibly because saves and reloads happen quickly and nobody's editing concurrently; understanding the mechanism is what lets you recognize the rarer cases where it doesn't resolve cleanly on its own.