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-27 02:25:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex-cli-integration
My-Brain-Is-Full-Crew/docs/codex-migration.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

176 lines
7.8 KiB
Markdown
Raw Permalink Blame History

# Migrating to Codex CLI
This guide covers how to move an existing My Brain Is Full — Crew installation from Claude Code, Gemini CLI, or OpenCode to Codex CLI. It also explains what transfers automatically and what needs manual attention.
> **If you are doing a fresh install** (not migrating), follow [docs/codex-cli.md](codex-cli.md) instead.
---
## When to reinstall vs update
| Scenario | Recommended action |
|----------|-------------------|
| You have an existing Claude Code / Gemini CLI / OpenCode vault and want to add Codex CLI alongside it | Run `bash scripts/launchme.sh --platform codex-cli` in the same vault — multiple platforms can coexist |
| You want to switch exclusively to Codex CLI | Run `launchme.sh --platform codex-cli`; the other platform files remain but are inactive |
| Your Codex layout is broken or missing files | Run `launchme.sh --platform codex-cli` again — it is idempotent and safe to re-run |
| You pulled new repo changes and want to update Codex | Run `bash scripts/updateme.sh --platform codex-cli` |
You do not need to remove other platform directories. Codex CLI only reads `.codex/` and `.agents/skills/`; it ignores `.claude/`, `.gemini/`, and `.opencode/`.
---
## Path mapping by platform
When you switch to Codex CLI, the project files move to new paths. Use this table to locate your existing files and understand where the equivalent lives in Codex.
| Source platform | Dispatcher | Agents | Skills | MCP or config | Codex target |
|----------------|-----------|--------|--------|--------------|-------------|
| Claude Code | `CLAUDE.md` | `.claude/agents/*.md` | `.claude/skills/` | `.mcp.json` | `AGENTS.md` / `.codex/agents/*.toml` / `.agents/skills/` / `.codex/config.toml` |
| Gemini CLI | `GEMINI.md` | `.gemini/agents/*.md` | `.gemini/skills/` | (none) | `AGENTS.md` / `.codex/agents/*.toml` / `.agents/skills/` / `.codex/config.toml` |
| OpenCode | `AGENTS.md` | `.opencode/agents/*.md` | `.opencode/skills/` | `opencode.json` | `AGENTS.md` / `.codex/agents/*.toml` / `.agents/skills/` / `.codex/config.toml` |
After running `launchme.sh --platform codex-cli`, the Codex files are installed automatically. You do not need to copy the old platform files manually.
---
## Moving from Claude Code
1. Pull the latest repo changes:
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
```
2. Run the Codex installer:
```bash
bash scripts/launchme.sh --platform codex-cli
```
3. The installer creates:
- `.codex/agents/` — all 8 core agents in TOML format
- `.agents/skills/` — all 14 skills as plain text instructions
- `.codex/config.toml` — MCP servers (translated from `mcp/servers.yaml`)
- `AGENTS.md` — dispatcher with Codex routing header
4. Your existing `.claude/` directory and `CLAUDE.md` are left untouched.
5. MCP configuration: Claude Code uses `.mcp.json`. Codex CLI uses `.codex/config.toml`. If you added custom MCP servers to `.mcp.json` manually, you will need to add them to `.codex/config.toml` as well. See the `[mcp_servers.*]` TOML table format.
6. Custom agents: Claude Code custom agents live in `.claude/agents/`. Codex CLI custom agents must be in `.toml` format in `.codex/agents/`. Custom agents created via the `/create-agent` skill are not automatically migrated — see [Custom agents and what does not migrate automatically](#custom-agents-and-what-does-not-migrate-automatically).
---
## Moving from Gemini CLI
1. Pull the latest repo changes:
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
```
2. Run the Codex installer:
```bash
bash scripts/launchme.sh --platform codex-cli
```
3. The installer creates the full Codex layout (same as above).
4. Your existing `.gemini/` directory and `GEMINI.md` are left untouched.
5. MCP configuration: Gemini CLI does not use `.mcp.json`. If you have MCP servers configured elsewhere, add them to `.codex/config.toml` manually.
6. Custom agents: Gemini CLI custom agents live in `.gemini/agents/`. These are Markdown files. For Codex CLI, custom agents must be TOML files in `.codex/agents/`. See [Custom agents and what does not migrate automatically](#custom-agents-and-what-does-not-migrate-automatically).
---
## Moving from OpenCode
1. Pull the latest repo changes:
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
```
2. Run the Codex installer:
```bash
bash scripts/launchme.sh --platform codex-cli
```
3. The installer creates the full Codex layout. Note that both OpenCode and Codex CLI use `AGENTS.md` as the dispatcher. The installer will overwrite `AGENTS.md` with the Codex-specific version (which includes the root-context routing header). If you are running both platforms from the same vault, be aware that the two platforms share `AGENTS.md`.
4. Your existing `.opencode/` directory is left untouched.
5. MCP configuration: OpenCode uses `opencode.json`. Codex CLI uses `.codex/config.toml`. If you added custom MCP servers to `opencode.json`, add them to `.codex/config.toml` manually.
6. Custom agents: OpenCode custom agents live in `.opencode/agents/` as Markdown files. Codex CLI custom agents must be TOML files in `.codex/agents/`. See [Custom agents and what does not migrate automatically](#custom-agents-and-what-does-not-migrate-automatically).
---
## Custom agents and what does not migrate automatically
When you run the installer, the 8 core crew agents are automatically translated to Codex TOML format. However, **custom agents you created with `/create-agent`** are not automatically migrated because:
- They live in your platform's agents directory (`.claude/agents/`, `.gemini/agents/`, etc.)
- They are Markdown files; Codex requires TOML
- The installer never overwrites or deletes files in the agents directory that it did not create
### To migrate a custom agent manually
1. Locate your custom agent file (e.g., `.claude/agents/budget-tracker.md`)
2. Open Codex CLI in your vault and run `/create-agent`
3. Describe the agent's purpose — the Architect will guide you through creating a new `.toml` file in `.codex/agents/`
4. Alternatively, create the TOML file manually using one of the generated core agents as a template (e.g., `.codex/agents/scribe.toml`)
### What the TOML format looks like
Codex CLI agent files use top-level keys (not nested under `[agent]`). The required fields are `name`, `description`, and `developer_instructions`:
```toml
name = "budget-tracker"
description = "Monitors spending notes and flags when you are close to the monthly limit"
model = "o4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
developer_instructions = '''
You are the Budget Tracker agent for the My Brain Is Full — Crew system.
... (your agent instructions here)
'''
```
See the [Codex CLI agent roles documentation](https://developers.openai.com/codex/subagents) for the full schema.
---
## Verification after migration
After running the installer, verify the Codex layout with these commands:
### Check that files installed correctly
```bash
ls <vault>/.codex/agents/ # Should list *.toml files for all 8 agents
ls <vault>/.agents/skills/ # Should list subdirectories for all 14 skills
ls <vault>/.codex/config.toml # Should exist with [mcp_servers.*] tables
ls <vault>/AGENTS.md # Should exist with Codex routing header
```
### Run 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: response references `AGENTS.md`, `.codex/agents`, and `.agents/skills`.
### Check MCP visibility
```bash
codex -C <vault> mcp list
```
Expected: lists MCP servers from `.codex/config.toml`.
### Run the full runtime smoke matrix
See [docs/codex-cli.md — Runtime smoke matrix](codex-cli.md#runtime-smoke-matrix) for the complete list of agents, skills, chaining, and MCP checks.
Reference in New Issue View Git Blame Copy Permalink