Codex AGENTS.md Not Loading in Symlinked Workspaces: v0.138 Fix (2026)

If you set up Codex CLI inside a symlinked workspace and the model pretends AGENTS.md does not exist, you are not crazy—you are on v0.137 or earlier. The v0.138.0 release on June 8 2026 fixes exactly this, in two PRs that quietly rewrote how Codex resolves instruction paths.

The failure pattern is consistent. You cd into a project. You have a perfectly valid AGENTS.md one or two directories up. Codex starts, the model ignores every rule in that file, and you spend an hour wondering whether you misnamed something. The cause is almost never the file. It is the path Codex used to look for it.

Is Codex Loading Your AGENTS.md? The 30-Second Diagnosis

Run these three commands from your workspace root, in order. Stop at the first row that flags a problem.

If step 1 prints 0.137.x or older and your workspace path traverses a symlink—anywhere from ~/work pointing at an external SSD to a Docker bind mount to an SSHFS share—stop reading and run npm install -g @openai/codex@latest. Re-run step 2. Across the reports tracked on the Codex issues board, this single upgrade clears the silent skip in the large majority of cases.

If step 1 already prints v0.138+ but step 2 comes back without your project file, the file or the discovery walk is still being shadowed. Skip to “Common AGENTS.md Loading Errors and Fixes” further down.

When to Apply These Fixes (and When to Switch Models Instead)

Not every “AGENTS.md not loading” symptom should be fixed inside Codex. Some setups never fit the discovery model, and forcing them costs you a day.

Upgrade and fix in place when

• You are on v0.137 or earlier and your AGENTS.md sits behind a symlink, NFS mount, or bind mount.
• You moved a monorepo into a worktree and nested AGENTS.md files stopped loading.
• Remote Codex on a sandbox VM no longer sees your project’s AGENTS.md.

Stop fixing and switch your runtime or model when

• You are maintaining a pre-v0.91 workflow that relies on relative-path symlinks for .agents/skills. Issue #9898 was closed as not planned. That resolution rule is not coming back. Convert symlinks to real directories, or move to a CLI that follows symlinks natively.
• Your merged AGENTS.md exceeds 32 KiB. The project_doc_max_bytes cap silently truncates the farthest-from-cwd files first. Tighten the instructions before tightening the tool.
• You only wanted Codex-tuned reasoning and never cared about the CLI. Point your existing OpenAI SDK at https://api.ofox.ai/v1 and call openai/gpt-5.3-codex directly. The model has codebase-navigation training baked in and does not depend on AGENTS.md discovery at all.

Stop rule. If you have upgraded to v0.138, codex doctor reports a healthy install, and the file still does not load, stop debugging Codex’s discovery code. The bug is now in your filesystem—wrong permissions, an empty stub file, or an override file shadowing yours. Jump straight to the verification steps in the next section.

Understanding Codex AGENTS.md Discovery: How v0.137 Failed and v0.138 Fixes It

The official AGENTS.md discovery rules are short. From the Codex AGENTS.md guide:

1. Global. ~/.codex/AGENTS.override.md then ~/.codex/AGENTS.md. First non-empty file wins.
2. Project. Walk from the Git root down to the current working directory. At each level, check AGENTS.override.md, then AGENTS.md, then any name listed under project_doc_fallback_filenames.
3. Merge. Concatenate root-to-cwd. Closer-to-cwd content overrides earlier guidance.
4. Cap. Total content capped at project_doc_max_bytes (32 KiB default). Farthest-from-cwd bytes truncate first.

What v0.137 got wrong is buried in steps 2 and 3. The walk used physical paths from host syscalls directly, so the moment your workspace root crossed a symlink, the walked segments stopped matching the directory tree the user had in mind.

Two real failure modes that showed up over and over in the issues board:

Symlinked workspace root. ~/work/proj is a symlink to /Volumes/ssd/proj. You add AGENTS.md at ~/work/proj/AGENTS.md. The physical resolution lands at /Volumes/ssd/proj/AGENTS.md, but the Git root detector latched onto ~/work and never followed the symlink across. The walk runs over [~/work, ~/work/proj] looking for files that physically live elsewhere.

Remote workspace through the TUI. The sandbox VM’s filesystem is a snapshot mount with a different driver. v0.137 read paths from the host shell environment and tried them inside the VM, where some segments returned ENOENT silently. The walk dropped them and moved on.

v0.138.0 fixes both via two PRs:

