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 02:04:43 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
1b9450aa030481f1436a8824ae2a3742e863446a
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

7.8 KiB
Raw 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 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:

    cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull

  2. Run the Codex installer:

    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.

Moving from Gemini CLI

  1. Pull the latest repo changes:

    cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull

  2. Run the Codex installer:

    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.

Moving from OpenCode

  1. Pull the latest repo changes:

    cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull

  2. Run the Codex installer:

    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

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:

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 for the full schema.

Verification after migration

After running the installer, verify the Codex layout with these commands:

Check that files installed correctly

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

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

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 for the complete list of agents, skills, chaining, and MCP checks.

Reference in New Issue View Git Blame Copy Permalink