›_ Codex Issues
Codex Issues / #16403

Refresh project instructions when AGENTS.md scope changes across turns

Resolved 💬 4 comments Opened Apr 1, 2026 by ansh-info Closed Apr 2, 2026
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

CLI

What feature would you like to see?

Codex should refresh the model-visible project instructions when the effective AGENTS.md set changes between turns, especially when the turn cwd moves to a different project subtree.

Today, project docs are discovered from the current cwd and merged into user instructions, but that instruction block is not re-emitted when the applicable AGENTS.md content changes across turns. This means a session can continue using stale project guidance after a cwd change, even though the new directory has different instructions.

This would improve:

  • multi-directory and monorepo workflows
  • reliability of scoped per-directory instructions
  • trust in AGENTS.md as the source of truth for local guidance
  • predictability when users intentionally change cwd between turns

Proposed behavior:

  • Recompute the effective project-doc payload for each turn using the submitted cwd
  • If the resulting instruction content differs from the last emitted project-doc payload for the thread, emit the updated instructions into the next model-visible request
  • Re-emit only when the effective content actually changes

Acceptance criteria:

  • Changing cwd to a directory with different effective AGENTS.md content refreshes the next turn’s project instructions
  • No duplicate re-emission when the effective content is unchanged
  • Existing single-directory behavior remains unchanged
  • Test coverage includes cwd-based instruction refresh

Additional information

There is already a TODO and regression snapshot in the codebase pointing at the current behavior:

  • codex-rs/core/tests/suite/model_visible_layout.rs
  • snapshot_model_visible_layout_cwd_change_does_not_refresh_agents

The test comment explicitly notes that Codex should diff user_instructions and emit updates when AGENTS.md content changes.

Implementation direction:

  • Recompute project docs from the turn cwd using the existing discovery path
  • Keep the last emitted project-doc payload in thread or session state
  • Diff old vs new payload before building the next request
  • Update the existing snapshot test to assert refreshed instructions

View original on GitHub ↗

4 Comments

ansh-info · 4 months ago

I implemented a candidate fix for this in my fork:

  • branch: feat/agents-md-refresh-16403
  • commit: b7d1314b2 (Refresh AGENTS instructions on cwd changes)

What it changes:

  • recomputes effective AGENTS.md / project-doc instructions from the per-turn cwd
  • routes user_instructions through the existing context-diff path
  • emits refreshed AGENTS context only when the effective payload changes
  • avoids restating AGENTS instructions when the cwd and effective payload are unchanged

Validation:

  • cargo test -p codex-core snapshot_model_visible_layout_cwd_change_refreshes_agents -- --nocapture
  • cargo test -p codex-core model_visible_layout_same_cwd_does_not_restate_agents -- --nocapture

Both targeted checks compiled and completed successfully in my environment. The test bodies were skipped by the suite's sandbox/network guard, but the code and updated test targets compiled cleanly.

I also added coverage for:

  • cwd change refreshing AGENTS instructions
  • same-cwd turns not restating AGENTS instructions

I can’t open a PR because this repository restricts PR creation to collaborators, but I’m happy to share the patch/branch details here if helpful.

ansh-info · 4 months ago

@charley-oai I implemented a candidate fix for this in my fork and shared the branch, commit, and verification details above. Since PRs are restricted to collaborators here, I wanted to flag it directly in case it is useful to cherry-pick or adapt.

@aibrahim-oai tagging you as well since this touches the existing context-diff path for model-visible updates.

Fork branch:

Commit:

ansh-info · 4 months ago

Follow-up verification update: I was able to run the two targeted tests outside the Codex sandbox-skipping environment, and both passed at runtime.

Passed:

  • cargo test -p codex-core snapshot_model_visible_layout_cwd_change_refreshes_agents -- --nocapture
  • cargo test -p codex-core model_visible_layout_same_cwd_does_not_restate_agents -- --nocapture

Updated commit:

etraut-openai contributor · 4 months ago

AGENTS.md instructions are sent at the beginning of a thread. Overriding previous instructions will generally confuse the model. If you decide to modify AGENTS.md, you should create a new thread.

If you change the cwd, you should definitely create a new thread.