Codex CLI Tool for Team Workflows

Use OpenAI’s Codex CLI only after the repo has written operating rules, not as a free-form terminal assistant. For an engineering team, the useful workflow is simple: give the Codex agent scoped instructions in AGENTS.md, connect external systems through MCP only where needed, and make every change end in a verification step a human can review.

In Codex CLI training and Codex workshop rooms, I start with the workflow before commands. The Codex CLI tool can speed up issue-to-PR work, but only if it inherits the same constraints a teammate would follow: package manager, test command, forbidden areas, security boundary, and definition of done. For more patterns in this lane, keep a running set of CLI workflows rather than a pile of one-off prompts.

Put repo rules where Codex will read them

Use AGENTS.md for durable repository instructions, not for today’s task prompt. The file should tell Codex how the repo works when nobody is watching: install command, test command, architecture boundaries, naming rules, and what not to touch.

A root AGENTS.md is enough for a small repo. In a monorepo, nested AGENTS.md files are usually cleaner because a frontend package and a worker package rarely share every rule.

Keep the file short. If a rule would annoy a human reviewer because it is vague, it will also produce weak agent work.

Use this Codex CLI loop for a repo change

A good Codex workflow is not “ask, accept, merge.” It is a small loop with visible checkpoints.

1. Start from one issue, bug, or refactor, not a bundle of unrelated work.
2. Ask Codex to inspect the relevant files and propose a plan before editing.
3. Approve one narrow slice of work.
4. Run the repo’s verification command in the same loop.
5. Ask Codex to summarize changed files, test output, and remaining risk.
6. Review the diff yourself before commit or PR.

For example, in a pnpm monorepo fix for a GitHub issue, I would scope Codex to packages/web, tell it not to change shared API types unless the failing test requires it, and require pnpm --filter web test before the work is done. That gives the team a reviewable unit instead of a broad agent pass across the repo.

This sits in the Review part of our methodology: delegate the narrow change, review the evidence, then own the decision. Codex can produce the patch, but the team still owns the merge.

Add MCP after the local loop works

MCP is useful when Codex needs context from systems outside the repo, such as issues, docs, or design notes. Add it after the local Codex CLI loop is boring and repeatable.

Start with read-only access. A read-only GitHub or docs connection is enough for many tasks because Codex can inspect the issue, search context, and still leave writes to the developer.

Do not connect everything because it is available. Each MCP server should have a reason, an access level, and a failure mode the team understands. If you are designing that boundary now, the related note on Add MCP to Codex CLI Workflows goes deeper on Codex MCP setup decisions.

Paste this AGENTS.md starter

Use this as a starting point, then replace the commands and boundaries with your repo’s real rules.

# AGENTS.md

## Repository rules
- Use pnpm for installs and scripts.
- Do not create npm or yarn lockfiles.
- Keep changes scoped to the issue unless the plan calls out a necessary dependency.
- Do not change public API types without explaining why in the final summary.

## Work loop for Codex
1. Inspect the relevant files before editing.
2. State the intended plan in 3 to 6 bullets.
3. Make the smallest useful change.
4. Run the verification command listed below.
5. Summarize changed files, test results, and remaining risk.

## Verification
- Frontend package: `pnpm --filter web test`
- Type check: `pnpm --filter web typecheck`
- If tests cannot run, explain the exact blocker and the command attempted.

## MCP boundary
- Treat GitHub, issue tracker, and docs MCP servers as read-only unless the task explicitly grants write access.
- Do not post comments, change issue status, or open pull requests without human approval.
- Prefer linking to external context in the summary over copying large private content into code comments.

## Review expectations
- Show the final diff summary.
- Call out files that carry higher risk.
- Do not mark the task done until verification has either passed or the blocker is documented.

The important part is not the wording. The important part is that the Codex agent has the same contract every time it enters the repo.

Decide what Codex may do alone

Give Codex autonomy by category, not by mood. This small decision list is enough for many teams starting with OpenAI Codex in a real repo.

The limit matters. Codex workflows become easier to trust when the agent has a narrow lane and the reviewer has evidence, not when the agent has more tools.

Further reading

• Codex CLI docs
• Codex CLI features
• Codex slash commands

Set up one safe run

Bring one low-risk issue to our hands-on Codex training and leave with an AGENTS.md file plus a verification loop your team can reuse.