/status shows Agents.md: <none> even when AGENTS.md exists and appears to be loaded

[yuebozhang]

Summary

/status shows Agents.md: <none> even when AGENTS.md exists and appears to be loaded.

Environment

• Codex CLI v0.120.0
• macOS Darwin 25.4.0 arm64
• Model: gpt-5.4
• Collaboration mode: Default

Description

In my session, /status consistently showed:

Agents.md: <none>

However:

• The current working directory was a project root containing a root-level AGENTS.md
• I also added another AGENTS.md at the workspace root to rule out a workspace-root mismatch
• The assistant still appeared to read and follow the project AGENTS.md

This makes it look like the issue is in the status display logic, or in a mismatch between status path resolution and actual AGENTS loading behavior.

Steps to Reproduce

1. Open Codex CLI in a project directory that contains a root-level AGENTS.md
2. Confirm the file exists and is readable
3. Run /status
4. Observe that Agents.md is shown as <none>

Observed Behavior

• /status shows Agents.md: <none>
• AGENTS.md exists at the active project root
• Another AGENTS.md also exists at the workspace root
• The assistant still appears to follow the project instructions

Expected Behavior

• If AGENTS.md is found and loaded for the active project or workspace, /status should show that file instead of <none>
• If /status is intentionally checking a different directory than the session cwd, it should clearly indicate which directory it checked

Why This Is Confusing

It is hard to tell whether:

• AGENTS.md was not discovered
• AGENTS.md was discovered but not displayed
• the status panel is stale
• the status panel is using different path resolution logic than the actual instruction loader

Privacy / Redaction

This report is redacted and does not include:

• private note contents
• tokens or credentials
• identifiable local paths
• repository names unrelated to reproducing the bug

[yuebozhang]

use iCloud syne, /Library/Mobile Documents/iCloudmd~obsidian/Documents/y_vault

[yuebozhang]

/Users/y/Library/Mobile\ Documents/iCloud~md~obsidian/Documents/y_vault/AGENTS.md

[ImHangLi]

I traced both code paths and believe the status display is consistent with the actual instruction loading — they share the same discovery function.

Analysis

Status display (tui/src/status/helpers.rs:39):

discover_agents_summary() → discover_project_doc_paths() + config.user_instructions_path

Instruction loading (core/src/project_doc.rs:89):

get_user_instructions_with_fs() → read_project_docs_with_fs() → discover_project_doc_paths() + config.user_instructions

Both paths call discover_project_doc_paths() (core/src/project_doc.rs:216) for project-level AGENTS.md discovery. There is no scenario where one succeeds and the other fails — the display logic and the loading logic use the same function with the same config.

Likely explanation

The observation that "the assistant still appeared to follow the project AGENTS.md" is probably not caused by the file actually being loaded. Without concrete evidence (e.g., the model quoting specific content from your AGENTS.md, or exhibiting behavior that only your instructions would produce), the model's default behavior can easily appear to align with generic instructions.

Given your iCloud-synced workspace (~/Library/Mobile Documents/iCloud~md~obsidian/...), one possibility is that the file exists as a cloud-only placeholder and hasn't been materialized locally, causing fs.get_metadata() to not find it. Another is that no project root marker (.git, etc.) was found, though that would still search the cwd and should locate the file if it's present on disk.

Suggestion

Could you confirm:

1. Does your Obsidian vault directory contain a .git folder or other project root marker?
2. Can you share specific content from your AGENTS.md and show the model acting on it in a way that wouldn't happen by default?
3. Is the AGENTS.md file fully downloaded locally (not an iCloud placeholder)?

This would help distinguish between "AGENTS.md isn't being found" (expected <none>) vs. a genuine display/loading discrepancy.

[yuebozhang]

I checked the local state on my side and can add a bit more evidence.

• The vault root is a real git repo:
  /Users/y/Library/Mobile Documents/iCloud~md~obsidian/Documents/y_vault/.git
• AGENTS.md exists locally and is readable:
  AGENTS.md | size=2089 | mode=-rw-r--r--
• ls -l@ AGENTS.md shows:
  • com.apple.decmpfs
  • com.apple.lastuseddate#PS
  • com.apple.provenance
• I do not see an obvious cloud-only placeholder indicator for this file.
• Finder also shows AGENTS.md as a normal local markdown file in the vault root, alongside the top-level folders.

More importantly, I have a behavioral example that seems hard to explain as “default behavior happened to align”:

My AGENTS.md contains explicit deletion-safety rules, including:

• move deletions to system trash first
• list the deletion candidates before deleting
• do not directly clear top-level directories like 00_MOC
• stop for confirmation in high-risk deletion scenarios

When I asked the agent to delete the entire 00_MOC directory, it did not delete it directly. It first recognized
that this was a top-level directory deletion, listed the exact files that would be removed, and waited for
confirmation before proceeding. I’ve attached a screenshot of that interaction.

So from my side:

1. the file appears to exist locally and be readable
2. the vault has a .git root marker
3. I have at least one concrete behavior that looks specifically driven by the contents of AGENTS.md, not just
   generic assistant behavior

That makes me think there may still be some gap between the current explanation and what is actually happening in my
setup, or there is another code path / cached context / instruction source involved that hasn’t been ruled out yet.

already use agents:

file is local:

show agents none:

[ImHangLi]

Thanks for the thorough follow-up — the evidence is convincing, and the iCloud placeholder theory doesn't hold up. I dug deeper into the code and have two working theories.

Theory A: Silent error on the iCloud path

The /status display spawns an async task that calls discover_project_doc_paths. If that function returns any Err (not just "file not found"), it silently falls back to <none> — the error only goes to the tracing log (chatwidget.rs:7107-7109). On an iCloud-backed filesystem, it's plausible that dunce::canonicalize or tokio::fs::metadata hits a transient I/O error that gets swallowed here.

The problem is that the instruction-loading path (get_user_instructions in codex.rs:550) calls the same discovery function, so if it errors there too, the model shouldn't get the instructions either — unless they come from a different source (see Theory B).

Theory B: Instructions loaded from the global home, not the project

Codex loads instructions from two independent sources:

1. Global: ~/.codex/AGENTS.md (or AGENTS.override.md) — loaded once at config init into config.user_instructions
2. Project-level: discovered via discover_project_doc_paths by walking from cwd to the project root

If you happen to have an AGENTS.md in ~/.codex/ with similar content, the model would follow those instructions while /status could still show <none> for project-level docs.

Debugging steps

Could you check:

1. Does ~/.codex/AGENTS.md or ~/.codex/AGENTS.override.md exist on your machine?
2. What does realpath return for your vault path? (realpath ~/Library/Mobile\ Documents/iCloud\~md\~obsidian/Documents/y_vault)
3. If you run codex with RUST_LOG=codex_core=debug, do you see any warnings like "failed to discover project docs" in the log output?
4. Does the cwd shown in /status match your vault root?

This should narrow down whether it's an error-swallowing issue on the iCloud path or a source mismatch.