Global AGENTS.md relative links resolve against the workspace cwd
What issue are you seeing?
Global AGENTS.md instructions lose their source directory when they are rendered together with project AGENTS.md instructions.
This causes relative Markdown links in the global AGENTS.md file to be interpreted as if they were relative to the current workspace cwd.
Example:
# <codex-home>/AGENTS.md
Before acting, read [shared rules](./shared-rules.md).
If Codex is started from <workspace>, it may try to read <workspace>/shared-rules.md instead of <codex-home>/shared-rules.md, or report the linked file as missing from the workspace.
What steps can reproduce the bug?
- Create a global Codex instructions file:
``text``
<codex-home>/AGENTS.md
with contents like:
``md``
Before acting, read [shared rules](./shared-rules.md).
- Create the referenced file next to it:
``text``
<codex-home>/shared-rules.md
- Start Codex from an unrelated workspace directory that does not contain
shared-rules.md.
- Ask Codex to follow the global instructions or inspect the linked file.
Observed behavior: the linked file is looked up relative to the workspace cwd, not relative to the global AGENTS.md file.
What is the expected behavior?
Relative links or file references in an AGENTS.md file should be resolved relative to the directory containing that AGENTS.md file.
At minimum, the model-visible instruction block should preserve the source path or source directory for the global AGENTS.md, so relative references in that file are not presented as workspace-relative.
Additional information
Observed with codex-cli 0.141.0 on macOS.
This appears related to #23416, but this issue focuses on the concrete failure mode caused by the lost provenance: relative references from global AGENTS.md resolve against the wrong directory.
From a source inspection, CodexHomeUserInstructionsProvider records the global instruction source path, but LoadedAgentsMd::legacy_text() and LoadedAgentsMd::environment_labeled_text() flatten the global instruction text without rendering that source. In the single-project case, LoadedAgentsMd::render() labels the combined block with the project cwd, which makes global relative references appear project-relative.
2 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
Thanks. I reviewed #28739. This issue is related, but I do not think it is a strict duplicate.
#28739 proposes a broader feature set: AGENTS.local overlays, @-reference expansion, and source-labeled instruction fragments.
This issue is narrower: the current rendering of global AGENTS.md loses its source directory, so ordinary relative Markdown references inside the global AGENTS.md are presented as
if they were workspace-relative.
A minimal fix for this bug does not require @include support or AGENTS.local. It only needs the model-visible instruction block to preserve the source path/source directory for
global AGENTS.md, or otherwise avoid wrapping global instructions under the project cwd.
This is also related to #23416, but focuses on a concrete failure mode caused by the lost provenance.