• PR #26205 — “Route AGENTS.md loading through environment filesystems.” Introduces an environment filesystem abstraction. The walk now asks the workspace’s own filesystem driver (local, remote VM, NFS) to resolve each segment, instead of calling host-level syscalls directly.
• PR #26465 — “Preserve logical paths during AGENTS.md discovery.” Keeps the user-visible path (e.g., ~/work/proj) intact through the walk, so symlinks transparently route to the physical destination without losing the logical segment that the Git root detector relied on.

In the official changelog the entry is one terse line: “Workspace instruction loading is more accurate for remote and symlinked workspaces, so the right AGENTS.md files are picked up consistently.” The two PRs behind that sentence are the actual fix.

Discovery flow, post-v0.138

flowchart TD
    A[codex starts in cwd] --> B{$CODEX_HOME set?}
    B -- yes --> C[Use $CODEX_HOME as global root]
    B -- no --> D[Use ~/.codex as global root]
    C --> E[Read global AGENTS.override.md, then AGENTS.md]
    D --> E
    E --> F[Detect Git root via env filesystem]
    F --> G[Walk Git root → cwd, level by level]
    G --> H{At each level, find override?}
    H -- yes --> I[Add override.md to merge buffer]
    H -- no --> J{Find AGENTS.md?}
    J -- yes --> K[Add AGENTS.md to merge buffer]
    J -- no --> L[Try project_doc_fallback_filenames]
    I --> M{cwd reached?}
    K --> M
    L --> M
    M -- no --> G
    M -- yes --> N[Concatenate, cap at 32 KiB]
    N --> O[Inject as system instructions]

Discovery order and precedence

All non-empty matches concatenate. Total bytes capped at 32 KiB. Closer-to-cwd content survives truncation.

How to Fix AGENTS.md Not Loading (Solutions for Every Setup)

Solution 1: Local symlinked workspace

The most common case is a Mac with ~/work symlinked to an external SSD, or a Linux workstation with ~/dev symlinked to a faster NVMe partition. After upgrading to v0.138:

npm install -g @openai/codex@latest
codex --version    # expect 0.138.0 or higher
cd ~/work/proj
codex --ask-for-approval never "Summarize the current instructions."

The echoed summary should mention ~/work/proj/AGENTS.md (or whichever physical path resolves to it). If it does not, run three quick checks in order:

1. File is non-empty. wc -c AGENTS.md must return at least 1 byte. Empty files are silently skipped. A recent touch AGENTS.md followed by an editor crash leaves a zero-byte stub more often than you would think.
2. No override is shadowing. find ~/.codex ~/work -name 'AGENTS.override.md' 2>/dev/null. Any non-empty hit higher in the tree wins over your project file.
3. $CODEX_HOME is not redirected. echo $CODEX_HOME should be empty or ~/.codex. If you set it to a project-local profile while experimenting, the global override hunt happens inside that profile instead of ~/.codex.

Solution 2: Remote workspace (Remote TUI / cloud sandbox)

Remote Codex runs the model side inside a sandbox VM and the TUI sends commands over WebSocket. v0.137 forwarded host-resolved paths the VM could not always re-resolve. v0.138’s environment filesystem abstraction resolves paths from inside the workspace process.

codex --remote ws://your-remote-endpoint
# then inside the TUI:
/status

/status reports the active model, approval policy, writable roots, current token usage, and—when the TUI is connected remotely—the remote address and server version. If /status shows the wrong workspace root or the model behaves as if no AGENTS.md is loaded, the issue is your WebSocket session or your workspace mount, not the discovery walk. Quit the TUI and reconnect with codex --remote ws://... to re-establish the session.

Solution 3: Monorepo with nested AGENTS.md

Pre-v0.138 monorepos lost nested files. Issue #13288 captured the canonical setup:

~/monorepo
├── AGENTS.md           # repo-wide rules
├── java/
│   └── AGENTS.md       # Java service rules
├── go/
│   └── AGENTS.md       # Go service rules
└── packages/web/
    └── AGENTS.md       # frontend rules

In v0.137, launching Codex from ~/monorepo and asking it to edit java/UserService.java only loaded the root AGENTS.md. In v0.138 the walk crosses ~/monorepo → java, concatenating both files in that order. Closer-to-cwd guidance wins overlapping rules.

The 32 KiB cap matters in a real monorepo. If your root file is 28 KiB of company-wide conventions, only 4 KiB of java/AGENTS.md survives the merge. Trim the root, or split rules so each leaf carries only what the root cannot say.

A quick way to tell which file Codex actually picked is to put a unique marker at the top of every AGENTS.md—a single line like <!-- agents-marker:java -->—then ask the model to repeat the marker it sees. The closest-to-cwd marker should come back.

The 3 Verification Steps Every Codex User Should Run After v0.138

