Using OpenAI Codex in SpaceSpider

Codex is OpenAI's terminal coding agent. It reads files, plans work, runs tools, and edits code inline. Paired with SpaceSpider's grid, Codex becomes an ideal second or third opinion next to Claude Code, Qwen Code, and Kimi CLI. This page covers install, auth, recommended pane placement, and the workflows where Codex excels.

Install the Codex CLI

Codex ships as an npm package. Install it globally so SpaceSpider can auto-detect it on PATH:

npm install -g @openai/codex

Verify the install:

codex --version

On Windows, close and reopen your PowerShell after installing so the PATH change propagates. On macOS and Linux, confirm your global npm bin directory is on PATH.

Authenticate Codex

Codex uses your OpenAI credentials. The recommended path is:

codex login

This opens a browser, completes OAuth against your OpenAI account, and writes a credential file to your home directory. Every Codex pane in SpaceSpider picks it up automatically.

If you prefer direct API-key auth, export one before launching SpaceSpider:

export OPENAI_API_KEY=sk-...

On Windows:

setx OPENAI_API_KEY "sk-..."

Restart SpaceSpider so new panes inherit the updated environment.

Assign Codex to a pane

1. In the new-space wizard or the CLI picker (Ctrl+Shift+T), click a slot.
2. Select Codex. A green dot next to the tile confirms the CLI is installed.
3. Save.

SpaceSpider spawns codex in the space's directory. You see Codex's banner and a prompt.

Recommended pane placement

Codex is fastest in tight, iterative loops. In most grids, pair it with at least one other AI CLI and a shell.

For a 2-pane space:

• Left: Codex for the main driver role.
• Right: shell for tests and git.

For a 4-pane 2-by-2:

• Top-left: Claude Code for architectural work.
• Top-right: Codex for iteration and test-driven tweaks.
• Bottom-left: shell for npm test --watch.
• Bottom-right: shell for git and diffs.

For a 6-pane setup, duplicate Codex in two panes when you want to work on two features in parallel without context bleed.

See Grid layouts for monitor guidance.

Workflows that fit Codex

Test-driven implementation

Codex is strong at writing and iterating tests. In a 2-pane space:

1. Ask Codex in the left pane to implement a failing test for the feature.
2. Ask Codex to run the test and fix the implementation until it passes.
3. Tail the output in a shell pane with npm test -- --watch.

Review a Claude Code diff

Let Claude Code edit in one pane; ask Codex in the next pane to review git diff. Codex tends to surface different risks than Claude Code, and you get both opinions without switching tools.

Spike new ideas

Spin up a fresh space on a throwaway branch. Ask Codex to spike three different implementations in separate commits. Compare them in a shell pane with git log --oneline.

Codex environment variables

Set these before launching SpaceSpider. They pass through the PTY environment:

• OPENAI_API_KEY: direct API-key auth.
• OPENAI_BASE_URL: for proxies or Azure OpenAI endpoints.
• CODEX_MODEL: default model; for example gpt-5-codex or a future equivalent.
• CODEX_EDITOR: the editor Codex launches for interactive edits. Falls back to $EDITOR.

Picking a Codex model

Codex supports multiple models with different latency and reasoning trade-offs. Common picks:

• gpt-5-codex: default, balanced.
• gpt-5-codex-mini (or similar cheaper tier): fast iteration, cheaper.
• A reasoning-tier model for long planning tasks.

Override per pane by setting args in the pane command:

codex --model gpt-5-codex-mini

Edit the pane's command override through its settings menu and save.

Useful Codex slash commands

Inside a Codex pane:

• /help: lists commands.
• /model: switches the active model mid-session.
• /clear: drops the in-session context.
• /cost: prints current token usage.

Cost tips when running multiple agents

Running Codex alongside Claude Code, Qwen Code, and Kimi CLI can rack up usage quickly. A few practical guardrails:

• Keep one pane on the cheapest tier and use it for scaffolding, test stubs, and trivial fixes.
• Reserve the reasoning-tier model for the pane doing architectural decisions.
• Compare costs across CLIs. Qwen and Kimi are often cheaper per token; see Using Qwen Code and Using Kimi CLI.

Troubleshooting Codex in SpaceSpider

• "Authentication required": run codex login in a regular terminal once.
• "Command not found": PATH does not include the global npm bin. Restart SpaceSpider from a fresh shell.
• Slow streaming output: a network proxy or corporate firewall is buffering. Set OPENAI_BASE_URL if needed.
• Output wraps mid-character: xterm.js defaults to UTF-8; if you see mojibake, confirm your system locale is UTF-8.

More on Troubleshooting.

Frequently asked questions

Can Codex and Claude Code edit the same file at the same time?

Technically yes, but in practice the last writer wins. Keep agents on separate files or sequential edits to avoid clobbering.

Does SpaceSpider support Azure OpenAI?

Set OPENAI_BASE_URL and the Azure-specific headers Codex requires; the PTY passes them through.

Can I run two Codex panes on different models?

Yes. Each pane is independent. Override the model per pane with custom args.

What happens to the Codex session when I close the grid?

The PTY exits and the session ends. Use Esc Esc to return home without closing, which keeps PTYs alive.

Does Codex inherit my shell aliases?

No. The PTY runs Codex directly, not through a login shell. Aliases from ~/.bashrc do not apply inside the Codex session. Environment variables exported at launch do apply.

Related reading

• Using Claude Code in SpaceSpider
• Using Qwen Code in SpaceSpider
• Grid Layouts: 1 to 9 Panes Explained