# Codex

> How midcode runs OpenAI's Codex in the chat and in a terminal, what has to be installed and signed in first, and where its settings come from.

- Page: https://midcode.app/docs/agents/codex
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Codex runs in midcode's Agent panel in both views, with the Codex sign-in already on your Mac. midcode has no OpenAI account of its own and never sees your credentials: it starts Codex in your project's folder and shows what it does.

What the panel does for every agent (the prompt, the crosshair, permission cards, undo) is in [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## At a glance

| What | Chat | Terminal |
| --- | --- | --- |
| midcode starts | `npx -y @agentclientprotocol/codex-acp@2.0.1` | `codex`, typed into a login shell |
| Needs on your Mac | The Codex CLI, signed in, and Node.js (for `npx`) | The Codex CLI, signed in |
| Account | Codex's own sign-in | Codex's own sign-in |
| Codex's edits | Each one is a `⌘Z` step and a line in Publish | On the canvas and in Publish; undone with Codex or git |

## Set it up

1. Install the Codex CLI, if you don't have it:

   ```bash
   npm install -g @openai/codex
   ```

2. Run `codex` once in a terminal and sign in the way you normally do.
3. In midcode, open the Agent panel and choose Codex in the "Agent" menu.

If the panel says "Codex isn't installed", it shows the same install command with a button to copy it. Press "Check again" once it's installed.

## The chat

midcode looks for `codex` on your login shell's `PATH`, then starts the adapter that speaks the Agent Client Protocol for Codex. The first time, `npx` downloads it, and the panel says "Getting Codex ready" for about a minute. The adapter's version is fixed by each midcode release.

From there it's the same chat as with any agent:

- Codex's plan shows as a "Plan" card, and its tool calls open to the command, the output or the diff.
- When Codex asks before running something, you answer on a card in the thread.
- Each edit Codex makes is one `⌘Z` step and a line in [Publish](https://midcode.app/docs/publish/publish.md), named after it ("Codex: …").
- The pickers under the prompt are the options Codex offers for the session with your account. midcode adds none, and remembers the model and effort you chose for Codex separately from the other agents.

## The Terminal view

Switch the panel to the Terminal view ("Show as a terminal") and midcode opens a login shell in your project's folder and types `codex`. It's the CLI as you know it, with its own interface and settings. The two buttons in the header paste the selected element's reference, or your open comments, into its prompt.

In this view Codex writes files by itself: they show on the canvas and in Publish's list of changed files, but they are not steps in midcode's `⌘Z`.

## Limits

- The chat's agent doesn't get the `OPENAI_…` or `CODEX_…` variables your shell exports: they're left out when midcode starts it. If your Codex depends on one (an API key in your shell profile, for example), use the Terminal view, which is your shell, or sign in with `codex` so the CLI keeps the sign-in itself.
- midcode can't sign you in to Codex or switch its account. That's done in the CLI.

## Troubleshooting

**"Sign in to Codex first: run codex once in a terminal."** The adapter started but Codex has no sign-in it can use. Do that, then press "Try again".

**"Codex isn't installed", and it is.** Check that `codex` runs in a new terminal window. midcode looks on your login shell's `PATH`; if installing it added a folder to your `PATH`, quit midcode and open it again.

**"Codex couldn't start".** The panel shows the reason it was given, often the last line the agent printed. One cause is Node.js missing: the adapter is run with `npx` even when the Codex CLI was installed another way.

To have Codex write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).