Contents
- 01Start From Zero and Choose the Right Surface
- 02Turn Intent Into Verifiable Work
- 03Configure Codex and Teach It the Project
- 04Bound Authority With Sandbox and Approvals
- 05Make the Change and Prove It
- 06Work Across Environments and Worktrees
- 07Delegate With Subagents
- 08Build the Extension Stack
- 09Automate, Embed, and Run Long Work Safely
- 10Capstone: From Command to Receipt
Configure Codex and Teach It the Project
Understand Codex configuration precedence, deliberately choose one permission system, write durable repository guidance, and place each recurring behavior in the smallest control surface that matches its scope.
By the end
A tested user configuration, a documented choice between permission profiles and older sandbox settings, a concise AGENTS.md hierarchy, and a decision map for prompts, configuration, skills, plugins, MCP, hooks, and scheduled work.
Understand what configuration wins
Codex combines several configuration layers. Current precedence is: CLI flags and `--config` overrides, trusted project `.codex/config.toml` files from root toward the working directory, a named user profile selected with `--profile`, user `~/.codex/config.toml`, system configuration, then built-in defaults. The higher layer wins for ordinary values. This explains why changing a user default may appear to do nothing when a project or launch flag overrides it.
Only trust a project-scoped `.codex/` layer when you trust the repository. Untrusted projects skip project config, hooks, and rules. Keep machine-specific credentials, providers, notifications, and telemetry in user config; project config should describe behavior safe for everyone who trusts that repository. Inspect the official config reference before adding a key because accepted values can evolve.
Do not confuse config overlays with permission profiles
Codex now has two different ideas that are both easy to call a profile. A named config overlay is a separate file such as `~/.codex/deep_review.config.toml`, selected with `codex --profile deep_review`; it can change any documented configuration key. A permission profile is an access policy selected by `default_permissions`, such as the built-ins `:read-only`, `:workspace`, and `:danger-full-access`, or a custom name defined under `[permissions.<name>]`. The CLI flag `--profile` selects a config overlay, not a colon-prefixed permission profile.
The newer permission-profile system is currently beta, and it does not compose with the older sandbox system. Choose either `default_permissions` plus `[permissions]`, or `sandbox_mode` plus `[sandbox_workspace_write]` and the `--sandbox` flag—never both in the same loaded configuration. If any loaded config or config overlay contains `sandbox_mode`, or the launch command passes `--sandbox`, Codex uses the older sandbox settings instead of `default_permissions`. This guide recommends the newer permission-profile path for fresh setups and shows the older path only as an explicitly separate compatibility lane; re-check the official reference as the beta evolves.
AGENTS.md is repository guidance
An AGENTS.md file gives Codex durable instructions for work in a repository. It is the right place for canonical commands, important architecture boundaries, coding conventions that are not obvious from nearby source, safety rules, and the evidence required before completion. It saves every future task from rediscovering the same operating facts.
Keep it reviewable by humans. Codex already sees the code, so the file should explain what the code does not make obvious: which checkout is canonical, which generated files should not be hand-edited, which test targets matter, where product rules live, and which actions require explicit approval.
Use scope instead of one giant file
Repository guidance can be layered. A root AGENTS.md can define rules for the whole project, while a more specific file can describe a subtree with different commands or conventions. The goal is not duplication. Put each durable instruction at the narrowest level where it remains true.
For example, the root may explain how to preserve a dirty worktree and run the main build. A mobile subtree may name the simulator and native tests. A database subtree may require migration and rollback checks. A nested file should add or refine local facts rather than copy the root word for word.
Choose the smallest control surface
Not every recurring preference belongs in AGENTS.md. A one-time constraint belongs in the task prompt. A trusted repository default may belong in project configuration. A reusable workflow with judgment belongs in a skill. A distributable bundle belongs in a plugin. Live external tools and data belong behind MCP or an app connector. A deterministic lifecycle check belongs in a hook. Recurring work belongs in an automation only after the workflow is stable.
This separation prevents instruction bloat and hidden behavior. It also makes problems diagnosable. If Codex is missing a business rule, inspect guidance. If it lacks a capability, inspect the tool or plugin. If it is allowed to do too much, inspect permissions. If the same unsafe command must always be blocked, inspect policy or hooks rather than hoping every prompt remembers.
- Prompt: temporary constraints for one task or conversation.
- AGENTS.md: durable repository conventions and verification expectations.
- Configuration: trusted environment defaults and product settings.
- Skill: a reusable task method, references, and optional scripts.
- Plugin: an installable package of capabilities for broader reuse.
- MCP or connector: authorized access to external data and actions.
- Hook: deterministic enforcement around lifecycle events.
- Automation: a scheduled or recurring execution with its own receipts.
Write operational instructions, not a company biography
A high-signal instruction is concrete: use this command, preserve these files, follow this existing pattern, do not publish from local tests, and report this evidence. A low-signal instruction says to be excellent, use best practices, or understand the whole company. Generic aspirations consume attention without changing decisions.
Never place secret values, personal access tokens, or volatile incident status in repository instructions. Name required environment variables without their contents. Link to an owned document when a long policy is necessary, and make clear whether the linked material is authoritative or optional context.
Test and maintain the guidance
Instructions are part of the operating system and can fail like code. Start a fresh task in the relevant directory and ask Codex to state the commands, boundaries, and verification requirements it received. Run one harmless task and confirm that the intended behavior actually changes.
Review AGENTS.md when commands, architecture, deployment, or ownership changes. Remove statements that source can reveal cheaply and rules that no longer alter behavior. A short accurate file is safer than an encyclopedic file whose stale sections appear equally authoritative.
Working reference
Commands and patterns
File contents: ~/.codex/config.toml for built-in read-only
default_permissions = ":read-only"
Save this as TOML after removing all older sandbox settings. The colon is part of the built-in permission-profile name; never pass `--sandbox` with this setup.
Terminal: launch built-in read-only
codex
Run this terminal command only after saving the preceding file and auditing every loaded config layer for older sandbox settings.
File contents: ~/.codex/config.toml for project editing
default_permissions = "project-edit" [permissions.project-edit] description = "Workspace editing with environment files denied." extends = ":workspace" [permissions.project-edit.filesystem.":workspace_roots"] "**/*.env" = "deny"
Save this complete TOML alternative instead of the built-in read-only file. It inherits the workspace boundary and denies matching environment files; keep older sandbox settings out of every layer.
Terminal: launch custom project-edit permission profile
codex
Run this terminal command after saving the project-edit TOML. The top-level `default_permissions` value selects the custom profile without a `--sandbox` flag.
File contents: ~/.codex/deep_review.config.toml
model_reasoning_effort = "xhigh"
This pure TOML config overlay changes a non-permission setting. The base user configuration still supplies the separately chosen permission profile.
Terminal: launch the deep_review config overlay
codex --profile deep_review
The `--profile` flag selects the saved config overlay; it does not select a colon-prefixed permission profile.
File contents: ~/.codex/legacy_read_only.config.toml
sandbox_mode = "read-only" approval_policy = "never"
This pure TOML file is the separate older compatibility lane. Use it only after removing every newer permission-profile key from the loaded configuration.
Terminal: launch the legacy read-only config overlay
codex --profile legacy_read_only
This selects the older sandbox configuration saved in the preceding file. Never combine that file with newer permission-profile keys.
When the happy path breaks
Failure modes
Symptom
Codex ignores an important project command or convention.
Likely cause
The guidance is absent, placed outside the relevant scope, contradicted by a more specific instruction, or buried in excessive text.
Recovery
Locate the smallest correct AGENTS.md scope, remove contradictions and filler, then test behavior in a fresh task.
Symptom
The instruction file becomes a large dump of architecture, history, and temporary status.
Likely cause
AGENTS.md is being used as the only memory, documentation, workflow, and configuration surface.
Recovery
Keep durable operating facts in AGENTS.md and route detailed knowledge, reusable procedures, tools, enforcement, and recurrence to their appropriate surfaces.
Symptom
A rule works for one folder but causes bad behavior elsewhere.
Likely cause
A local convention was written at repository root.
Recovery
Move the rule to a nested AGENTS.md under the subtree where it is consistently true and verify both scopes.
Symptom
A credential or sensitive value appears in source control.
Likely cause
Configuration guidance included an actual secret instead of a variable name and secure setup route.
Recovery
Revoke and rotate the exposed value, remove it from current and historical content as appropriate, and document only the secret's name and approved storage mechanism.
Symptom
A permission profile appears to be ignored.
Likely cause
A loaded config, selected config overlay, or CLI `--sandbox` flag activates the older sandbox system, which takes precedence over `default_permissions`.
Recovery
Choose one system. For the newer path, remove `sandbox_mode`, `[sandbox_workspace_write]`, and `--sandbox` from every loaded layer; for the older path, remove `default_permissions` and `[permissions]`.
Symptom
Changing `~/.codex/config.toml` does not change the session.
Likely cause
A higher-precedence CLI override, trusted project config, or selected profile supplies the same key.
Recovery
List the active launch arguments and project `.codex/config.toml` layers, then remove or intentionally change the highest-precedence value.
Hands-on lab
Build the project's Codex control map
Create a high-signal AGENTS.md and classify recurring needs across the available control surfaces.
- 01Inspect your current user config without printing credentials. List every trusted project config, selected config overlay, and CLI launch flag, then write one explicit choice: newer permission profiles or older sandbox settings.
- 02For the recommended newer lane, remove `sandbox_mode` and `[sandbox_workspace_write]` from every loaded layer and do not pass `--sandbox`. Set `default_permissions = ":read-only"`, launch Codex, request a harmless file creation, and capture the denial.
- 03Still in the newer lane, define and select the custom `project-edit` permission profile from the example. Launch without `--sandbox`, create and remove a harmless workspace file, and verify that a matching `.env` target remains denied.
- 04If compatibility requires the older lane instead, do not perform the preceding permission-profile steps: remove `default_permissions` and `[permissions]`, use the isolated legacy example, and capture the same read-only denial. Never load both systems for comparison in one setup.
- 05Create the `deep_review` config overlay and verify that `codex --profile deep_review` changes reasoning effort while the separately selected authority mechanism remains the one you chose.
- 06Collect the verified install, development, test, lint, build, and deployment commands without copying secret values.
- 07Write the non-obvious architecture, safety, generated-file, and completion rules that apply to the whole repository.
- 08Identify one subtree with genuinely different instructions and add a narrow nested AGENTS.md only if needed.
- 09Classify at least ten recurring requirements as prompt, AGENTS.md, config, skill, plugin, MCP, hook, or automation.
- 10Start a fresh task and ask Codex to restate the applicable commands and boundaries.
- 11Run one harmless change and verify that the guidance produces the intended workflow and receipts.
Deliverable: A demonstrated permission-system choice with denial evidence, one non-authority config overlay, a source-controlled instruction hierarchy, and a control-surface decision table with owners and review dates.
Reusable artifact
High-signal AGENTS.md
A compact repository contract for future Codex work.
# Purpose - [One sentence describing the system and primary user outcome.] # Canonical locations - Repository root: [rule or path] - Primary entry points: [paths] - Source of truth: [data, schema, or document] # Commands - Install: `[command]` - Develop: `[command]` - Targeted test: `[command]` - Lint/typecheck: `[commands]` - Build: `[command]` # Architecture and conventions - [Non-obvious boundary or existing pattern to reuse.] # Safety - Preserve unrelated user changes. - Never expose secret values or commit environment files. - Pause before deletion, publishing, production mutation, external communication, payments, or permission expansion. # Completion - Report changed files, commands, observed results, and remaining risk. - Do not equate source or local proof with deployed proof.
Before you move on
Receipt checklist
- The root and any nested AGENTS.md files contain only instructions true within their scope.
- Every command in the guidance was checked in the current repository.
- No secret value, temporary incident state, or generic filler appears in the instructions.
- A fresh task can restate the correct rules without manual prompting.
- Each recurring behavior is assigned to the smallest appropriate control surface.
Primary sources
