My-Brain-Is-Full-Crew/docs/codex-cli.md

Codex CLI Guide

This guide covers everything you need to install, update, and run My Brain Is Full — Crew on Codex CLI (@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

# 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 scripts/launchme.sh --platform codex-cli --target /path/to/your-vault

Update after a git pull

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

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

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.