This is not a beginner's guide, and you should have a bit of experience using Codex. Since I am not familiar with the Rust language used in the official repository, all information comes from PR and Issue discussions, and there may be empirical errors. If there are factual inaccuracies, please correct them. This article leans towards a tuning guide for Windows; if you can finish this, you will likely find MacOS/Linux even easier to handle.
Basic Configuration config.toml#
To do a good job, one must first sharpen their tools. For the Codex tool, it is strongly recommended to read the configuration document config.md.
Configure the basic Codex in ~/.codex/config.toml
model = "gpt-5-codex" # Codex 0.36.0 support
model_reasoning_effort = "high" # Use maximum reasoning capability
model_reasoning_summary = "detailed" # Display detailed reasoning summary in the terminal (view with ctrl+T) OpenAI does not provide reasoning processes, only reasoning summaries
model_verbosity = "high" # Not sure, just max it out
model_supports_reasoning_summaries = true # Force enable reasoning summaries, applicable for custom API KEYs
hide_agent_reasoning = false # Allow more internal thought processes of AGENT to be displayed
disable_response_storage = true # Do not allow OpenAI server to store your conversations
approval_policy = "never" # Configured but not used, just leave it for now, recommended to configure via /approvals
sandbox_mode = "workspace-write" # Configured but not used, just leave it for now, recommended to configure via /approvals
# allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true
Commands#
codex --helpis a good habit
After executing codex in the terminal, type / to get a list of currently supported shortcuts.
/status#
The most commonly used command, used to check current permissions and GPT-5 model configuration. If you are using a custom API Key, you should use this command more often to check if the correct model is being used.
/approvals#
Grant Codex permissions, currently there are three types, if exceeding permission limits, user confirmation is required:
- Read Only: Default permission, can only read files (in practice, this is too restrictive and contradicts the free coding philosophy of Agent Coding; a task may require manual approval more than ten times. Too troublesome)
- Auto: Read and write, run commands (in practice, it is not Auto at all, still requires too many manual approvals)
- Full Access: Read and write, use network tools (although the official repeatedly states to be careful, this is my daily usage method, true Auto, the whole process does not require a single confirmation)
Personally, I prefer to use Full Access daily, which allows adding extra command parameters each time Codex runs, without needing to reselect permissions each time:
codex --dangerously-bypass-approvals-and-sandbox
/mcp#
If you are a Windows developer, following mcp_servers will likely result in configuration failure. Typically, when entering Codex, you will see:
Program not found or request timed out
You need to add the following based on the original tutorial document:
- Add
commandpointing to the specific npx location - Add
envcontaining SYSTEMROOT
[mcp_servers.context7]
command = "C:\\Program Files\\nodejs\\npx.cmd"
args = ["-y", "@upstash/context7-mcp", "--api-key", "<your_api_key>"]
env = {SYSTEMROOT = 'C:\Windows'}
Resume/Continue Conversation#
The resume/continue conversation feature is still under development, so the corresponding description has not yet been added to
--help, but it is currently available
Conversations with Codex are saved in the local directory ~/.codex/sessions, and we can execute the following command to select the recent conversation list to resume and continue the conversation.
codex --resume
continue directly resumes the last conversation without selection
codex --continue
Tool Invocation#
To help Codex complete searches quickly and accurately, we need to use different tools specifically.
Different system platforms have different Shell tools; this article mainly focuses on the Windows platform, aiming to guide Codex to use the correct commands and tools, reducing error retries and shortening the execution time of single tasks.
Codex supports adding an AGENTS.md file at the root of the code repository to guide Codex on the rules to follow in that repository, such as the technology stack and tool invocation.
Currently, three main tools are used: fd, ripgrep, and ast-grep.
- Find by filename →
fd - Find by text content →
rg(ripgrep) - Find by code structure/semantics →
sg(ast-grep)
Windows Installation#
winget install sharkdp.fd BurntSushi.ripgrep.MSVC ast-grep
After installing ripgrep, you need to manually add it to the environment variable, solve it yourself
AGENTS.md#
During actual operations, it was found that simply declaring available tools without guiding specific usage often leads to deviations from expectations. Therefore, it is recommended to copy the following complete configuration and adjust as needed.
## Tool Priority
- Filename search: `fd`.
- Text/content search: `rg` (ripgrep).
- AST/structural search: `sg` (ast-grep) — preferred for code-aware queries (imports, call expressions, JSX/TSX nodes).
### AST-grep Usage (Windows)
- Announce intent and show the exact command before running complex patterns.
- Common queries:
- Find imports from `node:path` (TypeScript/TSX):
- `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx,mts,cts`
- Find CommonJS requires of `node:path`:
- `ast-grep -p "require('node:path')" src --lang js,cjs,mjs,ts,tsx`
- Suggest rewrite (do not auto-apply in code unless approved):
- Search: `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx`
- Proposed replacement: `import $$ from 'pathe'`
### Search Hygiene (fd/rg/sg)
- Exclude bulky folders to keep searches fast and relevant: `.git`, `node_modules`, `coverage`, `out`, `dist`.
- Prefer running searches against a scoped path (e.g., `src`) to implicitly avoid vendor and VCS directories.
- Examples:
- `rg -n "pattern" -g "!{.git,node_modules,coverage,out,dist}" src`
- `fd --hidden --exclude .git --exclude node_modules --exclude coverage --exclude out --exclude dist --type f ".tsx?$" src`
- ast-grep typically respects `.gitignore`; target `src` to avoid scanning vendor folders:
- `ast-grep -p "import $$ from '@shared/$$'" src --lang ts,tsx,mts,cts`
- If needed, add ignore patterns to your ignore files rather than disabling ignores.
System Notifications#
Codex supports executing custom events after task completion, and we can use this feature to implement Windows system pop-up notifications.
See Codex documentation https://github.com/openai/codex/blob/main/docs/config.md#notify
- ~/.codex/config.toml
notify = ["powershell.exe","-NoProfile","-ExecutionPolicy","Bypass","-File","C:\\Users\\<username>\\.codex\\notify.ps1"]
- ~/.codex/notify.ps1
param(
[Parameter(Mandatory = $true)]
[string]$json
)
# Parse JSON (Codex passes a segment of JSON as argv[1])
try {
$payload = $json | ConvertFrom-Json
} catch {
$payload = @{}
}
$title = 'Codex'
$msg = $payload.'last-assistant-message'
if (-not $msg) {
if ($payload.type) {
$msg = "Event: $($payload.type)"
} else {
$msg = 'Codex has an update.'
}
}
# Optional: truncate overly long text, note to only use ASCII ellipsis to avoid garbled text
if ($msg -and $msg.Length -gt 240) {
$msg = $msg.Substring(0,240) + '...'
}
# Only use Toast, do not use any Popup fallback
Import-Module BurntToast -ErrorAction Stop
New-BurntToastNotification -Text $title, $msg | Out-Null
Codex Prompt Debugging Tips#
After each modification of [AGENTS.md](http://AGENTS.md), frequently use ctrl+T to view its thought process, checking whether the command invocation and thought process meet your expectations. If not, directly converse with Codex to ask how to adjust AGENTS.md; repeating this several times usually yields satisfactory results.
[Start]
|
v
[Modify [`AGENTS.md`](http://AGENTS.md)]
|
v
[Ctrl+T View Current Thought Process/Trajectory]
|
v
{Does it meet your expectations?}
|Yes
v
[Submit/Apply Changes]───►(End or proceed to next task)
^
|No
|
v
[Talk to Codex: Ask how to adjust [`AGENTS.md`](http://AGENTS.md)]
|
v
[Modify [`AGENTS.md`](http://AGENTS.md) again based on suggestions]
|
└───────────────Loop back to───────────────┐
v
[Ctrl+T View Current Thought Process/Trajectory]
Spec-kit (Experimental)#
Imitating spec-kit, a set of specifications for implementing new features has been established, including three processes: spec, plan, and do.
It is still in the optimization phase, so instead of injecting instructions via codex/prompts.md, adjustments are made through AGENTS.md to continuously test. During conversations, simply input /spec, /plan, and /do.
- Start with /spec, input the functionality you want to achieve, and Codex will automatically generate a Markdown file in the specs folder.
- Start with /plan, and Codex will automatically generate a dated Markdown file in the plans folder.
- /do will automatically implement the tasks according to the plan.
There is no need to strictly follow the above three sequences; if the spec file does not meet expectations, you can continue conversing to adjust until satisfied, and then input /plan to guide the generation of the plan file.
## Stage-Gated Workflow (spec/plan/do)
- Mode: Opt-in. The workflow applies only when the user explicitly uses `/spec`, `/plan`, or `/do`. Routine Q&A or trivial edits do not require these stages.
- Triggers: A message containing one of `/spec`, `/plan`, or `/do` activates or advances the workflow. Once active, stages must proceed in order with explicit user approval to advance.
- Guardrails:
- Do not modify source code before `/do`. Documentation/spec files may be edited only in `/spec`.
- Do not skip stages or proceed without user confirmation once the workflow is active.
- If scope changes, return to the appropriate prior stage for approval.
- Respect sandbox/approval settings for all actions.
- When to Use
- Use the workflow for new features, structural refactors, multi-file changes, or work needing traceability.
- Skip the workflow (no triggers) for routine Q&A, diagnostics, or one-off trivial edits.
- Entry Points and Prerequisites
- `/spec` is the canonical entry point for new efforts.
- `/plan` requires an approved `/spec`. If unclear which spec applies, pause and ask the user to identify the correct file(s) under `specs/`.
- `/do` requires an approved `/plan`.
- `/spec` (Specifications; docs only)
- Purpose: Capture a concrete, reviewable specification using spec-kit style.
- Output: Markdown spec(s) under `specs/` (no code changes). Share a concise diff summary and links to updated files; wait for approval.
- Style: Specs are canonical and final. Do not include change logs or “correction” notes. Incorporate revisions directly so the document always reflects the current agreed state. Historical context belongs in PR descriptions, commit messages, or the conversation — not in the spec.
- Recommended contents:
- Problem statement and context
- Goals and non-goals
- Requirements and constraints (functional, UX, performance, security)
- UX/flows and API/IPC contracts (as applicable)
- Acceptance criteria and success metrics
- Alternatives considered and open questions
- Rollout/backout considerations and telemetry (if relevant)
- `/plan` (High-level Plan; docs only)
- Purpose: Turn the approved spec into an ordered, verifiable implementation plan.
- Inputs: Approved spec file(s) in `specs/`.
- Ambiguity: If the relevant spec is unclear, pause and request clarification before writing the plan.
- Style: Plans are canonical and should not include change logs or “correction” notes. Incorporate revisions directly so the plan always reflects the current agreed state. Historical notes should live in PR descriptions, commit messages, or the conversation.
- Output:
- An ordered plan via `update_plan` (short, verifiable steps; Task is merged into Plan and tracked here).
- A plan document in `plans/` named `YYYY-MM-DD-short-title.md`, containing:
- Scope and links to authoritative spec(s)
- Assumptions and out-of-scope items
- Phases/milestones mapped to acceptance criteria
- Impacted areas, dependencies, risks/mitigations
- Validation strategy (tests/lint/build) and rollout/backout notes
- Approval status and next stage
- Handoff: Await user approval of the plan before `/do`.
- `/do` (Execution)
- Purpose: Implement approved plan steps with minimal, focused changes and file operations.
- Actions:
- Use `apply_patch` for file edits; group related changes and keep diffs scoped to approved steps.
- Provide concise progress updates and a final summary of changes.
- Validate appropriately: run `pnpm lint`, `pnpm format`, `pnpm build`, and relevant tests.
- If material changes to the plan are needed, pause and return to `/plan` (or `/spec`) for approval.
- Output: Implemented changes, validation results, and a concise change summary linked to the plan checklist.
### Plans Directory
- Location: `plans/` at the repository root.
- Filename: `YYYY-MM-DD-short-title.md` (kebab-case title; consistent dating).
- Style: Plan docs are the canonical source of truth for the implementation approach; avoid embedding change logs or “correction” notes. Update the plan in place as decisions evolve.
- Contents:
- Title and summary
- Scope and linked specs (paths under `specs/`)
- Assumptions / Out of scope
- Step-by-step plan (short, verifiable)
- Validation strategy (tests/lint/build)
- Approval status and next stage
- Process:
- During `/plan`, create or update the relevant file in `plans/` and share a short summary in the conversation. Await approval before `/do`.
WSL2#
If you let Codex execute tasks under Windows, you will find that it often fails to call commands and retries, looping like this. Although it eventually succeeds, it wastes a lot of time. I personally speculate that this is due to the overwhelming amount of Unix Shell training data for GPT-5 compared to PowerShell, leading to hallucinations, as Codex subconsciously calls Unix Shell commands to handle tasks.
So is there a way to solve this? Of course! If you can't beat them, join them—WSL2.
For example, in Windows 11, execute wsl --install in PowerShell to install WSL2.
In this case, there are two options to choose from:
- Windows-side code + WSL2 Codex environment, suitable for developing Windows-side programs, such as Electron Windows, .NET, etc.
- WSL2 code + WSL2 Codex environment, such as Vue Web development.
For the latter, everything can run normally in the WSL2 environment, so no further explanation is needed. However, for the former, mixing Windows + WSL2 requires solving one problem: how to call Windows-side npm/pnpm in WSL2 to execute defined pnpm typecheck, pnpm lint:fix, etc.
When conversing with Codex in WSL2, you need to ask it to call pwsh.exe to execute pnpm typecheck for checking, like this.
we're in WSL2, please using pwsh.exe to run `pnpm <script>`
Complete AGENTS.md#
Still adjusting, do not copy it entirely; it is best to view the entire process through ctrl+T. If you encounter commands that Codex often gets wrong, selectively modify and delete to suit your own AGENTS.md.
Main adaptations:
- Windows/WSL2 support, prioritize using commands supported by PowerShell, and for any npm package installation, user confirmation is required to avoid chaotic dependencies.
- Use fd, ripgrep, ast-grep to search for files, text, and code snippets, faster and more direct.
- spec/plan/do workflow, first determine specifications, then write plans, and finally implement.
# AGENTS Guidelines
## Windows Environment Notice
- Prefer PowerShell (`pwsh`/`powershell`) when on Windows.
- Prefer using pwsh.exe to run `pnpm <script>` when on WSL2.
- WSL2 may be used for non-package-manager commands only (e.g., `rg`, `tar`). Avoid running Node builds in WSL due to OS mismatch.
- WSL2 cross-drive performance: accessing repos under `/mnt/c|d|e/...` goes through a filesystem bridge and can be slower for full scans. Prefer scoping to subtrees, excluding heavy folders, or running the same searches with native Windows binaries in PowerShell for large/iterative scans.
- Do not auto-run dependency installs. The user must run `pnpm install` in Windows PowerShell manually and then confirm completion.
- Do not modify `package.json`/lockfiles to add or update dependencies without explicit user approval. Propose dependencies in `/spec` or `/plan`, and ask the user to run `pnpm add <pkg>` (or `pnpm install`) and confirm.
- Do not call Unix text tools directly in PowerShell (e.g., `sed`, `awk`, `cut`, `head`, `tail`). Use PowerShell-native equivalents instead:
- `head` → `Select-Object -First N`
- `tail` → `Get-Content -Tail N`
- paging → `Out-Host -Paging` or `more`
- substitution/replace → `-replace` with `Get-Content`/`Set-Content`
## Tool Priority
- Filename search: `fd`.
- Text/content search: `rg` (ripgrep).
- AST/structural search: `sg` (ast-grep) — preferred for code-aware queries (imports, call expressions, JSX/TSX nodes).
### AST-grep Usage
- Announce intent and show the exact command before running complex patterns.
- Common queries:
- Find imports from `node:path` (TypeScript/TSX):
- `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx,mts,cts`
- Find CommonJS requires of `node:path`:
- `ast-grep -p "require('node:path')" src --lang js,cjs,mjs,ts,tsx`
- Suggest rewrite (do not auto-apply in code unless approved):
- Search: `ast-grep -p "import $$ from 'node:path'" src --lang ts,tsx`
- Proposed replacement: `import $$ from 'pathe'`
### Search Hygiene (fd/rg/sg)
- Exclude bulky folders to keep searches fast and relevant: `.git`, `node_modules`, `coverage`, `out`, `dist`.
- Prefer running searches against a scoped path (e.g., `src`) to implicitly avoid vendor and VCS directories.
- Examples:
- `rg -n "pattern" -g "!{.git,node_modules,coverage,out,dist}" src`
- `fd --hidden --exclude .git --exclude node_modules --exclude coverage --exclude out --exclude dist --type f ".tsx?$" src`
- ast-grep typically respects `.gitignore`; target `src` to avoid scanning vendor folders:
- `ast-grep -p "import $$ from '@shared/$$'" src --lang ts,tsx,mts,cts`
- If needed, add ignore patterns to your ignore files rather than disabling ignores.
## Temporary Research Files
- Canonical location: store all temporary research artifacts (downloaded READMEs, API docs, scratch notes) under `docs/research/`.
- Do not place temporary files at the repository root or outside `docs/research/`.
- Commit policy: avoid committing temporary files unless they are necessary for traceability during `/spec` or `/plan`. If committed, keep the scope minimal and store them under `docs/` only.
- Naming: use descriptive names with date or task context (e.g., `docs/research/2025-09-11-wsl-notes.md`).
- Cleanup: after completing a task (`/do`), evaluate whether each temporary file is still required. Remove unneeded files, or promote essential content into curated docs under `docs/` or into `specs/`/`plans/`.
## Stage-Gated Workflow (spec/plan/do)
- Mode: Opt-in. The workflow applies only when the user explicitly uses `/spec`, `/plan`, or `/do`. Routine Q&A or trivial edits do not require these stages.
- Triggers: A message containing one of `/spec`, `/plan`, or `/do` activates or advances the workflow. Once active, stages must proceed in order with explicit user approval to advance.
- Guardrails:
- Do not modify source code before `/do`. Documentation/spec files may be edited only in `/spec`.
- Do not skip stages or proceed without user confirmation once the workflow is active.
- If scope changes, return to the appropriate prior stage for approval.
- Respect sandbox/approval settings for all actions.
- When to Use
- Use the workflow for new features, structural refactors, multi-file changes, or work needing traceability.
- Skip the workflow (no triggers) for routine Q&A, diagnostics, or one-off trivial edits.
- Entry Points and Prerequisites
- `/spec` is the canonical entry point for new efforts.
- `/plan` requires an approved `/spec`. If unclear which spec applies, pause and ask the user to identify the correct file(s) under `specs/`.
- `/do` requires an approved `/plan`.
- `/spec` (Specifications; docs only)
- Purpose: Capture a concrete, reviewable specification using spec-kit style.
- Output: Markdown spec(s) under `specs/` (no code changes). Share a concise diff summary and links to updated files; wait for approval.
- Style: Specs are canonical and final. Do not include change logs or “correction” notes. Incorporate revisions directly so the document always reflects the current agreed state. Historical context belongs in PR descriptions, commit messages, or the conversation — not in the spec.
- Recommended contents:
- Problem statement and context
- Goals and non-goals
- Requirements and constraints (functional, UX, performance, security)
- UX/flows and API/IPC contracts (as applicable)
- Acceptance criteria and success metrics
- Alternatives considered and open questions
- Rollout/backout considerations and telemetry (if relevant)
- `/plan` (High-level Plan; docs only)
- Purpose: Turn the approved spec into an ordered, verifiable implementation plan.
- Inputs: Approved spec file(s) in `specs/`.
- Ambiguity: If the relevant spec is unclear, pause and request clarification before writing the plan.
- Style: Plans are canonical and should not include change logs or “correction” notes. Incorporate revisions directly so the plan always reflects the current agreed state. Historical notes should live in PR descriptions, commit messages, or the conversation.
- Output:
- An ordered plan via `update_plan` (short, verifiable steps; Task is merged into Plan and tracked here).
- A plan document in `plans/` named `YYYY-MM-DD-short-title.md`, containing:
- Scope and links to authoritative spec(s)
- Assumptions and out-of-scope items
- Phases/milestones mapped to acceptance criteria
- Impacted areas, dependencies, risks/mitigations
- Validation strategy (tests/lint/build) and rollout/backout notes
- Approval status and next stage
- Handoff: Await user approval of the plan before `/do`.
- `/do` (Execution)
- Purpose: Implement approved plan steps with minimal, focused changes and file operations.
- Actions:
- Use `apply_patch` for file edits; group related changes and keep diffs scoped to approved steps.
- Provide concise progress updates and a final summary of changes.
- Validate appropriately: run `pnpm lint`, `pnpm format`, `pnpm build`, and relevant tests.
- If material changes to the plan are needed, pause and return to `/plan` (or `/spec`) for approval.
- Output: Implemented changes, validation results, and a concise change summary linked to the plan checklist.
### Plans Directory
- Location: `plans/` at the repository root.
- Filename: `YYYY-MM-DD-short-title.md` (kebab-case title; consistent dating).
- Style: Plan docs are the canonical source of truth for the implementation approach; avoid embedding change logs or “correction” notes. Update the plan in place as decisions evolve.
- Contents:
- Title and summary
- Scope and linked specs (paths under `specs/`)
- Assumptions / Out of scope
- Step-by-step plan (short, verifiable)
- Validation strategy (tests/lint/build)
- Approval status and next stage
- Process:
- During `/plan`, create or update the relevant file in `plans/` and share a short summary in the conversation. Await approval before `/do`.
Tips#
- Proactively let Codex call specific tools: Do not write all considerations into AGENTS.md; users will also need to bear some mental load to guide Codex to use more suitable tools for different scenarios, such as using
git diffwhich may provide more accurate context. - Provide complete information sources during conversations as much as possible: Codex's method of searching for code is very primitive, like grep, ripgrep, etc., and it may not find what you want. For example, if you want to ask why something was instantiated twice, provide the places where it appeared twice: function, filename, etc., to reduce Codex's misjudgment or search time. Codex provides the
@shortcut command to help you quickly search for filenames. - For web searches, try to use the web version of ChatGPT-5-Thinking: Searches are faster and more complete, especially adept at retrieving GitHub projects: including but not limited to source code, project structure, issues, PRs, etc. It is particularly suitable for understanding the functionality of an open-source project; opening a long conversation with ChatGPT can be very beneficial.
Summary#
AI tools are evolving rapidly, and with the rise of a new tool, do not expect to master it in three minutes, nor should you overly rely on others' blog documents and conclusions. AI tools are unique to each individual, and everyone has their own programming habits. It takes a few days to slowly understand the tool's characteristics and the habits of the underlying large language model, and to tune the AI tool that is uniquely yours according to your needs and preferences.
When facing new things, do not get stuck on one tool; maintain curiosity and be brave to explore the unknown possibilities.