Proposal: standardize .agents workspace alongside .codex

[AmirTlinov]

Summary

Codex today keeps durable agent assets in ~/.codex, while project-specific guidance lives in scattered AGENTS.md files and user scripts. We want to add a sibling ~/.agents workspace — with an optional project-level .agents/ overlay — so that context notes, reusable tools, and MCP definitions have a consistent home.

Why it matters

• Predictable structure: Teams can drop durable memory (context/), helper scripts (tools/), or MCP manifests (mcp/) into ~/.agents and expect every Codex session to see them.
• Per-project overrides: When a repository contains its own .agents/, its content augments or overrides the global workspace. This lets each codebase carry tailored policies without affecting others.
• Lower setup friction: Provisioning new machines—or sharing platform-wide tooling—becomes a matter of syncing the .agents tree instead of juggling multiple ad-hoc folders.
• Shared ecosystem: Today, different agent CLIs often ship with their own hidden folders (~/.codex, ~/.claude, ~/.gemini, …). Standardizing on ~/.agents gives humans and agents a common, reusable hierarchy for memory, tooling, and configuration.
• Reusable context: High-value guidance stored in ~/.agents/context/ can be refined once and reused across projects or agents, rather than re-instructing each run from scratch.

What we’re proposing

1. Ship Codex CLI with an auto-initialized ~/.agents/{context,tools,mcp}. Users can override the path via the agents_home config key or the AGENTS_HOME environment variable.
2. At startup, if the working repository contains .agents/, merge it on top of the global workspace (project entries win, global entries remain as fallbacks).
3. Merge MCP configs from agents_home/mcp with the existing mcp_servers section in config.toml, so commands like codex mcp list surface both global and local servers.
4. Render an aggregated <agents_context> block (listing context documents and tool paths) at the beginning of every session/turn so models can immediately act on those assets. Global entries use their true absolute paths and honor per-file/per-block truncation limits.
5. Keep behavior opt-in for projects: we never create .agents/ in a repo automatically—users or tooling do that when they want project-local customization.
6. Document the layered layout and cover it with unit/integration tests so the behavior stays stable.

Expected outcome

• Global .agents becomes the canonical place for long-lived agent memory and tooling.
• Projects that ship with their own .agents gain layered context/MCP support without bespoke scripting.
• Multiple agent CLIs can converge on the same directory layout, simplifying coexistence on shared machines.
• Each Codex session receives a clearly delimited <agents_context> message that references the real paths to context files and helper tools.
• The new convention remains backwards compatible; existing ~/.codex workflows keep working unchanged.

We’ve prototyped this in PR #5877 (integration/unit coverage + docs included) and would appreciate guidance on whether the approach aligns with Codex’s roadmap, as well as any concerns about rolling it out.

[github-actions]

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

• seems like codex will read AGENTS.md in ~/.codex/AGENTS.md #4354
• Move today’s machine-local global agents rules (e.g., %USERPROFILE%\.codex\AGENTS.md) to an official cloud Policy Center with multi-device sync, versioning/rollback, org/team/user scoping with clear precedence, secure secret handling, and offline cache. #4765
• Add Memory bank feature similar to cline memory bank #4655
• Feature Request: Want OpenAI to dev user memory feature for Codex #4933

Powered by Codex Action

[AmirTlinov]

Follow-up: opened PR #5895 (stacked on #5877) to add the <agents_context> prompt and associated tests/docs once the base .agents support lands.