The upgrade itself is one command. The harder part is convincing yourself that the upgrade actually took effect on your specific workspace—especially if you have lived with the silent skip for weeks and have learned not to trust it. These three steps take under two minutes together and cover the failure modes that account for the bulk of the post-upgrade questions on the Codex issues board.

Verification step 1: have Codex echo back the instruction chain

The official AGENTS.md guide’s primary verification command is one non-interactive prompt. Run it from the deepest directory you actually launch Codex from, and Codex will summarize every AGENTS.md and AGENTS.override.md it pulled in, in precedence order.

cd ~/monorepo/java
codex --ask-for-approval never "Summarize the current instructions. List each AGENTS.md path you loaded and the order they were merged."

Three signals to read off this output. First, the number of files: if you have a nested file you expect to load and the summary does not name it, the walk skipped that level (often because that directory is on a different filesystem than its parent). Second, the rough content: if the leaf rules are missing from the summary, the 32 KiB cap may have truncated them—Codex skips the file before injection in that case. Third, the order: Codex concatenates root-to-cwd, and closer files win overlapping rules. If the order looks backwards, you almost certainly have a stale $CODEX_HOME left over from a previous session.

If you also want a clean read on the workspace root and config state, codex doctor (or codex doctor --json for machine-parsable output) prints the install/auth/runtime/config diagnostics—useful to rule out a misconfigured Codex before blaming the discovery walk.

Verification step 2: round-trip a sentinel marker through the model

The summary in step 1 confirms which files Codex named, but not that every byte survived to the model. The two can diverge if the 32 KiB cap truncated a section, or if a hook in your harness strips the system prompt.

Put a unique sentinel at the top of each AGENTS.md in the merge chain:

<!-- agents-marker:java-leaf -->

Then ask the model in a fresh session: “Repeat every agents-marker:* comment you see in your system instructions verbatim.” If every marker comes back, the merge survived. If only the root marker comes back and the leaf is missing, you are hitting the 32 KiB cap—trim the root before the leaf gets truncated.

The same trick catches the override shadow case. Drop agents-marker:override into any AGENTS.override.md and you will instantly see whether an override file you forgot about is winning over your base file.

Verification step 3: the symlink round-trip test

The third step exists to catch one specific regression that v0.138 fixed but that is easy to reintroduce by accident—running Codex against a path that is itself a symlink, not just sitting inside one.

mkdir -p /tmp/codex-sym-test/real
echo "<!-- agents-marker:symtest -->" > /tmp/codex-sym-test/real/AGENTS.md
ln -s /tmp/codex-sym-test/real /tmp/codex-sym-test/linked
cd /tmp/codex-sym-test/linked
codex --ask-for-approval never "Repeat every agents-marker comment you see in your system instructions verbatim."

If the summary echoes <!-- agents-marker:symtest -->, the environment filesystem abstraction is working in your install. If the marker is missing, either the upgrade did not land (re-check codex --version) or your shell’s realpath resolution is producing a different physical path than the workspace process sees. Move the test directory to your home directory and try again before opening an issue.

These three checks are also the right things to put in a runbook for anyone on the team who hits the same symptom in three months. The verification flow is the same regardless of whether your trigger was a symlinked workspace, a remote sandbox, or a monorepo subtree—the underlying question is always “did Codex see the file the way I expected it to.”

Common AGENTS.md Loading Errors and Fixes

Codex AGENTS.md History: Real Issues in 2026

The path to v0.138 was not one bug fix. It was a string of similar reports, several of which were declined before the workspace abstraction landed. The pattern tells you where the project actually invests.

The split is sharp. Every symlink report against SKILL.md or the .agents/skills tree was closed as not planned. Only AGENTS.md and workspace-root resolution were judged worth the abstraction work. If your workflow leans on symlinking the skills directory itself, v0.138 does nothing for you—convert to real directories, or pick a CLI that treats symlinks as first-class behavior.

When Codex Can’t Load Your Instructions: Best Alternatives That Work Now

For most teams the right answer is just “upgrade to v0.138.” These alternatives are for the edge cases where Codex’s discovery model still does not fit.

Alternatives at a glance

1. Call GPT-5.3-Codex directly via ofox

If your reason for using Codex was the GPT-5.3-Codex model’s coding skill—512K context, agentic tool use, codebase navigation—skip the CLI. The model itself runs through the ofox OpenAI-compatible endpoint. Read AGENTS.md from your own harness and pass it as the system prompt:

from openai import OpenAI
client = OpenAI(base_url="https://api.ofox.ai/v1", api_key="ofox-...")
with open("AGENTS.md") as f:
    house_rules = f.read()
