Description

Adel Rodríguez (adelrodriguez)

opened on Nov 5, 2026

Issue body actions

Describe the bug

apm compile --global writes Codex instructions to ~/.codex/AGENTS.md even when CODEX_HOME points elsewhere. The command succeeds, but Codex keeps reading the old instructions in $CODEX_HOME/AGENTS.md.

The Codex MCP adapter already honors CODEX_HOME. This leaves MCP configuration and compiled instructions in different directories during the same global deployment.

To Reproduce

This reproduction uses an isolated home and requires no downloads or installed dependencies:

test_home="$(mktemp -d)"
mkdir -p "$test_home/.apm/apm_modules/example/instructions/.apm/instructions"
cat > "$test_home/.apm/apm.yml" <<'YAML'
name: codex-home-repro
version: 0.1.0
targets: [codex]
YAML
cat > "$test_home/.apm/apm_modules/example/instructions/.apm/instructions/global.instructions.md" <<'MD'
---
description: Global test instruction
---

Use concise responses.
MD
(cd "$test_home/.apm" && HOME="$test_home" CODEX_HOME="$test_home/.config/codex" apm compile --global)
test -f "$test_home/.codex/AGENTS.md" && echo 'Default path exists'
test -f "$test_home/.config/codex/AGENTS.md" || echo 'CODEX_HOME output is missing'
rm -rf "$test_home"

Expected behavior

Global compilation writes $CODEX_HOME/AGENTS.md when CODEX_HOME is set, and defaults to ~/.codex/AGENTS.md when unset. Project compilation should keep its project-relative destination.

Official instruction discovery behavior: https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance

Environment

• macOS 27.0
• Python 3.15.2, from the Homebrew APM installation
• APM 0.35.0, also the current release when checked

Logs

The isolated reproduction exited with code 0:

[+] codex: wrote ~/.codex/AGENTS.md
[+] Compiled 1 user-scope root context file(s).
Default path exists
CODEX_HOME output is missing

Additional context

Confirmed against the installed 0.35.0 source:

• The Codex target uses .codex as its root.
• The global compiler resolves the target root and appends the context filename.
• The MCP adapter honors CODEX_HOME.

Related closed issue #1861 concerned the MCP installation path. This report concerns global instruction compilation, which remains affected. A source check of current main also found the static .codex target root. The runtime reproduction above used the released 0.35.0.

Local workaround: back up the existing custom-home instruction file, then symlink $CODEX_HOME/AGENTS.md to ~/.codex/AGENTS.md. Remove this workaround once global compilation honors CODEX_HOME.

🤖 Created with gpt-6.1-sol in T3 Code

Activity

1. github-project-automation

   added this to APM Roadmapon Nov 5, 2026
2. danielmeppiel commented on Nov 10, 2026

   

   Daniel Meppiel (danielmeppiel)

   on Nov 10, 2026

   Collaborator

   More actions

   Decision: approve
   Area: project
   Scope: Make apm compile --global write Codex user-scope instructions to $CODEX_HOME/AGENTS.md when CODEX_HOME is set to a non-blank value (default ~/.codex/AGENTS.md), matching the documented CODEX_HOME contract and the Codex MCP adapter's existing resolution, without changing project-scope compile destinations.
   Done when: Tests (tests/unit/compilation/test_user_root_context.py and target-profile tests) show set, unset, blank and relative CODEX_HOME behave like the Codex MCP adapter (relative fails clearly, nothing is written under ~/.codex when CODEX_HOME is set); project compile output is unchanged; every other Codex user-scope write that shares the changed target root is shown to resolve consistently with docs/src/content/docs/reference/environment-variables.md; compile and environment-variable docs state the behavior; tests fail on current main.
   Out of scope: Moving or deleting files already written under ~/.codex, other harness home variables (CLAUDE_CONFIG_DIR, COPILOT_HOME), Codex skills under ~/.agents, Codex native plugin registration paths, and #1861.
   Review contact: Daniel Meppiel (@danielmeppiel)
3. danielmeppiel commented on Nov 10, 2026

   

   Daniel Meppiel (danielmeppiel)

   on Nov 10, 2026

   Collaborator

   More actions

   The apm-scope:v1 record above was approved by Daniel Meppiel (@danielmeppiel) at Gate B on 2026-11-10 in the coordinator session of the issue-reduction program. It is the scope a fix for this issue will be reviewed against.

   Review contact: Daniel Meppiel (@danielmeppiel).

   Linked pull requests:

   • PR fix(compile): honour CODEX_HOME for global Codex instructions #3491 by JohnnyXu (@xubenqiang): appears to address this scope.

   ---

   Generated by autopilot-issue-triage-worker. This comment is AI-generated and may contain errors.
4. Daniel Meppiel (danielmeppiel)

   added

   status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.Human scope approval; verify the issue's approval record and review contact before work.

   on Nov 10, 2026
5. Daniel Meppiel (danielmeppiel)

   added 3 commits that reference this issue on Nov 10, 2026

   fix(targets): honor CODEX_HOME through the for_scope home override

   1172ff3

   docs: document CODEX_HOME for global compile and user-scope writes

   5e505b1

   docs(changelog): note CODEX_HOME for Codex user-scope writes

   4edd9d4

Issue actions