What the Codex CLI is and how to run it inside a project folder on a Mac

Codex is a name OpenAI uses for several things, and that is the first source of confusion. Codex CLI is the one that runs on your own machine, in your own terminal, against the files in front of you. It is not the cloud agent at chatgpt.com/codex, and it is not the IDE extension, though all three share an account and a set of conventions. This guide covers the local terminal tool: how it installs on a Mac, what the first session looks like inside a project folder, and which settings decide how much freedom the agent has.

What Codex CLI is, and what it is not

Codex CLI is a coding agent that runs locally. It reads files, edits them, runs commands with the tools already installed on the machine, and reports what it did. The interactive session is a terminal user interface: a prompt box, a transcript of tool calls and diffs, and slash commands for changing the model, the permissions, or the review mode mid-task.

OpenAI ships three other surfaces around it. The IDE extension puts the same agent inside VS Code, Cursor, or Windsurf. Codex cloud runs tasks on OpenAI infrastructure from the web. Running codex app opens a desktop application. The CLI is the one to choose when the work is already in a terminal, when it needs to compose with scripts, or when the files involved should not leave the machine.

Two things follow from being local. The agent can only act on what it can reach, so the directory it starts in matters more than any setting. And because it runs real commands, the safety model is not a policy document but an operating system sandbox, which is covered further down.

Installing on macOS

There are four documented install routes and they all produce the same binary.

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # standalone installer
npm install -g @openai/codex
brew install --cask codex

The standalone installer downloads from OpenAI's release host and falls back to GitHub Releases if that is unavailable. Updating is the same command as installing for the standalone route, npm install -g @openai/codex for npm, and brew upgrade --cask codex for Homebrew. Prebuilt archives for Apple Silicon and Intel are also attached to each GitHub release for anyone who prefers to place the binary by hand.

Then sign in. Running codex for the first time offers Sign in with ChatGPT, which is the route OpenAI recommends, or an API key for shared environments such as continuous integration.

Plan	Price listed	Notes
Free	0 USD per month	Positioned for quick coding tasks
Go	8 USD per month	Lightweight use
Plus	20 USD per month	A few focused sessions per week, plus cloud features
Pro	From 100 USD per month	5x or 20x the usage of Plus
API key	Usage-based	CLI, SDK, and IDE only, no cloud features such as code review or Slack

Prices are the ones OpenAI publishes on its Codex pricing page and exclude tax. The API key route is worth noting for a different reason than cost: it drops the cloud-connected features and follows whatever models the key has access to, which makes it the predictable choice inside automation.

One dated detail to keep in view: OpenAI has announced that GPT-5.5 retires from ChatGPT and Codex on all plans on October 14, 2026. Anything pinned to that model in a config file needs a replacement before then.

The first session in a project folder

Open a terminal at the project directory and run codex. The header shows the model, the reasoning effort, and the working directory, and that third line is the one to read twice. Everything the agent does is anchored there.

A good first move is /init, which writes an AGENTS.md file into the repository. That file is where the project's standing instructions live: how to run the tests, which directories are generated, what the naming conventions are, what not to touch. Every terminal agent has converged on this pattern under a different filename, and the payoff is the same in each: instructions written once stop being retyped in every prompt.

From there, the useful first task is a question rather than a change. Asking the agent to describe the project surfaces what it can and cannot see, and costs nothing if the answer is wrong. OpenAI's own quickstart suggests creating Git checkpoints before and after a task so that any change can be reverted, which is the cheapest safety net available and works regardless of how the permissions are set.

Useful commands inside the session:

• /status shows the current session configuration
• /model changes the model and reasoning effort
• /permissions shows what the agent may do and which roots are writable
• /review runs a dedicated review pass over changes without touching the working tree

Permissions and the sandbox

This is the part of Codex CLI worth understanding properly, because it is where the tool differs most from a chat window that merely suggests code.

Two settings work together. Sandbox mode decides what the agent can technically do: where it may write, and whether it may reach the network. Approval policy decides when it has to stop and ask. On a Mac, the sandbox is enforced by the operating system rather than by the model's good intentions.

The defaults are conservative. Network access is off, and writes are limited to the active workspace. In the Auto preset, which corresponds to --sandbox workspace-write --ask-for-approval on-request, the agent reads, edits, and runs commands inside the working directory on its own, and asks before editing files outside it or doing anything that needs the network. Switching to read-only with /permissions gives a planning session that cannot change anything.

