Trusting a New Project Directory

A directory without version control starts read-only by default — not broken, not misconfigured, just genuinely untrusted until you explicitly decide otherwise, and understanding the actual trust mechanism behind it is what turns a confusing first encounter into an expected, entirely sensible default rather than a mysterious obstacle.

Why trust is directory-scoped rather than account-wide, globally

Trusting one specific project doesn't automatically trust every other project sitting on your machine — the mechanism is scoped specifically to the directory in question, which is exactly the right granularity for a real safety boundary. A blanket "trust everything on this machine" setting would defeat much of the purpose of having a trust mechanism at all, since it would extend automatic confidence to directories you haven't actually had a chance to evaluate.

Why version control is the signal this mechanism relies on

Using version-control status as the trust signal makes practical sense: a version-controlled directory has real history you can inspect, diff against, and roll back if something goes wrong, which is exactly the kind of safety net that makes a more permissive starting posture reasonable. A directory with no version control has none of that — no diff to review, no easy rollback — which is precisely the situation where a more cautious starting point earns its keep.

What actually happens when you trust a directory

Trusting a directory moves it out of the default read-only posture and into the normal Auto behavior a version-controlled project would start with — read, edit, and run within the workspace, with approval needed to step outside it. This is a deliberate, explicit action you're taking, not a passive default; it reflects a genuine decision that this specific directory is safe to work in more freely.

When trusting an untracked directory is obviously fine

A scratch directory you created yourself, a downloaded example project you're about to start experimenting with, a brand-new prototype you haven't gotten around to initializing with git init yet — these are all cases where trusting the directory is a low-risk, sensible thing to do, since the directory's contents and provenance are already known and understood by you.

When it's worth pausing before trusting

A directory whose contents you didn't create and haven't reviewed — something downloaded from an unfamiliar source, an archive extracted from somewhere you're not fully confident about — deserves genuine scrutiny before trusting it with write access, the same scrutiny you'd apply before running any unfamiliar code directly on your machine. The read-only default exists specifically to create a natural pause at exactly this moment, and skipping past it reflexively defeats the purpose of having the default at all.

Initializing version control as an alternative to trusting directly

For a project that's genuinely going to be a real, ongoing piece of work, running git init rather than simply trusting the untracked directory gets you both the normal Auto posture and the actual safety net version control provides — diffs, history, an easy rollback — which is a strictly better position than trusting an untracked directory outright. This is worth doing as a first step for any new project you expect to keep working on, rather than working untracked and trusted, which gives up real safety with nothing gained in return.

Revisiting trust as a directory's status changes

A directory trusted once, untracked, that later gets initialized with version control doesn't need re-trusting — it simply starts qualifying for the normal Auto default going forward. It's worth keeping this relationship between trust and version-control status in mind as projects evolve from quick scratch work into something more established, since the appropriate posture for a directory can genuinely change as its own nature changes.

The underlying principle worth taking away

This default is a small, specific instance of a pattern worth recognizing across all of Codex's safety mechanisms: the system defaults to caution specifically where less is knowable about a given context, and grants more latitude specifically where more is knowable — version history, established conventions, a track record. Understanding that principle makes every individual default, this one included, feel like a reasoned choice rather than an arbitrary restriction to work around.

What this looks like the very first time you hit it

For most people, the first encounter with this default happens unexpectedly — pointing Codex at a fresh directory expecting the same behavior as every other project, then being confused when an edit gets refused with no obvious explanation. Recognizing this specific symptom quickly, rather than assuming something is broken, is the actual practical value of having read this page before hitting it rather than after.

A quick reference for the decision itself

New, self-created directory you already understand: trust it directly, or better, run git init first. Downloaded or unfamiliar content: review before trusting, the same scrutiny you'd give any unfamiliar code before running it. Anything in between: default toward the more cautious option, since the cost of a brief pause is far lower than the cost of a mistake made under an unwarranted assumption of safety that turned out not to be justified.

Why this default earns trust over time rather than losing it

The first time this default interrupts a task, it can feel like an obstacle. Once you understand the actual mechanism — a deliberate, narrow, well-reasoned check tied specifically to a genuinely useful signal — it tends to become one of the defaults people appreciate rather than resent, precisely because it's protecting against a real and common mistake rather than an imagined or overly broad one.