---
load_when: platform is Codex, or multi-platform tool name translation is needed
---

# codex-tools.md — Cross-Platform Tool Name Matrix

This reference maps the Codebase Wizard's tool names across all four supported
platforms. Load this file when:
- Generating platform-specific install instructions
- Translating agent manifests for non-Claude Code targets
- Explaining tool differences to users on Codex or other platforms

---

## Why This Mapping Exists

Each CLI platform invented its own tool naming convention before any cross-tool
standard existed:

- **Claude Code** uses PascalCase (`Read`, `Write`, `Bash`)
- **OpenCode** uses lowercase (`read`, `write`, `bash`)
- **Gemini CLI** uses snake_case (`read_file`, `write_file`, `run_shell_command`)
- **Codex** uses its own naming — see the full matrix below

The wizard's `SKILL.md`, `agents/codebase-wizard-agent.md`, and all command
files are written in Claude Code PascalCase as the canonical form. When
adapting for other platforms, use this table to translate.

---

## Full 4-Platform Tool Name Matrix

| Claude Code | OpenCode | Gemini CLI | Codex |
|-------------|----------|------------|-------|
| `Read` | `read` | `read_file` | `file_read` |
| `Write` | `write` | `write_file` | `file_write` |
| `Edit` | `edit` | `replace` | `file_edit` |
| `Bash` | `bash` | `run_shell_command` | `shell` |
| `Grep` | `grep` | `search_file_content` | `grep_search` |
| `Glob` | `glob` | `glob` | `file_glob` |
| `WebSearch` | `websearch` | `google_web_search` | `web_search` |
| `WebFetch` | `webfetch` | `web_fetch` | `web_fetch` |

---

## Platform Conventions at a Glance

| Platform | Naming Style | Config Dir | Hook Support |
|----------|-------------|------------|-------------|
| Claude Code | PascalCase | `~/.claude/` | Yes (Agent Rulez) |
| OpenCode | lowercase | `~/.config/opencode/` | Yes |
| Gemini CLI | snake_case | `~/.gemini/` | Yes |
| Codex | mixed (see table) | `~/.codex/` | **No** |

---

## Codex: No Hook Support

Codex has no hook mechanism. This affects the Codebase Wizard in two ways:

### 1. Automatic Session Capture Does Not Work

On Claude Code, OpenCode, and Gemini CLI, Agent Rulez hooks fire
`PostToolUse` to append each Q&A turn to the session JSON automatically.
On Codex, this mechanism does not exist.

### Manual Export Instruction for Codex Users

At the end of every Codebase Wizard session on Codex, users must manually
trigger export:

> **Codex users:** After your wizard session ends, run:
> ```
> /codebase-wizard-export --latest
> ```
> This generates `SESSION-TRANSCRIPT.md` and the mode-specific doc
> (`CODEBASE.md`, `TOUR.md`, or `FILE-NOTES.md`) in
> `{resolved_storage}/docs/{session_id}/`.
>
> Without this step, your session content will not be persisted to disk.

This instruction is also printed by `AGENTS.md` (the Codex instruction file
generated by `setup.sh codex`).

### 2. Setup Skips Hook Installation (Exit 77)

When `setup.sh` is run with the `codex` runtime argument, it detects the
lack of hook support and exits the hook installation step with code 77.

Exit code 77 is the conventional "skip" code for unsupported scenarios in
multi-platform install scripts. It is not an error — it signals that hook
setup was intentionally skipped because the platform does not support it.

When `setup.sh all` runs, it catches exit 77 from the Codex branch and
continues without failing the overall install.

---

## Translation Notes

### `Edit` vs `replace` vs `file_edit`

All three tools perform in-place file modification, but their interfaces differ:
- Claude Code `Edit`: `old_string` / `new_string` with exact match
- Gemini `replace`: similar semantics, different parameter names
- Codex `file_edit`: may use line-range semantics on some versions

When adapting wizard commands for Gemini or Codex, verify the parameter
contract for `Edit` / `replace` / `file_edit` against the current platform docs.

### `WebSearch` vs `google_web_search` vs `web_search`

Gemini's `google_web_search` is backed by Google Search. OpenCode's
`websearch` and Codex's `web_search` may use different providers. The wizard's
research priority logic (Agent Brain → Perplexity → web search → codebase scan)
applies regardless of which tool name is in use on the current platform.

### `Bash` vs `shell`

Codex's `shell` tool may have different sandboxing behavior than Claude Code's
`Bash`. On Codex, test that `node*`, `grep*`, `find*`, `cat*`, `ls*`, and
`rulez*` are permitted under the equivalent Codex tool before deploying.
