Skip to content
Test version · build of 28.10.26 · prototypes · direction note

Tested on 28.10.26

Get started with Codex

My real Codex setup: installed, plugged into Claude Code, and what broke along the way. You rebuild each link and check it.

When you finishCodex installed and signed in on your Mac, guided by an AGENTS.md, with a first task started, and the method to check every link before you give it more.

Let’s go
What you need (4)
  • A ChatGPT account. As of 10/28/2026, OpenAI's pricing page lists the terminal (CLI) from Plus ($20 a month). For Free and Go it only mentions the desktop app.
  • The Terminal on your Mac.
  • A project tracked by Git, even a tiny one.
  • 30 quiet minutes.
  • Level 3 · So, can you actually?
  • 30 min
  • Free: Not really (ChatGPT subscription)
  • 16 steps
My mascot in front of a Codex terminal, headphones around the neck

Chapter 01 / 07 · 3 min

What I hand over, and what I keep

I mostly work in Claude Code. Codex is my second brain: a second opinion, a big coding job, or the relief when my Claude cap gets close.

It reads your files and runs commands in the Terminal. It asks for your approval when it matters.

Chapter 02 / 07 · 5 min

Install Codex and check

One command installs, another confirms. Don't move on without the confirmation.

  1. Step 2.1: Paste the first command into the Terminal, then Enter.
  2. Step 2.2: It fails? Paste the second one instead.
  3. Step 2.3: Type the third: a version number must appear.
  4. Step 2.4: Type the fourth: it checks the install, the account and the config.
In the terminal
curl -fsSL https://chatgpt.com/codex/install.sh | sh
In the terminal
npm install -g @openai/codex
In the terminal
codex --version
In the terminal
codex doctor
Plan BIf you get stuck

Using Homebrew? brew install --cask codex works too. The npm version needs Node.js. On my Mac, codex --version says 0.160.1 (10/28/2026): yours is probably newer, that's fine.

Chapter 03 / 07 · 3 min

Connect your account

The browser links Codex to your ChatGPT account. Your password doesn't go through the Terminal.

  1. Step 3.1: Run codex in a project folder.
  2. Step 3.2: Choose "Sign in with ChatGPT".
  3. Step 3.3: Approve in the browser.
  4. Step 3.4: Back in the Terminal, Codex waits for your first instruction.
$ codex…Sign in with ChatGPT1Sign in with API key
  1. The first choice goes through your ChatGPT account.
Plan BIf you get stuck

The browser doesn't open? Copy the link Codex shows into your browser. Prefer a window to the Terminal? Type codex app.

Chapter 04 / 07 · 5 min

Pick your guardrails

Two separate settings: the sandbox (where Codex may write) and approval (when it asks you). OpenAI's docs describe workspace-write with on-request as the low-friction local mode (checked 10/28/2026).

  1. Step 4.1: Open a project tracked by Git: cd ~/Documents/my-project (replace "my-project").
  2. Step 4.2: Start Codex with the guardrails below.
  3. Step 4.3: Paste the first prompt.
  4. Step 4.4: Read every permission before you answer.
In the terminal
codex --sandbox workspace-write --ask-for-approval on-request
First prompt
Explain what this project does, in plain language, without changing anything for now.

Chapter 05 / 07 · 4 min

Write the rules: AGENTS.md

AGENTS.md is the roadmap Codex reads before it starts. Two levels: a global file in ~/.codex/AGENTS.md (your habits everywhere) and one at the root of each project (local rules). The closest one wins.

  1. Step 5.1: Create AGENTS.md at the root of the project.
  2. Step 5.2: Write the test commands to run.
  3. Step 5.3: List the files never to touch.
  4. Step 5.4: Run codex "Summarize the instructions you loaded": it must quote your file.
Plan BIf you get stuck

My global AGENTS.md starts with my writing rule, then points to my Claude Code config so Codex can take over without starting from zero. Put what matters to you.

Chapter 06 / 07 · 6 min

Plug it into Claude Code

My goal: both tools can do the same things. On my Mac it rests on three bridges.

  • Skills: one symbolic link per skill, from ~/.codex/skills to ~/.claude/skills. One copy on disk, so a fix on the Claude side shows up in Codex right away. A small script of mine repairs the links.
  • MCP servers: I add them on the Codex side with codex mcp add. Plugins, however, are not shared.
  • Memory: a bridge drops what Codex learns into Claude's inbox folder.

And to hand a bounded job to Codex from Claude, I use a lightweight profile defined in a separate config.

In the terminal
codex exec -p eco "your instruction" < /dev/null

Chapter 07 / 07 · 4 min

What broke on my side

Here are the real failures, not a magic trick.

  • The skill links had drifted: 41 skills linked out of 132, and 6 dead links. Nobody noticed, Codex just ignored most of my skills. Repaired on 08/29/2026.
  • The memory bridge wrote to the wrong place: 3 notes sat since 09/12 in a folder of Codex's own, invisible to Claude. Aligned with the shared inbox on 09/14, confirmed on 10/09/2026.
  • I looked for a scheduled job in the wrong place: the 6-hour conversation collection isn't a launchd job, it's Codex's internal scheduler. I thought it was dead because I couldn't find it in LaunchAgents.
  • The memory isn't exhaustive: the automatic collection only sees recent conversations. The full history needs a manual export.
Weak

I plug the bridge in, see "OK", move on.

Better

I plug the bridge in, open the destination folder, check that a test note is really there.

The cheat sheet

The whole guide in 6 lines

Copy it into your notes.

Cheat sheet · Get started with Codex
1. Terminal (CLI) listed from Plus as of 10/28/2026; check your plan.
2. Install with the official script, npm as a backup, then codex --version and codex doctor.
3. Run codex and choose "Sign in with ChatGPT".
4. To start: workspace-write + on-request, in a Git project, commit before every task.
5. Rules in AGENTS.md (global + project), 32 KiB at most.
6. Every bridge between agents is checked by opening the destination folder.
Next guide · level 3Plug Codex into Claude Code