agentleFS
youcislayoucisla/Agent-Foundry/.codex/AGENTS.md

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

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
  1. Distinctive:

    Treat networked tools as read-only by default.

    line 52
  2. Distinctive:

    When approval is ambiguous, produce a local plan or draft artifact instead of taking the external action.

    line 57
  3. Distinctive:

    Always validate inputs at system boundaries.

    line 94
  4. Common:

    Never hardcode secrets — use environment variables.

    line 95
  5. Very specific:

    Run pip audit before committing (the project ships a Python daemon).

    line 96
  6. Very specific:

    Use sandbox_mode = "workspace-write" in .codex/config.toml.

    line 98

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 TypeRecommended Model
Routine coding, tests, formattinggpt-5-mini
Complex features, architecturegpt-5
Debugging, refactoringgpt-5
Security reviewgpt-5
Skill body generationgpt-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 workflow
  • agents/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 = 10

This 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 plan
  • af-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

FeatureClaude CodeCodex CLI
Hooks8+ event typesNot yet supported
Context fileCLAUDE.md + AGENTS.mdAGENTS.md only
SkillsDirect children of ~/.claude/skills/Direct children of ~/.agents/skills/
Commands/slash commandsInstruction-based
AgentsSubagent Task toolMulti-agent via /agent and [agents.] roles
SecurityHook-based enforcementInstruction + sandbox
MCPFull supportSupported via config.toml and codex mcp add

Security Without Hooks

Since Codex lacks hooks, security enforcement is instruction-based:

  1. Always validate inputs at system boundaries.
  2. Never hardcode secrets — use environment variables.
  3. Run pip audit before committing (the project ships a Python daemon).
  4. Review git diff before every push.
  5. 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-start

The 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-cli 0.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)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.