The Codex Developer
Field Guide for macOS

Start with a predictable Mac environment

A useful Codex session starts with a reproducible toolchain. Open Terminal, identify your macOS version and process architecture, and verify the tools the repository actually needs. An installed command is not proof that its version, permissions or dependencies are correct.

sw_vers
uname -m
xcode-select -p
git --version

Use a macOS release supported by your hardware and required toolchains. Install Xcode Command Line Tools before native builds. Homebrew is a convenient package manager, while project runtime versions belong in the repository. Node, Python and Rust are stack-dependent; they are not all prerequisites for using an agent.

On Apple Silicon, prefer native arm64 binaries. On Intel, check each tool’s current support and available x86_64 release. Do not solve architecture mismatches by mixing libraries from two Homebrew prefixes.

Begin at the repository boundary

Launch Codex from the project root for a clear default scope and predictable relative paths. Root manifests, lockfiles and instructions describe how the application fits together. Nested invocation is valid, but changes the working context; it does not inherently make ancestor instructions invisible.

cd "$HOME/Projects/my-project"
git status
git branch --show-current
git log --oneline -5
git diff
git diff --staged

Replace my-project with your existing checkout. A failed cd means you should stop before running later commands. In shell syntax, ~ expands at the start of an unquoted word; use "$HOME/Projects/My App" when a path contains spaces. Home directories commonly live under /Users, but $HOME avoids guessing a username or managed account location.

Inspect this repository before editing. Read applicable AGENTS.md and README
files. Map the architecture, manifests, lockfiles and relevant source files.
Identify build/test commands and current Git changes. Preserve existing user
work. Report evidence, uncertainties and a bounded plan for the requested task.

Give every project an AGENTS.md

AGENTS.md records durable engineering instructions, not an operating-system setting or a security sandbox. Put project-wide conventions at the root and specialized instructions near the code they govern. Keep actual build and test commands current.

Codex combines global and project instructions along its discovery path. Within a directory, AGENTS.override.md takes precedence over AGENTS.md. More specific instructions refine broader guidance; ask Codex to identify the sources it loaded when behavior is surprising. Starting in a specialized directory can change which instructions are discovered.

# AGENTS.md — Project engineering agreements

## Context and scope
This example is for a static website with HTML, CSS and JavaScript.
Inspect README.md, applicable instructions and existing files before editing.
Keep the site deployable as static files. Do not add a backend or framework.
Preserve existing routes, accessible controls and public behavior.
Use directory instructions for specialized modules. Identify conflicts.

## macOS development
Use UTF-8 and LF; quote paths with spaces. Keep filenames case-consistent.
Use portable shell syntax or explicitly declare zsh-specific scripts.
Do not assume GNU utilities or a particular Homebrew prefix.
Never use sudo to fix a project dependency installation without diagnosis.

## Build and test
No production build is required for this example static site.
Preview: python3 -m http.server 8765 --bind 127.0.0.1
Check JavaScript: node --check assets/js/app.js
Test all changed interactions, keyboard access and mobile layouts.
Check links, assets and browser console. Replace example paths if different.
Run repository-defined checks; report actual commands, exit codes and scope.

## Security and completion
Never commit .env files, credentials or diagnostic logs containing secrets.
Do not disable Gatekeeper, change global permissions or deploy without scope.
Review git diff and git diff --staged. Preserve unrelated user work.
Report files changed, verification evidence and remaining limitations.

This example is for a static website; adapt commands to the real repository. Use the AGENTS.md generator to write project-specific build, test and architecture rules. Avoid boilerplate that demands tools the project does not use.

Reference: OpenAI: custom instructions. Documentation checked 5 September 2026.

Give specifications, not vague requests

“Make the app better” leaves the agent to guess what matters. Specify the observed problem, inputs, expected outcomes and boundaries. A small measurable requirement is easier to implement and review than a stylistic preference alone.

Improve the project navigation on small screens.
Inspect the current header, styles, scripts and applicable AGENTS.md first.
Requirements: usable at 375–1920 CSS px, keyboard operable, visible focus,
Escape closes the menu, focus returns to the opener, no page overflow.
Preserve existing routes, search and desktop behavior. Add no dependencies.
Identify affected files and propose bounded steps before implementing.
Verify the controls in a browser and report viewport coverage and failures.

Include one concrete before/after example and an error case. For an API, name status codes and response contracts. For a CLI, define exit behavior and output. For a Mac utility, distinguish supported CPU architectures, minimum OS policy and required file permissions.

Use the task prompt builder for repeatable structure. Review the generated text before submitting it: form completeness is not specification quality.

Deliver in verified stages

Split work at meaningful boundaries: data contracts, core behavior, integration and release verification. Each stage should leave a reviewable result and a clear next step. Large requests can still be handled end to end when progress is grounded in intermediate checks.

• Define interfaces and invariants before callers depend on them.
• Implement the narrow behavior and exercise its boundary cases.
• Connect UI or integrations, including loading and failure states.
• Review the diff, run the production path and update documentation.

For a native Mac dependency, prove one minimal compilation before rewriting application code. If the dependency only ships x86_64 artifacts, resolve that support decision before integrating it into an arm64 build.

