1# Codex Tool Mapping
2 
3Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Codex these resolve to the tools below.
4 
5| Action skills request | Codex equivalent |
6|----------------------|------------------|
7| Read a file | `shell` (e.g., `cat`, `head`, `tail`) — Codex reads files via shell |
8| Create / edit / delete a file | `apply_patch` (structured diff for create, update, delete) |
9| Run a shell command | `shell` |
10| Search file contents | `shell` (e.g., `grep`, `rg`) |
11| Find files by name | `shell` (e.g., `find`, `ls`) |
12| Fetch a URL | `shell` with `curl` / `wget` — Codex has no native fetch tool |
13| Search the web | `web_search` (enabled by default; configurable in `config.toml` via the top-level `web_search` setting — `live`, `cached`, or `disabled`) |
14| Invoke a skill | Skills load natively — just follow the instructions |
15| Dispatch a subagent (`Subagent (general-purpose):` template) | `spawn_agent` (see [Subagent dispatch requires multi-agent support](#subagent-dispatch-requires-multi-agent-support)) |
16| Multiple parallel dispatches | Multiple `spawn_agent` calls in one response |
17| Wait for subagent result | `wait_agent` |
18| Free up subagent slot when done | `close_agent` |
19| Task tracking ("create a todo", "mark complete") | `update_plan` |
20 
21## Instructions file
22 
23When a skill mentions "your instructions file", on Codex this is **`AGENTS.md`** at the project root. Codex also reads `~/.codex/AGENTS.md` for global context, and an `AGENTS.override.md` (in the project tree or `~/.codex/`) takes precedence when present. Codex walks from the project root down to the current working directory, concatenating `AGENTS.md` files it finds along the way, up to `project_doc_max_bytes` (32 KiB by default).
24 
25## Personal skills directory
26 
27User-level skills live at **`$CODEX_HOME/skills/`** (default `~/.codex/skills/`). Codex also reads the cross-runtime path **`~/.agents/skills/`** (shared with Copilot CLI and Gemini CLI). When both directories exist at the same scope, Codex loads them both as separate skill catalogs — Codex's docs don't currently document a precedence between them. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
28 
29## Subagent dispatch requires multi-agent support
30 
31Add to your Codex config (`~/.codex/config.toml`):
32 
33```toml
34[features]
35multi_agent = true
36```
37 
38This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
39 
40Legacy note: Codex builds before `rust-v0.115.0` exposed spawned-agent
41waiting as `wait`. Current Codex uses `wait_agent` for spawned agents. The
42`wait` name now belongs to code-mode `exec/wait`, which resumes a yielded exec
43cell by `cell_id`; it is not the spawned-agent result tool.
44 
45## Environment Detection
46 
47Skills that create worktrees or finish branches should detect their
48environment with read-only git commands before proceeding:
49 
50```bash
51GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
52GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
53BRANCH=$(git branch --show-current)
54```
55 
56- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
57- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
58 
59See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
60Step 1 for how each skill uses these signals.
61 
62## Codex App Finishing
63 
64When the sandbox blocks branch/push operations (detached HEAD in an
65externally managed worktree), the agent commits all work and informs
66the user to use the App's native controls:
67 
68- **"Create branch"** — names the branch, then commit/push/PR via App UI
69- **"Hand off to local"** — transfers work to the user's local checkout
70 
71The agent can still run tests, stage files, and output suggested branch
72names, commit messages, and PR descriptions for the user to copy.
73