# Codex CLI Guide

This guide covers everything you need to install, update, and run My Brain Is Full — Crew on [Codex CLI](https://openai.com/codex) (`@openai/codex`).

> **Windows note:** Codex CLI's Windows support is experimental. If you are on Windows, running inside WSL (Windows Subsystem for Linux) is strongly recommended.

---

## Install and update commands

### First-time install

```bash
# Install Codex CLI globally
npm i -g @openai/codex@latest

# Clone the repo inside your vault and install the Crew
cd /path/to/your-vault
git clone https://github.com/gnekt/My-Brain-Is-Full-Crew.git
cd My-Brain-Is-Full-Crew
bash scripts/launchme.sh --platform codex-cli
```

The installer accepts an optional `--target` flag if you want to point it at a vault in a non-standard location:

```bash
bash scripts/launchme.sh --platform codex-cli --target /path/to/your-vault
```

### Update after a git pull

```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
bash scripts/updateme.sh --platform codex-cli
```

The updater auto-detects Codex CLI by checking for `.codex/agents` in your vault. If multiple platforms are installed, pass `--platform codex-cli` explicitly.

---

## What installs where

After running `launchme.sh --platform codex-cli`, your vault will contain:

```
your-vault/
├── .codex/
│   ├── agents/          ← 8 core crew agents (.toml format)
│   ├── references/      ← shared docs the agents read
│   └── config.toml      ← MCP server definitions + profiles + sandbox policy
├── .agents/
│   └── skills/          ← 14 specialized skills (plain text instructions)
├── Meta/
│   └── scripts/         ← orchestra scripts (permission-free agent commands)
└── AGENTS.md            ← dispatcher (project instructions for Codex)
```

Key differences from other platforms:

| Path | Purpose |
|------|---------|
| `.codex/agents/*.toml` | Custom agent definitions (Codex native format) |
| `.agents/skills/` | Repo-scoped skill instructions (shared discovery path) |
| `.codex/config.toml` | MCP servers, approval policy, sandbox mode, model profiles |
| `AGENTS.md` | Dispatcher — Codex reads this as its primary project instruction file |

---

## Architecture differences from Claude Code, Gemini CLI, and OpenCode

### Dispatcher

All platforms use a dispatcher file, but the name and format differ:

| Platform | Dispatcher file |
|----------|----------------|
| Claude Code | `CLAUDE.md` |
| Gemini CLI | `GEMINI.md` |
| OpenCode | `AGENTS.md` |
| Codex CLI | `AGENTS.md` (with root-context routing header) |

Codex CLI shares the `AGENTS.md` name with OpenCode but prepends a routing header that handles orchestration within the `agents.max_depth = 1` constraint (see below).

### Agent format

Claude Code, Gemini CLI, and OpenCode all use Markdown (`.md`) agent files. Codex CLI uses TOML:

```
.claude/agents/architect.md        ← Claude Code
.gemini/agents/architect.md        ← Gemini CLI
.opencode/agents/architect.md      ← OpenCode
.codex/agents/architect.toml       ← Codex CLI
```

### Skills location

Skills install to `.agents/skills/` for Codex (not `.codex/skills/`). Codex CLI discovers skills from this shared path.

### Agent chaining (max_depth constraint)

Codex CLI enforces `agents.max_depth = 1`. This means child agents can only go one level deep. My Brain Is Full — Crew handles this through root-context orchestration:

- The dispatcher embeds orchestration instructions in the root context (not in a child)
- Child agents (`spawn_agent`) finish one bounded task and return to root
- Any next step is decided from the root context, not by a nested child

### Tool name differences

Codex CLI has its own tool set. Some Claude Code tools do not exist in Codex; others have native equivalents. `request_user_input` is a real Codex CLI tool — use it directly for follow-up questions.

| Source concept | Codex CLI equivalent |
|---|---|
| `AskUserQuestion` | `request_user_input` (native Codex tool) — ask a follow-up question and wait for the reply |
| `request_user_input` | Same tool name exists natively in Codex CLI — no translation needed |
| `Skill tool` | Follow the skill instructions directly in the root context |
| `Agent tool` | Use `spawn_agent` for a bounded child task; orchestration returns to root |
| `Read tool` | `shell` (e.g. `cat`) — Codex has no dedicated read_file tool |
| `Glob tool` / `Grep tool` | `shell` (e.g. `find`, `grep`) or `list_dir` (experimental) |
| `Bash tool` | `shell` — execute shell commands |
| `max chain depth 3` | `agents.max_depth = 1` with root-only orchestration |
| `.mcp.json` | `.codex/config.toml` |

### MCP configuration

Claude Code uses `.mcp.json`. Codex CLI uses `.codex/config.toml`. The MCP server, approval policy, sandbox mode, and model profile settings all live in the TOML config. The CLI and Codex IDE extension share this same config file.

---

## Runtime smoke matrix

Use this table to verify the Crew works correctly in a real Codex vault after install or update. Run each row and compare the result against the expected outcome.

> **Note:** Use natural-language prompts. The dispatcher in `AGENTS.md` routes to the correct agent based on intent — you do not need to address agents by name.

| Surface | Name | Prompt or command | Expected result |
|---------|------|-------------------|----------------|
| Agent | Architect | `Set up my vault structure` | Architect starts onboarding conversation or confirms vault is already set up |
| Agent | Scribe | `Save this note: quick test` | Scribe creates a note in 00-Inbox with proper frontmatter |
| Agent | Sorter | `Batch sort my inbox` | Sorter reviews inbox notes and files them, or reports inbox is empty |
| Agent | Seeker | `What do I know about this project?` | Seeker searches the vault and returns results with source citations |
| Agent | Connector | `Find connections in my recent notes` | Connector analyzes the vault graph and suggests wikilinks |
| Agent | Librarian | `Run a vault health check` | Librarian scans for broken links, duplicates, and orphan notes |
| Agent | Transcriber | `Process this transcript: [paste text]` | Transcriber generates structured meeting notes |
| Agent | Postman | `Check my email` | Postman scans Gmail (or Hey) and saves actionable emails, or reports missing integration |
| Skill | onboarding | `Initialize my vault` | Architect starts the full onboarding conversation |
| Skill | create-agent | `Create a new agent` | Architect walks through designing a new custom agent |
| Skill | manage-agent | `List my agents` | Architect lists, edits, or removes custom agents |
| Skill | defrag | `Defragment the vault` | Architect runs the 5-phase vault defragmentation |
| Skill | email-triage | `What's in my inbox?` (email) | Postman scans and prioritizes unread emails |
| Skill | meeting-prep | `Prepare for the meeting` | Postman generates a comprehensive meeting brief |
| Skill | weekly-agenda | `What's this week?` | Postman produces a day-by-day week overview |
| Skill | deadline-radar | `What are my deadlines?` | Postman produces a unified deadline timeline |
| Skill | transcribe | `Transcribe this recording` | Transcriber processes a recording or transcript into structured notes |
| Skill | vault-audit | `Weekly review` | Librarian runs the full 7-phase vault audit |
| Skill | deep-clean | `Deep clean the vault` | Librarian runs the extended vault cleanup |
| Skill | tag-garden | `Clean up tags` | Librarian analyzes and cleans up tags |
| Skill | inbox-triage | `Triage the inbox` | Sorter processes and routes all inbox notes |
| Skill | contact-sync | `Sync my contacts` | Postman syncs contacts to Apple Contacts |
| Chaining | bounded child-agent chain | `Batch sort my inbox` (with notes mentioning a new project) | Sorter files notes, then dispatcher signals Architect to create the new project folder; child returns to root before Architect runs |
| MCP | MCP visibility | `codex -C <vault> mcp list` | Lists the MCP servers configured in `.codex/config.toml`, or shows the auth/setup state for each server |

### Running the non-interactive discovery smoke

```bash
codex exec -C <vault> "List the project custom agents under .codex/agents, the repo skills under .agents/skills, and the dispatcher file used in this workspace."
```

Expected output references:
- `AGENTS.md` (the dispatcher)
- `.codex/agents` path (custom agents)
- `.agents/skills` path (repo skills)

### Running the MCP visibility smoke

```bash
codex -C <vault> mcp list
```

Expected: lists MCP servers from `.codex/config.toml` (e.g., `Gmail`, `Calendar`) or shows their auth/setup state.

---

## Troubleshooting

### Agents are not discovered

- Verify `.codex/agents/` exists in your vault root and contains `.toml` files.
- Open Codex CLI from your vault directory: `codex -C /path/to/your-vault`
- Check that `AGENTS.md` exists at the vault root (not inside the repo subdirectory).

### Skills are not available

- Verify `.agents/skills/` exists in your vault root and contains subdirectories.
- Skills must be at the vault root level: `<vault>/.agents/skills/<skill-name>/`

### Child agent chain does not return to root

- This is a Codex `agents.max_depth = 1` constraint. Child agents can only go one level deep.
- The dispatcher uses root-context orchestration to work within this constraint.
- If a task seems to require deeper nesting, flatten it: complete the first bounded step in a child, then handle the next step in the root context.

### MCP server not connecting

- MCP configuration lives in `.codex/config.toml` (not `.mcp.json`).
- Check `codex -C <vault> mcp list` to see the current server status.
- For Gmail/Calendar setup, see `docs/gws-setup-guide.md`.
- For Apple Contacts, verify the `apple-contacts` server entry in `.codex/config.toml`.

### Codex errors about approvals

- Child agent approvals surface in the child thread. Approve or deny there, then continue orchestration from the root context after the child returns.
- If a task requires deeper recursion, stop spawning children and flatten the next step into the root context or split the work into separate bounded child tasks.

### Windows users

Codex CLI's Windows support is experimental. Use WSL (Windows Subsystem for Linux) for the most reliable experience. From WSL, follow the standard Linux install path above.

### Reinstall vs update

- **Reinstall** (`launchme.sh`): Use when setting up a new vault or recovering from a broken state.
- **Update** (`updateme.sh`): Use after `git pull` to push new agents, skills, and references to an existing vault. Custom agents are never overwritten.

For a migration from another platform, see [docs/codex-migration.md](codex-migration.md).