Implement the agreed feature in bounded stages. After each meaningful stage,
run the relevant checks and fix failures caused by the change. Continue within
the authorized scope. Pause only for a material missing decision or an action
that exceeds that scope. Keep a concise record of completed and remaining work.

Inspect evidence before implementation

Investigation prevents a plausible fix from being applied to the wrong layer. Ask Codex to locate definitions, callers, tests and repository instructions before editing. Distinguish an observed failure from a hypothesis about its cause.

Investigate the repeated authentication redirect. Do not edit yet.
Trace session creation, expiration and refresh through the existing handlers.
Use the supplied reproduction and sanitized logs. Cite relevant file paths
and explain the failing condition. Identify a minimal fix and a regression
check. Ask for a decision only if the requirements leave a material ambiguity.

A plan should identify files, intended behavior and verification. It should not confidently name a library API that has not been checked. If an external tool changed, consult its current primary documentation rather than patching around a guessed command.

Make Codex prove the result

A completion statement needs evidence: what command ran, where it ran, its exit status, and what behavior it covered. Passing a unit test does not prove a release archive launches on both Mac architectures.

# Discover declared npm scripts before selecting one
npm run
# Python example: only if pytest is installed in this project environment
.venv/bin/python -m pytest
# Rust example: only in a Cargo repository
cargo test

Tests and builds can write files, execute package hooks, call networks or touch databases. Inspect unfamiliar scripts and use test services, not production credentials. Do not run every example above in every project.

• Use the repository’s lint, type, unit, integration and build checks as applicable.
• Record pre-existing failures separately from regressions caused by the change.
• Test behavior at boundaries: missing input, permission denied, timeout and cancellation.
• State untested platforms and blocked checks explicitly.

Report the exact checks run and their results. If a check is unavailable,
state why and what remains unverified. Do not call a mock or a simulated
architecture run a native macOS test. Review the final diff before completion.

Use Git as a deliberate safety system

The working tree holds your current files. The staging area (index) selects the next snapshot. A commit records that snapshot; a branch names a line of commits. A remote is another repository, not an automatic backup of uncommitted files.

git status
git diff
git diff --staged
git log --oneline -5

Before significant agent work, preserve valuable changes. Review new files as well as diffs: ordinary git diff does not show untracked file contents. Stage only intended paths, inspect the staged snapshot for secrets, then commit when the checkpoint is coherent.

# Example paths: substitute the files you reviewed
git switch -c feat/navigation
git add -- index.html assets/css/app.css
git diff --staged
git commit -m "checkpoint: navigation baseline"

Reference: Git: working-tree and staged comparisons. Documentation checked 5 September 2026.

Give Codex controlled autonomy

Define outcomes and operating boundaries, then allow routine work within them. Reading source, implementing an authorized change and running understood checks can progress without repeated confirmations. Publishing, destructive data changes and new external access require clear authorization.

• Name allowed directories and interfaces that must remain stable.
• Specify whether dependency changes, migrations or network services are in scope.
• Use test accounts and least necessary access. Keep production credentials out of the session.
• Require reviewable diffs and an evidence-based final report.

Sandboxing and approval controls are enforcement mechanisms; AGENTS.md is guidance. Inspect the active Codex configuration and organization policy. Do not disable protections globally merely because one command fails.

Work autonomously on the requested navigation fix in this repository.
Preserve unrelated changes and existing routes. Run the established checks.
Do not publish, change credentials or alter the database. Report a concrete
blocker if the work needs access or decisions outside these boundaries.

Debug from a reproduction, not a guess

Give the exact error, shortest reproduction, expected behavior and environment. Remove tokens and personal paths from logs. “Add a delay” prescribes a solution before a race condition has been established.

sw_vers
uname -m
command -v node
command -v codex
lsof -nP -iTCP:3000 -sTCP:LISTEN

On macOS, distinguish a port conflict from a permission failure, and a missing command from a mismatched binary. Compare the editor terminal with Terminal.app: they may start different shell modes or inherit different PATH values. A process reporting x86_64 may be translated on Apple Silicon.

Reproduce this error using the supplied steps. Inspect the failing code,
selected executable paths, tool versions and relevant configuration.
List observations separately from hypotheses. Identify the root cause,
propose the smallest fix, then verify the original reproduction and a nearby
negative case. Do not hide the failure by suppressing errors or adding delays.

For process termination, identify the owning program and stop its development server normally. Escalate signals only when necessary; never kill every process with a familiar name.

Verify the browser experience

Check desktop, tablet and mobile layouts, then keyboard and touch behavior. A command block may scroll internally, but the whole page should not become wider than the viewport. Visible focus, readable contrast and usable controls are part of functionality.

• Exercise 375, 768, 1280 and 1920 CSS px plus zoom/reflow at 320 CSS px.
• Open and close menus and dialogs, test Escape and focus return, and follow navigation anchors.
• Test empty search results, copy failures, form resets and downloads.
• Inspect console errors and missing network assets. Disable JavaScript and check documentation access.

