Codex: project instructions and subagents
Published on
Codex can inspect a repository, edit files, and run local checks. Give it a clear task, the constraints that matter, and a way to verify the result. For a repeated repository workflow, put the shared guidance in AGENTS.md so future tasks start with the same rules. See the Codex CLI guide and AGENTS.md guide in the official OpenAI documentation.
Delegate independent work
Ask Codex directly when you want a subagent to handle a bounded part of a larger task. For example:
Use a subagent to map the routes affected by this change.
Return the route list and any broken links. Keep implementation and
the final review in the main thread.The main thread can use that result to decide what to change and verify. In an interactive CLI session, /subagents shows the agent threads while they run. The Codex subagents guide covers delegation and thread controls.
Create a reusable agent when needed
For a recurring specialized job, Codex supports project agent definitions in .codex/agents/ and personal definitions in ~/.codex/agents/. Each agent is a TOML file with a name, description, and developer_instructions. A focused reviewer definition might begin like this:
name = "reviewer"
description = "Review completed changes for correctness and missing tests."
developer_instructions = "Review the diff for bugs and missing tests. Cite file paths. Do not edit."Custom agent instructions describe a role; they do not replace the parent session’s permissions. Check the custom agents section before changing model or tool settings.
Verify the result
Read the final diff, exercise the changed behavior, and run the repository’s checks. For this site, the repository test plan calls for a production build and route checks through a local server.