Codex app: support local repo-scoped AGENTS instructions for app-created worktrees

Open 💬 3 comments Opened May 5, 2026 by janbernloehr

Component

Codex app / worktrees / AGENTS.md

Feature Request

Please support repo-scoped local instructions that are private to a developer but automatically available in Codex app-created worktrees.

For example, a repo could have a local-only instructions file such as AGENTS.local.md, or an equivalent app-managed setting, that is loaded alongside AGENTS.md without being committed to git.

Motivation

Some instructions are specific to a repo and a developer’s machine, so they do not belong in committed AGENTS.md, but global Codex instructions are too broad.

Examples:

setting KUBECONFIG before running kubectl
copying or linking .env into new worktrees
local cluster names, VPN notes, private paths, or machine-specific test setup

Today these either have to be committed, repeated manually, placed in global instructions, or handled partially through setup scripts. None of those quite fit repo-specific private instructions.

Expected Behavior

When the Codex app creates a new worktree for a repo, the repo’s local/private instructions should be available automatically in that worktree’s Codex sessions.

View original on GitHub ↗

3 Comments

SpiGAndromeda · 3 months ago

https://developers.openai.com/codex/guides/agents-md
Codex supports AGENTS.override.md

olijboyd · 3 months ago

I don't think SpiGAndromeda's link fully answers it. AGENTS.override.md is for replacing base content, but the OP's examples (KUBECONFIG, local cluster names, VPN notes) read like additions, not overrides. Codex doesn't seem to document an AGENTS.local.md equivalent.

The worktree bit is also a separate question. Even if override works in a normal cwd, the docs don't say whether it propagates into worktrees the Codex app creates, which is really what's being asked here.

Across the AGENTS.md / CLAUDE.md / .cursorrules files we index at tomevault.io, the pattern that's settled is <file>.local.md for gitignored additions and <file>.override.md for shadowing. If you need the same content kept in sync across formats while you wait for Codex to sort this out, we also run a free fan-out converter at tomevault.io/studio (disclosure: I run TomeVault).

olarcher · 3 months ago

This affects CLI/TUI too, not only app-created worktrees; verified that AGENTS.override.md shadows AGENTS.md, so it cannot safely serve as a local additive equivalent to Claude’s CLAUDE.local.md