---
title: "OpenAI Codex"
description: "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

```bash
codex plugin marketplace add baz-scm/baz-plugin --ref main
codex plugin add baz@baz
```

The first command registers the `baz-plugin` repository as a marketplace named `baz`; the second installs the `baz` plugin from it. 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. |
| `get-plan-comments` skill | Pulls every comment on the current plan back into the CLI, so you can work through feedback without leaving Codex. |
| `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:

```text
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](/docs/capabilities/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:

```text
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](/docs/basics/plugins).

## 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`):

```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](/docs/basics/plugins).

## FAQ

<details>

<summary>Why does the tool-usage summary print after every turn?</summary>

Codex has no session-end event, so the summary is per turn and reflects only that turn's Baz calls.

</details>

<details>

<summary>Is there a plan mode in Codex?</summary>

No. The planning skill runs read-only by convention rather than by harness enforcement, and the only file it writes before approval is the plan scratch file.

</details>

<details>

<summary>Codex keeps searching locally. What should I do?</summary>

Name the Baz tools explicitly, or invoke `plan-with-baz`, which restates the routing rules. For authentication loops, clear `~/.mcp-auth` and restart the CLI.

</details>