Codex CLI Workflows from GitHub

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

Start narrow: use OpenAI's Codex CLI from its GitHub repo as a repo-local coding loop, not as a free-running engineer. For OpenAI Codex training, I would point a team at the official docs and the openai/codex repository, then make them write down how Codex may read, change, and verify code before it touches a real issue.

The public repo and docs answer the basic setup question. The harder team question is how to turn Codex CLI work into repeatable CLI workflows: AGENTS.md instructions, a small MCP boundary, and a verification loop that survives review.

Start with a repo-local contract

Put the working rules in AGENTS.md before you optimize prompts. Codex needs the same facts a careful teammate would ask for: where the app starts, which commands prove a change, what style to preserve, and which areas are risky.

Keep the file short. A long policy document gets skimmed by humans and blurred by agents. If a subdirectory has different rules, use a nested instruction file there instead of forcing one root file to describe every part of the repo.

In a CLI repo such as openai/codex, I would not start with “improve the CLI.” I would start from one GitHub issue, ask Codex to inspect the likely command path, make one change, and run the nearest verification command before it summarizes the diff.

Put GitHub work into a verification loop

A Codex CLI GitHub workflow should move through code, terminal output, and review. Chat alone is not evidence.

Use this procedure when you pick up an issue or small PR:

1. Select one GitHub issue with a clear expected behavior.
2. Ask Codex CLI to inspect the relevant files and propose a two or three step plan.
3. Approve only the first slice of code change.
4. Run the repo's normal check for that slice: unit test, typecheck, lint, or a focused CLI command.
5. Ask Codex to summarize the changed files and the exact commands that passed or failed.
6. Review the diff in GitHub before merge, including any test gap Codex called out.

This is the Review step in our methodology: the agent can draft and repair, but the team owns the acceptance signal. If the command is slow or flaky, say that in AGENTS.md and name the smaller check that should run first.

Keep the first MCP connection read-only

MCP is the integration layer that lets Codex reach an external system through a server, such as GitHub issues, docs, or a private knowledge base. Start with read-only access if the server is new to the team.

Read-only is slower at first because someone still has to create comments, labels, or PR updates. That is fine. You are learning which context helps Codex and which writes would be dangerous if the model misunderstood the task.

For browser-heavy automation, the same boundary shows up in a different shape in Agents API computer use: build a browser agent step by step. The common habit is to separate observation from action until verification is boring.

Paste this AGENTS.md starter into a CLI repo

Use this as a starting point, then delete anything that is not true for your repository.

# AGENTS.md

## Scope
These instructions apply to this repository unless a nested AGENTS.md gives more specific rules.

## Working style
- Start from the GitHub issue or the user's stated goal.
- Inspect the relevant files before editing.
- Make the smallest code change that can be verified.
- Do not reformat unrelated files.
- Do not change public CLI behavior without calling it out in the final summary.

## Verification
Before handing back work, run the narrowest relevant check first.

Preferred order:
1. Focused unit test for the changed area.
2. Typecheck or lint for the package touched.
3. End-to-end or full test suite only when the change crosses boundaries.

If no check exists, state the gap and propose the smallest test or manual command that would prove the behavior.

## GitHub workflow
- Link the work back to the issue or PR when summarizing.
- Include changed files, verification commands, and remaining risks.
- Do not mark work as done if verification failed or was skipped.

## MCP boundaries
- Treat GitHub, docs, and private knowledge MCP servers as read-only unless the task explicitly allows writes.
- Never post comments, change labels, or update issues without naming the intended action first.

Decide what Codex may do before you connect GitHub

Make the permission decision explicit. Otherwise the first productive demo turns into a fuzzy production habit.

The limitation is obvious but worth saying: a tight loop is slower than giving Codex broad write access. It is also easier to debug when something goes wrong.

Further reading

• Codex CLI docs
• Codex CLI features
• Codex on GitHub

Next step

Pick one low-risk GitHub issue and run the loop above with the AGENTS.md starter in place. If you want a guided team version, the Codex CLI workflows track in hands-on training gives you the same exercise with review practice.