Allow pointing codex to specific AGENTS.md / prevent reading AGENTS.md file from folder above where codex-cli started

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #5983

Powered by Codex Action

Hey @bornio, looks like this issue closely resembles my feature request! Just wanted to share with you a "workaround" which achieves roughly the results you're looking for:

1. Add AGENTS.override.md to your project's .gitignore
2. Create a shell source file at the root of the project with the following contents:

# Usage: source shell.sh activate|deactivate

# codex --disable-git-root-agents
function codex() {
  if [[ "$1" != "--disable-git-root-agents" ]]; then
    # launch codex normally and exit immediately
    codex "$@"
    exit 0
  fi
  # remove special arg so we have regular codex launch command
  shift
  # how many times we've pushed up
  depth=0
  # find repo root
  while true; do
    # If there's a .git directory or worktree file here, we're at the repo root
    if [[ -d ".git" || -f ".git" ]]; then
      # capture root folder
      workspace_dir="$PWD"
      # Optionally handle if AGENTS.override.md is a non-empty file
      if [[ -s "AGENTS.override.md" ]]; then
        original_override="$(cat AGENTS.override.md)"
        override_path="$PWD/AGENTS.override.md"
        # set trap on exit, restoring original non-empty override
        trap "echo \"${original_override}\" > ${override_path}" EXIT
      fi
      # Add empty override
      echo "" > AGENTS.override.md

      # Unwind directory stack until we're back to the original directory
      while (( depth > 0 )); do
        popd > /dev/null
        (( depth-- ))
      done
      # Launch codex with all args passed in (after stripping special arg)
      codex "$@"
      # Clean-up override
      rm "$workspace_dir/AGENTS.override.md"
      break
    fi

    # If we're at root and still didn't find .git, bail out
    if [[ "$PWD" == "/" ]]; then
      echo "Not inside a Git repository (reached / without finding .git)" >&2
      # unwind any pushes that might have happened
      while (( depth > 0 )); do
        popd > /dev/null
        (( depth-- ))
      done
      exit 1
    fi

    # Go up one level and count it
    pushd .. > /dev/null
    (( depth++ ))
  done
}
case "$1" in
  deactivate) # Explicitly deactivate override
    unset -f codex
    echo "🚫 Deactivated: removed codex override"
    ;;
  activate) # Explicitly activate override by not unsetting that function above
    echo "✅ Activated: codex root AGENTS override active"
    ;;
  *) # In all other cases, deactivate override just to be safe & print usage
    unset -f codex
    echo "⁉️ Unknown command: removed codex override."
    echo "usage: source shell.sh {activate|deactivate}"
    ;;
esac

1. At the root of the git repo, use source shell.sh activate.
2. Navigate to any subdirectory and launch codex --disable-git-root-agents [OPTIONAL_ARGS]

The pros:

• You disable the root git AGENTS file so context is scoped in the subfolder
• You can still launch codex like normal!

~~The cons (and the reason I created my issue in the first place):

• If you run multiple codex instances inside the project at the same time, perhaps you want one in a subfolder with an empty override and one at the repo root without the override, you'll have to pay attention to the override file before sending the first message (AGENTS(.override)?.md is read after you send your first prompt, not when you launch codex!)
• During compaction (auto or manual), it re-reads the AGENTS files.

Anyways, there's a workaround! I use similar mechanics in my workflow, taking advantage of that override for various reasons. Another option is to ln -s ../../../.git .git which drops a symbolic link to the real git root into the working folder (you'd also add .git to .gitignore so it doesn't end up committed by accident). Codex-CLI's logic for detecting the repo root is simply "does a file or directory named .git exist here?" so you can fool it into thinking the repo root is the subfolder. All of these options are somewhat brittle and convoluted. Hope that helps while we wait for feedback on our ideas!~~

Update: The way AGENTS.md is loaded has changed a lot since that recommendation. Now at the start of every turn it loads the AGENTS.md if it changed, so this workaround is outdated.

This feature request hasn't received enough upvotes, so I'm closing it.