Your first Codex task should end with a change you understand, not merely generated code. This walkthrough uses a small bug fix: trimming whitespace before validating an email address. Follow the same sequence for another narrowly scoped issue.
1. Install Codex CLI and Check the Command
With Node.js and npm available, run npm install -g @openai/codex, then codex --version. Confirm that the second command prints a version before continuing. If your terminal cannot find Codex, check your npm global executable directory and shell PATH rather than repeatedly reinstalling. ([help.openai.com](https://help.openai.com/en/articles/11096431?utm_source=openai))
2. Choose Your Codex Authentication Route
Run codex and follow the available authentication prompts. For direct OpenAI access, use the appropriate sign-in method. If you prefer pay-as-you-go relay billing, SwiftRelay works with Codex and charges per token. Sign up for SwiftRelay to receive a small gift credit for your first experiment. ([developers.openai.com](https://developers.openai.com/codex/cli))
For a relay connection, configure the provider in ~/.codex/config.toml, using the relay's Codex-specific endpoint and exact model identifier. Codex supports provider settings including base_url, env_key, and wire_api = "responses". Confirm Responses API and tool-call compatibility for your selected route; generic OpenAI compatibility alone is not a sufficient check. Keep the API key in an environment variable, not your repository. ([developers.openai.com](https://developers.openai.com/codex/config-advanced))
3. Create a Clean Branch Before Asking for Edits
Open a trusted repository and run git status. Commit or stash unrelated work, then create a branch with git switch -c fix/email-whitespace. Run the project's documented tests now and record existing failures. This gives you a baseline for deciding whether the eventual patch introduces a regression.
Choose an issue with an observable result: an otherwise valid email address should still validate when surrounded by spaces. Avoid combining that fix with dependency upgrades, formatting changes, or a validation rewrite.
4. Give Codex Repository Rules and Bounded Permissions
Inspect existing AGENTS.md files before adding instructions. Codex reads these files as project guidance. If guidance is missing, document the actual test command, formatting rules, and directories that should remain untouched. Do not invent commands without checking the repository. ([developers.openai.com](https://developers.openai.com/codex/guides/agents-md))
Start the session with codex --sandbox workspace-write --ask-for-approval on-request. This permits workspace changes while retaining approval boundaries for actions requiring broader access. Review escalation requests individually; do not disable the sandbox simply because a command needs permission. ([learn.chatgpt.com](https://learn.chatgpt.com/docs/agent-approvals-security?translationFallback=pt-BR&utm_source=openai))
5. Request a Plan, Regression Test, and Minimal Fix
Give Codex this focused prompt:
Find the email validation entry point. Explain where whitespace should be normalized, then add a regression test for surrounding spaces and implement the smallest fix. Preserve rejection of invalid addresses. Avoid unrelated refactoring and new dependencies. Run the relevant tests and report their exact results.
Read the proposed approach before authorizing broader work. Require clarification if trimming would change a shared utility or affect stored values. Keep the acceptance criteria tied to behavior rather than a preferred implementation.
6. Verify the Patch Beyond the Agent's Report
Inspect git diff --stat, git diff, and git diff --check. Read every changed file. Rerun the targeted test yourself, followed by the repository's normal lint, type-check, and test commands. Distinguish passing checks from checks that could not run.
Use /review in Codex to request a review of uncommitted changes. Treat its findings as another review input, not approval to merge. Ask specifically about empty strings, whitespace-only input, and unintended changes to invalid-address handling. ([developers.openai.com](https://developers.openai.com/codex/cli))
7. Commit, Open the Pull Request, and Merge
Stage only intended files with git add, inspect git diff --cached, and commit with git commit -m "Fix email validation with surrounding whitespace". Push using git push -u origin fix/email-whitespace, then open a pull request through your repository host.
Describe the original behavior, the fix, and the checks you actually ran. Resolve reviewer feedback and wait for required CI checks and approvals before merging. After merging, update your local default branch and confirm the merged commit is present. Your first successful Codex change is a reviewed, tested patch—not an unattended commit.