superpowers/skills/using-superpowers/references/codex-tools.md

Codex Tool Mapping

Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Codex these resolve to the tools below.

Action skills request	Codex equivalent
Read a file	shell (e.g., cat, head, tail) — Codex reads files via shell
Create / edit / delete a file	apply_patch (structured diff for create, update, delete)
Run a shell command	shell
Search file contents	shell (e.g., grep, rg)
Find files by name	shell (e.g., find, ls)
Fetch a URL	shell with curl / wget — Codex has no native fetch tool
Search the web	web_search (enabled by default; configurable in config.toml via the top-level web_search setting — live, cached, or disabled)
Invoke a skill	Skills load natively — just follow the instructions
Dispatch a subagent (Subagent (general-purpose): template)	spawn_agent (see Subagent dispatch requires multi-agent support)
Multiple parallel dispatches	Multiple spawn_agent calls in one response
Wait for subagent result	wait_agent
Free up subagent slot when done	close_agent
Task tracking ("create a todo", "mark complete")	update_plan

Subagent dispatch requires multi-agent support

Add to your Codex config (~/.codex/config.toml):

[features]
multi_agent = true

This enables spawn_agent, wait_agent, and close_agent for skills like dispatching-parallel-agents and subagent-driven-development.

Environment Detection

Skills that create worktrees or finish branches should detect their environment with read-only git commands before proceeding:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

• GIT_DIR != GIT_COMMON → already in a linked worktree (skip creation)
• BRANCH empty → detached HEAD (cannot branch/push/PR from sandbox)

See using-git-worktrees Step 0 and finishing-a-development-branch Step 1 for how each skill uses these signals.

Codex App Finishing

When the sandbox blocks branch/push operations (detached HEAD in an externally managed worktree), the agent commits all work and informs the user to use the App's native controls:

• "Create branch" — names the branch, then commit/push/PR via App UI
• "Hand off to local" — transfers work to the user's local checkout

The agent can still run tests, stage files, and output suggested branch names, commit messages, and PR descriptions for the user to copy.