Use Safari on macOS for final Safari validation. Automated WebKit checks help, but do not prove the behavior of the shipping Safari build, VoiceOver, Keychain integrations or native application packaging.

Review the changed UI in a browser. Check responsive layout, zoom, keyboard
navigation, visible focus, contrast, reduced motion and no-JavaScript content.
Exercise every changed control and failure state. Record browsers and viewport
sizes actually tested; list Safari/VoiceOver coverage separately.

Recover failed work without losing evidence

When an approach repeatedly fails, stop expanding it. Preserve the error, relevant diff and reproduction. Identify whether the failure comes from the requirement, design, environment or implementation. A fresh conversation may help clarity, but should not erase diagnostic history.

git status --short
git diff --stat
git diff
git diff --staged

If the agent mixed its work with yours, examine changes path by path and hunk by hunk. A blanket restore can erase both. A corrective commit is often appropriate for shared history; changing published history affects collaborators and needs coordination.

Stop broad edits. Summarize the failed approaches and evidence. Inspect the
current diff and separate intended changes from regressions and pre-existing
user work. Propose a minimal recovery. Do not reset the repository or delete
untracked files. Retest the original failure after the targeted correction.

Keep the next session reproducible

Update documentation when commands, public behavior or architecture change. Future agents and teammates need a working path from checkout to verification. Document exact prerequisites in repository terms instead of describing only your personal machine.

• README: purpose, setup, runtime versions, configuration and first test.
• AGENTS.md: current conventions, architecture boundaries and real verification commands.
• Architecture notes: decisions, tradeoffs and data ownership.
• Release notes: externally visible changes, migration steps and known limitations.

For a Mac project, record CPU targets, minimum deployment target, native dependency requirements and signing prerequisites. Separate the OS support policy from a package manager’s support tier. Keep secret-free examples; do not paste local diagnostic logs into public docs.

Audit documentation against the repository. Verify every documented command
exists, inspect the lockfiles and build configuration, and correct only stale
instructions affected by this task. Record Mac architecture constraints and
untested environments. Link primary sources for volatile installation advice.

Use parallel agents selectively

Parallel work is useful when tasks have independent inputs, bounded outputs and clear owners. One agent can review accessibility while another investigates a backend defect. More agents do not automatically reduce integration cost.

Separate branches in a single checkout do not isolate concurrent edits. Git worktrees provide separate working directories. Assign ownership of files, ports, test databases and generated artifacts; integrate through one responsible reviewer.

# From an existing repository with a commit
git worktree list
git worktree add -b review/accessibility ../project-accessibility

Agree interfaces before parallel implementation. Review each result and run integrated checks after combining changes. Do not duplicate dependency installation or builds against shared output directories. Worktrees still share repository metadata, and processes can still contend for external services.

Reference: Git: multiple working trees. Documentation checked 5 September 2026.

Use specialist perspectives with evidence

A role prompt changes the questions asked; it does not confer expertise or prove findings. Require the reviewer to cite code, explain impact and distinguish confirmed defects from opportunities.

• Architecture: boundaries, dependencies, state ownership and migration cost.
• Security: input trust, authorization, credential handling and concrete exploit conditions.
• QA: boundary cases, regression coverage and unreliable tests.
• Performance: repeatable measurements before optimization.
• Accessibility: keyboard, semantics, contrast and assistive-technology behavior.

Act as a macOS compatibility reviewer. Inspect build scripts, native modules,
paths and packaging. Cite each finding with a file and failing condition.
Separate arm64, x86_64 and BSD/GNU compatibility. Recommend bounded fixes and
verification steps. Do not rewrite the project or claim native tests you did
not run. Prioritize observed release blockers over speculative preferences.

The prompt library includes general engineering roles and platform reviews. Choose the role that matches the decision, then provide real repository context.

Establish a professional completion contract

Define done before work begins. Completion means the requested behavior exists, the relevant checks ran, and the result is reviewable. It does not mean that every conceivable test or unrelated improvement must be added.

• Requested behavior meets the acceptance criteria.
• Existing behavior has been checked for regressions.
• No unfinished placeholders or fake implementations remain.
• Invalid inputs, empty states and error paths were exercised.
• Formatting follows repository conventions.
• Applicable lint checks passed or a justified exception is recorded.
• Applicable type/compiler checks passed.
• Relevant automated tests were actually executed.
• The production build or static deployment check succeeded.
• Secrets, input handling and permission changes were reviewed.
• Keyboard, focus, contrast and responsive behavior were checked.
• Working-tree and staged diffs were reviewed.
• Target-platform manual tests and their limits are recorded.
• Setup, architecture and usage documentation are current.
• Known limitations and deployment/recovery steps are recorded.

Before declaring completion, inspect the final working-tree and staged diffs.
Report:
- Behavior implemented and files changed.
- Exact verification commands, results and coverage.
- Manual/browser/platform checks actually performed.
- Remaining risks, blocked checks and unverified environments.
- Deployment or recovery steps relevant to the change.
Do not substitute confidence for evidence or describe unrun tests as passing.

Use the completion checklist to track your review. Its checkmarks are your own record, not automated certification.