Skip to content
Esc
↑↓navigate↵open⌘Jpreview
Sign up
On this page

OpenAI Codex

Install the Baz plugin in the OpenAI Codex CLI.

The Baz plugin for the OpenAI Codex CLI adds indexed cross-repository search, the codebase-exploration skill, and two task skills: plan-with-baz and review.

Install

codex plugin install baz-scm/baz-plugin@main

Codex reads the plugin manifest and wires the same skill set and MCP server that Claude Code gets. The first time the agent calls a Baz tool your browser opens for OAuth, and you sign in with your Baz account.

What gets wired

Piece Effect
MCP server baz repo_search, remote_grep, and remote_file_search become available to the agent.
baz-codebase-exploration skill Loads when you ask Codex to plan, scope, or investigate a change. Routes searching through Baz and reading through Codex’s own tools.
plan-with-baz skill Invoked by name to start a planning run.
review skill Diff-scoped code review with cross-repository checks. Invoked by name, or triggered by a plain request such as “review my changes”.
Session hooks SessionStart passes your session id and current repository to the agent, and PostToolUse records Baz tool calls and watches for the finished plan.

Planning with Baz

Codex has no plan mode, so invoke the plan-with-baz skill with a description of the work and the run stays read-only until you approve:

plan-with-baz: add rate limiting to the public API

The agent explores the relevant repositories with the Baz tools, then writes its plan to /tmp/.baz-plan-<sessionId>.md and presents the same content inline. That file write is the signal that planning is over: the plugin’s PostToolUse hook nudges the agent to call update_plan, which stores the plan in Baz and closes the planning session on your timeline. See Planner for the plan record.

Once you approve the plan, ask Codex to save it to baz-plan.md if you want it kept in the repository.

Reviewing with Baz

Invoke the review skill, with an optional scope:

review
review uncommitted
review --pr 42
review --fix

Codex resolves the diff, reads the changed files, then spends the Baz search budget checking the change against repositories you have not cloned. Unlike the planning skill, this one is model-invocable, so asking Codex to “review my changes” reaches the same workflow.

Reviewing is read-only. The --fix loop is the one exception, and it runs only after you approve specific findings, only in the repository you have checked out. The full scope flags, the four cross-repo checks, and the coverage rules are in the plugins overview.

Known limitations

  • Session summary is per turn. Codex has no session-end event, so the tool-usage summary prints after every turn and reflects only that turn’s Baz calls.
  • No plan mode. The planning skill runs read-only by convention rather than by harness enforcement. The only file it writes before approval is the plan scratch file.

Connecting the MCP server without the plugin

Add the server to your Codex config (~/.codex/config.toml):

[mcp_servers.baz]
command = "npx"
args = ["-y", "mcp-remote", "https://baz.co/mcp"]

You get the search tools this way, but not the skills or the session hooks.

Troubleshooting

  • Auth loops. Clear the stored MCP credentials with rm -rf ~/.mcp-auth and restart the CLI.
  • Codex searches locally. Name the Baz tools explicitly, or invoke plan-with-baz, which restates the routing rules.

More detail on the shared pieces is in the plugins overview.

Was this page helpful?