Feat: Load global instructions from ~/.agents/AGENTS.md

Resolved 💬 4 comments Opened May 26, 2026 by nbiish Closed May 26, 2026

💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

Codex CLI reads AGENTS.md at the workspace level. We should extend this to support loading a global instructions file at ~/.agents/AGENTS.md in the user's home directory. This allows developers to define cross-project standards (like credentials handling, formatting preferences, and OODA-framework guidelines) that apply to Codex sessions regardless of the workspace.

View original on GitHub ↗

4 Comments

etraut-openai contributor · 3 months ago

Codex already supports global (user-level) AGENTS.md files. See this documentation for details.

nbiish · 3 months ago

This setup will allow developers to establish a consistent, low-level global system prompt/ruleset across all agents on their machine, while still supporting project-level AGENTS.md/AGENT.md specifications for workspace-specific context.

nbiish · 3 months ago

To clarify the motivation for standardizing on ~/.agents/AGENTS.md (the global .agents home directory file):

While several CLI tools have their own tool-specific global folders (e.g., ~/.claude/CLAUDE.md, ~/.config/kilo/AGENTS.md, ~/.deepagents/AGENTS.md), standardizing on a single, vendor-neutral ~/.agents/AGENTS.md file is crucial for modern multi-agent workflows.

When developers write custom skills, orchestrators, or MCP tools that trigger multiple CLI agents with different provider/model configurations, it is highly complex to keep multiple rules files synchronized. Using a unified ~/.agents/ directory in the home folder ensures that all agents and sub-agents can fetch their core guidelines (such as security standards, reasoning structures, and data handling rules) from a single source of truth, while still respecting project-level AGENTS.md specifications for workspace-specific context.

quickdraw6906 · 2 months ago

To add on, ~/.agents and other directories should be walked to discover agents. I should be able load ~/.agents/AGENTS.md, and ~/.agents/my-company/AGENTS.md with the later loading either automatically, conditionally, or manually, as dictated in frontmatter.