resp = client.chat.completions.create(
    model="openai/gpt-5.3-codex",
    messages=[{"role": "system", "content": house_rules},
              {"role": "user", "content": "Refactor UserService.java to async."}],
)
print(resp.choices[0].message.content)

This bypasses the discovery walk completely. The trade-off is that you re-implement the file read, the multi-level merge, and the override semantics in your harness—but you also stop fighting symlink resolution. Pricing on ofox is $1.49/M input and $11.90/M output after the standard discount, with cache reads at $0.153/M.

2. Pin to real directories, drop the symlinks

If you do not want to change models, the pragmatic patch is cp -r instead of ln -s. Real directories work in every Codex version, including pre-v0.91. Reviewers of issues #9898, #10470, and #11314 made the position explicit: symlinks are not first-class behavior for the skills tree, and they will not be. Treat that as a fact and structure your project around it.

A shared-library workflow that previously symlinked .agents/skills can move to a checked-in subtree or a git submodule. Both resolve to real directories on disk and load on every Codex version.

3. Claude Code or Cursor for symlink-heavy workflows

Claude Code and Cursor both read project rules from physical filesystem paths and follow symlinks by default. If your team’s .agents/skills tree is symlinked across many repos as a shared rules library, neither tool will fight you. Set OPENAI_BASE_URL=https://api.ofox.ai/v1 in either to route through the same backend Codex uses, so the model choice is independent of the CLI choice.

This is a tool swap, not a model swap. You can still call openai/gpt-5.3-codex through either CLI.

4. Stay on v0.137 with a workaround

If you cannot upgrade today—locked CI, vendored binary, frozen Docker image—the workaround is to copy the resolved AGENTS.md into the directory the v0.137 walk actually visits:

cp "$(realpath ~/work/proj/AGENTS.md)" ~/work/proj/AGENTS.md.physical
mv ~/work/proj/AGENTS.md.physical ~/work/proj/AGENTS.md

It is not elegant. It also forces you to re-sync the file by hand whenever the source changes. Upgrade as soon as the freeze ends.

How to Monitor AGENTS.md Loading and Get Alerts

A silent failure mode is still possible on v0.138. Somebody adds an AGENTS.override.md in a parent directory, shadows the file you maintain, and the model’s behavior changes without an error. Two practical guardrails catch this before it costs you a debugging session.

Add a sentinel-marker pre-flight script

You can round-trip a sentinel through the model in one non-interactive shot and fail CI if it does not come back. Add a single line like <!-- agents-marker:repo-root --> to the top of your project AGENTS.md, then:

#!/bin/bash
# scripts/preflight-codex.sh
marker="agents-marker:repo-root"
out="$(codex --ask-for-approval never exec \
  "Repeat every agents-marker comment you see in your system instructions verbatim.")"
echo "$out" | grep -q "$marker" || {
  echo "AGENTS.md not loaded: marker '$marker' missing from response"; exit 1; }

Note the flag order: --ask-for-approval is a global flag and must precede the exec subcommand. codex exec --ask-for-approval never will be rejected as an unknown exec flag.

Wire it into npm run codex or whichever entry point your team uses. CI catches override shadows and truncation before anyone wonders why the model “forgot” the style guide.

Watch override files at the repo level

Add **/AGENTS.override.md to your repo’s .gitignore. git status will flag any new override file that creeps in via a colleague’s experiment, and the gitignore prevents accidental commits. Pair this with a Renovate or Dependabot rule that bumps @openai/codex so your team picks up future discovery fixes without manual upgrades.

Pin the Codex version in package.json

{
  "engines": {
    "codex": ">=0.138.0 <0.140.0"
  }
}

Workspace discovery changes ship without a feature flag, and v0.137 → v0.138 is the most recent example. Pinning a range in engines (or your equivalent tool registry) keeps latest from drifting your team across a behavior change you have not reviewed. Subscribe to the Codex releases feed and bump the upper bound after testing.

Sources Checked for This Refresh

• OpenAI Codex Changelog (June 2026) (verified 2026-06-10)
• Codex AGENTS.md discovery guide (verified 2026-06-10)
• openai/codex Release v0.138.0 (verified 2026-06-10, released 2026-06-08 23:00 UTC)
• GitHub Issues: #8759, #9898, #11314, #13288
• ofox GPT-5.3-Codex model page (verified 2026-06-10, $1.49/M input / $11.90/M output / $0.153/M cache read — ofox discounted; list is $1.75/M input)
• Related ofox blog: codex: command not found fix

The lesson from a year of symlink reports is that Codex treats AGENTS.md as a first-class concept and .agents/skills as undocumented behavior. If your workflow depends on the latter, switch tools instead of waiting for a v0.139 that will not come.