smolkik_adm/My-Brain-Is-Full-Crew
1
0
Fork 0
mirror of https://github.com/gnekt/My-Brain-Is-Full-Crew.git synced 2026-08-26 10:05:37 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
1b9450aa030481f1436a8824ae2a3742e863446a
My-Brain-Is-Full-Crew/docs/codex-cli.md
gnekt 1b9450aa03 fix: review corrections for Codex CLI adapter (PR #35) 
Great work on the Codex CLI integration, thanks for putting this together!
After reviewing the PR against the actual Codex CLI docs and source code,
I found a few things that needed fixing. Here is what changed and why.

## request_user_input is a real Codex CLI tool

The adapter was removing `request_user_input` and replacing it with "ask
the user directly in chat". But `request_user_input` is a native Codex CLI
tool (like `shell` or `spawn_agent`). The fix: `AskUserQuestion` now maps
to `request_user_input` instead of being erased, and `request_user_input`
is preserved everywhere (adapter, docs, compat reference, tests).

## Fictional model names replaced with real ones

The config profiles used `gpt-5.4`, `gpt-5.4-mini`, and
`gpt-5.3-codex-spark`, which do not exist. Replaced with `o3` and
`o4-mini`, which are the current production models for Codex CLI.

## TOML key quoting (security)

`_cc_toml_quote_key` was sanitizing server names by replacing spaces with
hyphens (`Google Calendar` -> `Google-Calendar`). This broke cross-platform
parity because `mcp/servers.yaml` is the source of truth for all platforms.
The fix: the function now properly quotes keys per TOML spec when they
contain spaces or special characters, so `Google Calendar` stays as-is in
YAML and becomes `[mcp_servers."Google Calendar"]` in TOML output.

## servers.yaml breaking change reverted

The PR renamed `Google Calendar` to `Google-Calendar` in servers.yaml.
Since this file feeds all four platform adapters, that rename would break
Claude Code, Gemini CLI, and OpenCode builds. Reverted.

## TOML agent schema in migration doc was wrong

The example in codex-migration.md used a nested `[agent]` /
`[agent.prompt].content` structure. Codex CLI actually uses top-level keys:
`name`, `description`, `developer_instructions`. Fixed the example.

## Security hardening

- Path traversal guard on agent names: rejects `/` and `..` sequences
- Control character rejection in TOML key quoting (newline/CR/tab)
- Newline and tab escaping in all three TOML string escape functions
- Fixed glob expansion risk in `_cc_capabilities_to_sandbox` (now uses
  `read -ra` array instead of unquoted word splitting)

## Docs and smoke matrix

- codex-cli.md: fixed tool mapping table, replaced `@Agent` syntax with
  natural language prompts (Codex CLI does not support @ mentions), added
  note about dispatcher routing
- codex-cli-compat.md: added Read/Glob/Grep/Bash tool mappings
- README.md: added codex-cli adapter and docs to the project structure tree

## Test updates

- ~15 tests updated to match the new semantics (request_user_input
  preserved, model names, POSIX find instead of GNU -printf)
- 119/123 tests pass; the 4 remaining failures are pre-existing (bash 3.2
  on macOS lacks `mapfile` and `declare -A`)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-12 21:25:12 +02:00

225 lines
11 KiB
Markdown
Raw Blame History

# 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).
Reference in New Issue View Git Blame Copy Permalink