Agent-Foundry
AGENTS.md1 starsChanged 23 days agoMITView on GitHub
This supplements the root AGENTS.md with Codex-specific guidance. After bash scripts/install.sh --harness=codex, this file lives at ~/.codex/AGENTS.md (per-project) or inside this repo's .codex/ for shipped defaults. Codex scans .agents/skills/ from the working directory up to the repository root, plus $HOME/.agents/skills/. The installer links each of the 41 skills as a direct child of $HOME/.agents/skills/. ~/.codex/skills/ is a legacy location and is not used by the installer. Each skill contains: Skills must be direct children of the skills root; Codex does…
- Pipes a download into a shell
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository46 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .gemini/AGENTS.mdAGENTS.md
- .cursor/rules/agent-foundry-orchestrator.mdcCursor rule
- .cursor/rules/agent-foundry-skills.mdcCursor rule
- web/llms.txtllms.txt
- anti-slopSkill
- api-designSkill
- automation-pickSkill
- bottleneck-gatingSkill
- budget-guardSkill
- cache-identitySkill
- constraint-then-solveSkill
- context-optimizationSkill
- cron-troubleshootSkill
- e2e-test-strategySkill
- engram-routingSkill
- execution-observabilitySkill
- fallback-model-routingSkill
- feedback-loopSkill
- judge-integritySkill
- knowledge-extractSkill
- landscape-firstSkill
- measure-firstSkill
- plan-before-codeSkill
- plan-then-actSkill
- prompt-disciplineSkill
- pushback-when-wrongSkill
- quality-protocolSkill
- read-before-buildSkill
- re-verify-findingsSkill
- session-closeoutSkill
- session-distillSkill
- show-your-workSkill
- structured-output-contractSkill
- verify-firstSkill
- workflow-decomposeSkill
- agent-memory-vaultSkill
- agent-team-standardsSkill
- autonomous-briefingSkill
- book-to-skillSkill
- chrome-devtools-mcp-bridgeSkill
- design-languageSkill
- funnel-pr-guardSkill
- persistent-memorySkill
- sql-migration-trioSkill
- token-compressionSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 1 is common, 3 are distinctive, and 2 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 52
Treat networked tools as read-only by default.
- Distinctive: line 57
When approval is ambiguous, produce a local plan or draft artifact instead of taking the external action.
- Distinctive: line 94
Always validate inputs at system boundaries.
- Common: line 95
Never hardcode secrets — use environment variables.
- Very specific: line 96
Run pip audit before committing (the project ships a Python daemon).
- Very specific: line 98
Use sandbox_mode = "workspace-write" in .codex/config.toml.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Foundry — Codex CLI Guide
This supplements the root AGENTS.md with Codex-specific guidance. After
bash scripts/install.sh --harness=codex, this file lives at
~/.codex/AGENTS.md (per-project) or inside this repo's .codex/ for
shipped defaults.
Model Recommendations
| Task Type | Recommended Model |
| Routine coding, tests, formatting | gpt-5-mini |
| Complex features, architecture | gpt-5 |
| Debugging, refactoring | gpt-5 |
| Security review | gpt-5 |
| Skill body generation | gpt-5-mini (cost-efficient) |
Skills Discovery
Codex scans .agents/skills/ from the working directory up to the repository
root, plus $HOME/.agents/skills/. The installer links each of the 41 skills
as a direct child of $HOME/.agents/skills/.
~/.codex/skills/ is a legacy location and is not used by the installer.
Each skill contains:
SKILL.md— Detailed instructions and workflowagents/openai.yaml— optional Codex interface metadata
Skills must be direct children of the skills root; Codex does not recurse into a shared parent folder.
MCP Servers
Agent Foundry does not require MCP servers. agent-foundry mcp is the
stdio MCP server; agent-foundry serve is the HTTP daemon. Recommended MCP
baseline:
[mcp_servers.agent-foundry]
command = "agent-foundry"
args = ["mcp"]
startup_timeout_sec = 10This lets Codex route LLM calls through the Foundry's plan → execute → log pipeline. Without it, Codex runs skills in isolation (no budget guard, no judge, no execution log).
External Action Boundaries
Treat networked tools as read-only by default. Search, inspect, and draft freely within the user's requested scope, but require explicit user approval before posting, publishing, pushing, merging, opening paid jobs, dispatching remote agents, changing third-party resources, or modifying credentials.
When approval is ambiguous, produce a local plan or draft artifact instead of taking the external action. Preserve user config and private state unless the user specifically asks for a scoped change.
Multi-Agent Support
Codex supports multi-agent workflows behind features.multi_agent. Agent
Foundry ships two native roles:
af-planner— decomposes a request into a skill/agent planaf-critic— judges a completed output on correctness/slop/scope
To dispatch via Codex CLI, point the role at the agent's directory:
[agents]
[agents.af-planner]
description = "Decomposes a request into a skill/agent plan."
config_file = "agents/af-planner/agents/openai.yaml"Key Differences from Claude Code
| Feature | Claude Code | Codex CLI |
| Hooks | 8+ event types | Not yet supported |
| Context file | CLAUDE.md + AGENTS.md | AGENTS.md only |
| Skills | Direct children of ~/.claude/skills/ | Direct children of ~/.agents/skills/ |
| Commands | /slash commands | Instruction-based |
| Agents | Subagent Task tool | Multi-agent via /agent and [agents.] roles |
| Security | Hook-based enforcement | Instruction + sandbox |
| MCP | Full support | Supported via config.toml and codex mcp add |
Security Without Hooks
Since Codex lacks hooks, security enforcement is instruction-based:
- Always validate inputs at system boundaries.
- Never hardcode secrets — use environment variables.
- Run
pip auditbefore committing (the project ships a Python daemon). - Review
git diffbefore every push. - Use
sandbox_mode = "workspace-write"in.codex/config.toml.
Daemon Lifecycle
Agent Foundry uses a lazy-started daemon. If you want Codex to invoke the orchestrator, start the daemon explicitly first:
agent-foundry serve --port 8765 & # or rely on lazy-startThe daemon serves on http://127.0.0.1:8765 with endpoints:
/health— GET, returns daemon status/index— POST, rebuilds the skill index/plan— POST, returns ranked skills for a prompt/execute— POST, runs a specific skill/loop— POST, full plan → execute → return/loop/resume— POST, continue a stored loop session/loop/{id}— GET, inspect a loop session
Compatibility Notes
Tested on:
codex-cli0.144.6, npm install (npm i -g @openai/codex)- Windows 10, Node 22+, Python 3.10-3.14
Not tested on:
- Mac/Linux standalone installer (
curl -fsSL https://chatgpt.com/codex/install.sh | sh) - Codex cloud / Codex IDE extension
- Codex app (desktop)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

