Codex CLI

Overview

Coding Friend supports Codex CLI alongside Claude Code. Claude remains the default host for cf commands; use --agent codex or the --codex alias when you want the Codex path.

Install

# 1. Install the shared CLI
npm i -g coding-friend-cli

# 2. Register the Codex marketplace and deploy generated agents
cf install --agent codex

# 3. Open Codex, then install the plugin from the plugin UI
codex
# inside Codex: /plugins -> install coding-friend

# 4. Initialize this project for Codex
cf init --agent codex --trust-project

--trust-project marks the current project trusted in ~/.codex/config.toml, so Codex can read the project .codex/config.toml written by Coding Friend. Skip it if you prefer to review and trust the project manually.

What Gets Registered

cf install --agent codex:

• Checks that the codex binary exists and is at least 0.130.0
• Runs codex plugin marketplace add dinhanhthi/coding-friend
• Records coding-friend as enabled in ~/.codex/config.toml
• Copies generated agent TOMLs into your personal Codex agents directory when available

cf init --agent codex:

• Creates the usual Coding Friend docs folders (docs/plans, docs/memory, docs/research, and related folders)
• Writes AGENTS.md with Coding Friend rules and $cf-* skill references
• Registers coding-friend-memory in the project's .codex/config.toml (project-scoped — see Why .codex/ Is Project-Scoped)
• Deploys one agent TOML per Coding Friend agent under .codex/agents/
• Sets agents.max_depth = 2 in ~/.codex/config.toml so nested Coding Friend review and implementation agents can run

Why .codex/ Is Project-Scoped

After setup you will find a .codex/ folder in each project, containing a config.toml and an agents/ directory with one TOML per Coding Friend agent (currently 12). This is expected in every project where you run cf init --agent codex — the files are not duplicates and do not need cleanup.

The reason is how Codex registers the memory MCP server. Codex pins an absolute path in its config, so a single global ~/.codex/config.toml entry could only ever point at one project's docs/memory — whichever project ran cf init last — leaking that project's memory into every other Codex session. To avoid this, Coding Friend writes a per-project .codex/config.toml that points the memory MCP at this project's own docs/memory. cf init then deploys the agent TOMLs alongside it under .codex/agents/, so they are available to Codex in this project.

This differs from Claude Code, where the memory server is registered once at user scope and resolves the active project's memory directory at runtime:

These are local working files. cf init git-ignores AGENTS.md for you; if your project tracks the repo, add .codex/ to .gitignore so the generated TOMLs are not committed.

Daily Commands

cf install --agent codex
cf init --agent codex
cf update --agent codex
cf enable --agent codex
cf disable --agent codex
cf uninstall --agent codex

cf update --agent codex runs codex plugin marketplace upgrade coding-friend-marketplace. If Codex reports that the marketplace was upgraded but the plugin is not installed yet, open Codex and use /plugins to install it.

Skills And Agents

In Codex, Coding Friend skills use $cf-* syntax instead of Claude's /cf-* syntax:

$cf-plan add dark mode to the dashboard
$cf-review --target HEAD~1..HEAD
$cf-fix investigate the checkout crash

Agents are generated from the same Markdown source used by Claude and copied as Codex TOML files. Claude's intent tiers map to Codex reasoning effort without pinning an account-specific model:

• haiku -> model_reasoning_effort = "low"
• sonnet -> model_reasoning_effort = "medium"
• opus -> model_reasoning_effort = "high"
• inherit -> inherit the current session defaults

The generated files omit Claude's tool-list frontmatter because tools is not a documented standalone Codex custom-agent key. Agent instructions constrain the role, while the parent Codex sandbox and MCP configuration control the available tools. To pin a model, edit the copied TOML and add a supported Codex model = "...".

Auto-Approve

Codex auto-approve is separate from Claude auto-approve:

cf permission --agent codex --enable-auto-approve
cf permission --agent codex --disable-auto-approve

This writes autoApproveCodex in .coding-friend/config.json. Codex v1 auto-approve is deterministic-only: known-safe reads and working-directory edits can be approved, destructive actions are blocked, and unknown actions defer to Codex native approval. The Claude Sonnet classifier is intentionally not used from Codex hooks.

Known Differences

• Codex plugin install still has a manual /plugins step; the CLI can register and upgrade marketplaces but cannot fully install a plugin non-interactively in Codex 0.130.0.
• Parallel agent fan-out is best effort. Coding Friend raises agents.max_depth to 2, but Codex still decides how to schedule spawned agents.
• Task tracking hooks that depend on Claude-only task events are not registered on Codex.
• Codex hooks are synchronous, so generated Codex hooks keep payloads small and drop Claude's async flag.
• Configure Codex's built-in footer fields with /statusline. Claude's CF-specific live task and agent counters are not available.
• Browse skills with /skills or type $ to invoke one explicitly.
• $cf-session routes to native /resume, /fork, codex resume, and codex fork.

Troubleshooting

codex --version
cf install --agent codex
cf init --agent codex --trust-project
cf update --agent codex

If generated agents are missing, rerun cf install --agent codex after the plugin is installed, then run cf init --agent codex in the project.

For contributors, regenerate the Codex artifact and verify it is committed:

npm run build:codex
npm run verify:codex-drift