Use Codex CLI for a Bounded README Change

For: builders and operators who need a small, reviewable change in a local repository.

Artifact: a reviewed README diff that changes one section and leaves unrelated files untouched.

Evidence label: Documentation-based guide. The commands and workflow are based on the current Codex CLI documentation. No Codex execution is claimed here.

Advanced builder lesson: this requires a terminal, a local Git repository, and permission to run commands. If you do not use Git or a coding agent, use the no-code alternative below.

What Codex CLI is

OpenAI describes Codex CLI as a local coding agent that can read, change, and run code in the selected directory. The Codex documentation also describes repository work, tests, commands, and change review as part of its use. Access, model options, and workspace policies can vary.

Sources: Codex CLI, ChatGPT Work and Codex.

Fictional repository task

Assume this repository contains README.md with a section called Local setup. You want to add one sentence explaining where the example data lives. You do not want a code change, a dependency update, or a new file.

Expected change:

README.md only
Add one sentence under "Local setup":
"Example input files live in the examples/ directory."
Do not change any other wording.

Three steps

1. Open a terminal in a disposable clone or a branch where you can review changes. Confirm the starting state before the agent works:

git status --short
git branch --show-current
test -f README.md && printf 'README exists\n'

If the working tree already contains unrelated changes, stop and save them or use a clean copy.

2. Start Codex in that repository with codex. Give it this bounded brief:

Edit README.md only.

Task: under the existing heading "Local setup", add exactly this sentence:
"Example input files live in the examples/ directory."

Constraints:
- Do not edit any other file.
- Do not add dependencies.
- Do not run destructive commands.
- Do not rewrite nearby wording.
- Before finishing, show the proposed diff and stop for my review.

Acceptance checks:
- git diff -- README.md shows one added sentence.
- git diff --name-only shows only README.md.
- The sentence appears once.

3. Review the result outside the agent. Run:

git diff -- README.md
git diff --name-only
rg -n -F "Example input files live in the examples/ directory." README.md

Then run the repository’s documented checks, if any. Do not treat a clean diff as proof that the sentence is factually correct. Check the path and wording yourself before committing.

What to accept

Accept the change only when git diff --name-only returns README.md, the sentence occurs once, the surrounding section remains intact, and the repository checks pass. If the repository has no checks, record that fact rather than claiming a test result.

Common failure fixes

Codex edits several files. Stop. Reset only the agent’s changes if you understand what they are, or discard the disposable clone. Restart with a clean working tree and a stricter file allowlist.

The heading does not exist. Do not let the agent create a new section by assumption. Ask for a report of the closest matching headings, then decide where the sentence belongs.

The agent runs an unexpected command. Stop the session and inspect the command and its effect. Use a disposable copy for unfamiliar repositories and never provide production credentials just to edit documentation.

No-code alternative

Open the README in your normal editor, make the one-sentence change, and use the same three checks. The useful lesson is the boundary and review process, not the agent brand.

Limits and access

Codex CLI is a local technical tool, not a substitute for repository permissions or review. The exact commands, model choices, and policies shown in the interface can vary by installation and workspace. Keep secrets out of prompts and review every file change before a commit or deployment.

For a related technical guide, read Use Claude Code to Remove Exact Duplicate Rows from a Sample CSV.