Some paths stay protected even inside a writable root, .git and .codex among them, so an agent cannot quietly rewrite history or its own configuration. Destructive tool calls from connected apps and MCP servers require approval when the tool declares itself destructive.

At the other end sits danger-full-access, reachable through the --yolo style settings. It exists for throwaway containers, not for a laptop that holds client work. Note one consequence documented by OpenAI: web search normally serves results from a maintained cache, which limits exposure to instructions hidden in arbitrary live pages, but under a full-access setting it switches to live results.

Configuration lives in ~/.codex/config.toml for personal defaults, with per-project overrides in a .codex/config.toml inside the repository, loaded only for projects marked as trusted. A minimal pair of settings looks like this:

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Beyond the first loop

Once the basic session is comfortable, four features carry most of the day-to-day value.

Resuming. codex resume reopens a recent chat from the current repository, or searches across local chats for older work. Sessions are per-directory, which is another reason to keep one folder per piece of work.

Images. codex --image attaches a screenshot, a diagram, or a design reference to the first prompt, and images can be pasted into the composer mid-session. An error screenshot often explains a problem faster than a paragraph describing it.

Subagents. A larger investigation can be split, with focused agents doing the digging and reporting findings back into the main session. This keeps the main transcript readable.

Non-interactive runs. codex exec is the scripted form, for pipelines, scheduled jobs, and repeatable checks. Paired with an API key, it is how Codex ends up inside continuous integration rather than only in a human session.

Skills package repeatable instructions, and plugins connect the CLI to team tools. Both are managed from inside the session rather than by hand-editing configuration.

How it sits next to the other terminal agents

Three agents share this space on a Mac, and the differences that matter are less about raw capability than about defaults and distribution.

	Codex CLI	Claude Code	Gemini CLI
Project instructions	AGENTS.md	CLAUDE.md	GEMINI.md
Default network access	Off in the standard sandbox	Configurable	Configurable
Entry price	0 USD on the Free plan	20 USD per month for Pro	Paid API key or org license
Scripted runs	codex exec	claude -p and the Agent SDK	gemini -p with JSON output
Source	Open, Apache 2.0	Closed	Open, Apache 2.0

Two entries in that table deserve a sentence. Gemini CLI stopped serving consumer tiers on June 18, 2026, when Google moved those users to Antigravity CLI, so on a personal Google account it is no longer a like-for-like alternative. And the sandbox row is where Codex CLI is most opinionated: network access off by default is a meaningful protection when an agent is about to run commands that a model wrote.

Running more than one agent is common and not a problem. They use different instruction files, so a repository can carry AGENTS.md and CLAUDE.md side by side, each describing the same project in whatever form its reader expects. Keeping the substance of those files identical is worth the small duplication.

The assumption the CLI makes about your folders

Every capability above rests on one premise: that the terminal is already open at the right directory, and that the files the work needs are inside it.

That premise breaks constantly. A single job touches a repository, a folder of reference PDFs, a client export sitting in Downloads, and footage on an external drive. Codex sees the directory it was launched in. Pulling in the rest means switching to Finder, locating the path, copying it, switching back, typing cd, and restarting the session. Each round trip is a few seconds and a small tax on attention, and both compound over a day.

The low-cost fix is discipline: one folder per project, an AGENTS.md inside it, and a habit of launching from there. The structural fix is to stop treating the file browser and the terminal as separate applications. When a file manager keeps a terminal in the same window, selecting a folder is what opens the shell in it, so the agent always starts where the work is and the files it rewrites stay visible beside the transcript. The comparison with other file managers lays out how that differs from the usual Finder plus terminal arrangement.

There is a second gap, and it is time rather than space. An agent run takes minutes and then stops to ask a question, and that question waits until someone returns to the desk. Reading and answering a running terminal from an iPhone or iPad closes most of that gap without moving the work off the Mac.

What to change first

Install through whichever route matches the rest of the machine, sign in, and leave the sandbox on its defaults until the agent's behavior is familiar. Then spend twenty minutes on AGENTS.md, because that file is what stops the same explanations being retyped for the next six months.

After that, count the application switches in one working hour. If the number is large, the next improvement is not a different agent but a window where the folder and the shell live together. Everything Atriens does on the Mac itself is free to use, which makes that an easy thing to measure rather than argue about.