learn/best-practices.md Codex Docs, 2026-03-13 18:15 UTC → 2026-03-23 18:22 UTC

78- Keep repo-specific behavior in `.codex/config.toml`78- Keep repo-specific behavior in `.codex/config.toml`

79- Use command-line overrides only for one-off situations (if you use the CLI)79- Use command-line overrides only for one-off situations (if you use the CLI)

80 80 

81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, profiles, multi-agent setup, and experimental features. You can edit it directly or ask Codex to update it for you.81[`config.toml`](https://developers.openai.com/codex/config-basic) is where you define durable preferences such as MCP servers, profiles, multi-agent setup, and feature flags. You can edit it directly or ask Codex to update it for you.

82 82 

83Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.83Codex ships with operating level sandboxing and has two key knobs that you can control. Approval mode determines when Codex asks for your permission to run a command and sandbox mode determines if Codex can read or write in the directory and what files the agent can access.

84 84 

205 205 

206Keep one thread per coherent unit of work. If the work is still part of the same problem, staying in the same thread is often better because it preserves the reasoning trail. Fork only when the work truly branches.206Keep one thread per coherent unit of work. If the work is still part of the same problem, staying in the same thread is often better because it preserves the reasoning trail. Fork only when the work truly branches.

207 207 

208Use Codex’s [multi-agent](https://developers.openai.com/codex/concepts/multi-agents) workflows to offload208Use Codex’s [subagent](https://developers.openai.com/codex/concepts/subagents) workflows to offload bounded

209bounded work from the main thread. Keep the main agent focused on the core209 work from the main thread. Keep the main agent focused on the core problem,

210problem, and use subagents for tasks like exploration, tests, or triage.210 and use subagents for tasks like exploration, tests, or triage.

211 211 

212## Common mistakes212## Common mistakes

213 213