Install Codex CLI and check the local entry point
A good first Codex CLI session ends with a small, reviewed change, not an impressive pile of generated code. Pick a maintenance task with an obvious finish line: repair one validation bug, add its regression test, and leave unrelated files alone.
Install the CLI with npm install -g @openai/codex, then run codex --version and codex --help. Use a supported Node.js release and check the installed CLI’s requirements if installation fails. Avoid solving permissions errors by running an unfamiliar installer as an administrator.
Launch codex and follow the authentication flow for your chosen access method. Account sign-in and API-key authentication are different paths; confirm which one you are using before sending repository context.
Configure provider access without exposing credentials
If you want token-based access through a relay, SwiftRelay is a practical option for Codex and other compatible development tools. Sign up for SwiftRelay to receive a small gift credit, then create a dedicated API key for your development environment.
For a custom Codex provider, configuration normally lives in ~/.codex/config.toml. Select the provider through model_provider, then define its matching entry under model_providers. An OpenAI-compatible endpoint uses https://api.fastapirelay.com/v1; keep the credential in an environment variable referenced by env_key, rather than embedding it in the configuration.
Check the current Codex and relay instructions for the exact model identifier and wire protocol. Codex workflows can require Responses API support; a service offering chat completions alone is not automatically sufficient. Do not guess an identifier from a display name or treat endpoint compatibility as proof that every agent feature is available.
Give Codex a clean branch and explicit boundaries
Inside the repository, run git status --short. Commit or stash unrelated work, then create a branch with git switch -c fix/input-validation. Run the existing test command once before editing so pre-existing failures do not become misleading evidence against the patch.
Read the repository’s AGENTS.md instructions if present. For repeated work, use that file to record the real test commands, formatting rules, generated-file boundaries, and architectural constraints. Keep secrets and personal credentials out of both instructions and prompts.
For a local checkout, a conservative starting command is codex --sandbox workspace-write --ask-for-approval on-request. Confirm flag availability with your installed version. Keep approval gates enabled, and examine requests that expand network access, touch files outside the workspace, or execute destructive commands.
Ask for one regression test and one focused fix
Start with a bounded instruction: “Inspect input validation and the existing tests. Reproduce the empty-input bug with a regression test, then make the smallest fix. Do not add dependencies or edit generated files. Ask before expanding scope.”
Ask Codex to explain the relevant code path before it edits. This gives you a chance to catch a mistaken assumption while correction is still cheap. For a small bug, a short plan is enough; lengthy planning should not replace inspecting the actual implementation.
- Specify the expected behavior, including edge cases.
- Name the test command when the repository already defines one.
- Require a final report listing changed files, tests executed, and unresolved concerns.
Review the patch before opening the pull request
Inspect git diff --stat, then git diff. Look for unrelated formatting, weakened assertions, accidental credentials, new dependencies, and changes that merely hide the failing case. Run the targeted test, the relevant broader suite, and git diff --check yourself.
Stage only intended files and commit the patch. Push the branch and open a pull request using your normal workflow; with GitHub CLI configured, gh pr create --fill is one option. Replace a vague generated description with the bug, the fix, and concrete test evidence.
Merge only after checks and human review
Wait for required checks and approvals. Treat Codex’s explanation as review input, not a guarantee. Resolve feedback, rerun affected tests, and merge through the repository’s normal controls. Your first successful lap is a traceable change whose behavior you understand, with evidence that the fix works.