How to Use Codex: The Beginner's Guide (First Session, Slash Commands, AGENTS.md, and the Safety Line)

CodexFuse Team · 2026-10-29T15:13:10.593Z · 12 min read

Your first fifteen minutes with Codex: install the CLI, sign in, run your first session, write AGENTS.md, and learn the approval modes that keep your machine safe.

Learning how to use Codex takes about fifteen minutes: you install the CLI, sign in with your ChatGPT account, open a terminal inside a project folder, and type your first task in plain English. Codex is OpenAI's open-source, terminal-based coding agent — you describe what you want changed, it reads your files, proposes a diff, and only applies it after you approve. If you have used a terminal agent before, the loop will feel familiar: our Claude Code beginner guide covers the same idea from Anthropic's side, but this guide is the complete OpenAI lane — install, auth, first session, slash commands, AGENTS.md, and the safety line that keeps your machine intact.

What is Codex CLI, exactly?

Codex CLI is a coding agent that lives in your terminal instead of your browser. It reads the files in your current directory, makes edits across multiple files, and can run shell commands — all inside sandbox and approval settings you control. The project is open source under the Apache 2.0 license at github.com/openai/codex, where it passed 131,000 stars by late October 2026, and the codebase is written primarily in Rust (GitHub README, fetched 2026-10-29).

Three Codex flavors exist, and beginners mix them up. Codex CLI runs locally against your real filesystem. Codex Web (chatgpt.com/codex) runs the same agent in OpenAI-managed cloud containers. The Codex IDE extension brings it into VS Code, Cursor, and Windsurf. There is also a desktop app, launched with codex app. This guide is about the CLI, because that is where developers spend most of their time.

How do you use Codex?

Your first session is five steps. Do them in order, in a throwaway repository — never your first run on a project you care about.

1. Install Codex. On Mac or Linux, run curl -fsSL https://chatgpt.com/codex/install.sh | sh. On Windows, run powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex". The npm and Homebrew paths also work: npm install -g @openai/codex or brew install --cask codex (GitHub README, fetched 2026-10-29).
2. Sign in. Run codex and choose Sign in with ChatGPT. This is the recommended path — Codex is included with Plus, Pro, Business, Edu, and Enterprise plans. An API-key path exists (codex login --with-api-key) but needs extra setup and lacks cloud features like GitHub code review (GitHub README; ayautomate guide, checked 2026-10-29).
3. Move into a project. cd into a small repository. Codex uses your current directory as its working context, so being in the right folder decides what it can see and touch.
4. Ask for something small. Type a task like "explain how the auth module works" or "add input validation to the registration form." Codex reads the repo, plans, and shows you a diff before changing anything.
5. Review the diff, then keep it. Read every proposed change the way you would read a colleague's pull request. Accept, edit, or reject — the session only moves forward when you say so.

That loop — describe, review the diff, approve — is the entire product. Everything below makes that loop faster or safer.

Which install method should you pick?

Any of the five official install paths lands you on the same binary, so pick by your platform and habits. The installers download from releases.openai.com by default and fall back to GitHub Releases; setting CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false forces GitHub (GitHub README, fetched 2026-10-29).

After installing, confirm it landed with codex --version. The CLI ships fast — version 0.164.0 was current in late October 2026 — so re-running your installer every few weeks keeps you current (ayautomate guide, install commands re-checked 2026-10-29).

How does Codex auth work?

Auth is the first decision, not an afterthought, and it decides what you pay and what Codex can reach. There are two paths, and they are not equal.

The pricing page is explicit about the floor: the CLI is included starting at the Plus plan ($20/month), which covers Codex on the web, in the CLI, in the IDE extension, and on iOS. The Free ($0) and Go ($8/month) tiers only list Codex in the desktop app, subject to rollout — the CLI is not listed for them (learn.chatgpt.com/codex/pricing, fetched 2026-10-29). So if you are on a free ChatGPT account and want the CLI, your honest options are upgrading to Plus or bringing your own API key. Check which method is active any time with codex login status.

What do the approval modes and sandbox actually do?

The approval mode is the product's safety core, and beginners should understand it before their first real task. Codex pairs a sandbox mode (what the agent is allowed to touch) with an approval policy (when it must ask you first).

On the approval side, the current policies are on-request (Codex proposes each change and waits for your yes — the default, and where beginners should stay) and never (hands-off execution, no confirmations). Older guides mention an untrusted policy and a suggest/auto-edit/full-auto naming set — those are retired or renamed in current builds (blakecrosley reference, 6 days old; ayautomate guide, checked 2026-10-29). The rule of thumb: on-request is earned trust's starting point, never is earned trust's destination, and the jump between them should take weeks, not minutes.

Two habits make the safety line real. First, create a Git checkpoint before every session: git add . && git commit -m "Before Codex changes" — then git diff afterwards shows exactly what the agent did (lineserve guide, fetched 2026-10-29). Second, keep internet access disabled by default; if a task needs it, allow only specific domains (for example pypi.org or npmjs.com) in ~/.codex/config.toml. Your config file is TOML, not YAML — every current source agrees on ~/.codex/config.toml.

What are the essential slash commands?

Inside a session, slash commands are the control panel. Learn these six and you can ignore the rest for your first month.

Two more are worth knowing early: press Esc twice (or Ctrl+T) to open the transcript and see the agent's reasoning, and type exit or press Ctrl+D to quit (lineserve guide, fetched 2026-10-29).

What is AGENTS.md and how do you write one?

AGENTS.md is project memory: a Markdown file of instructions Codex reads every time it works in your repo. Run /init in a session and Codex drafts one for you; then edit it by hand. It nests — a global ~/.codex/AGENTS.md applies everywhere, the repo-root AGENTS.md overrides it, and subdirectory files override further (danielvaughan guide, 1 day old; learn.chatgpt.com/pricing notes).

Good AGENTS.md content is boring and specific: how to run the test suite, which package manager the repo uses, code style rules, and things the agent must never do ("never commit directly to main", "never edit files under /migrations by hand"). The pricing page itself advises keeping AGENTS.md small — a bloated memory file wastes context on every session. Write it once, and every future session starts smarter.

How do you run Codex without the interactive session?

codex exec is the non-interactive mode: you pass a task as a shell command, Codex streams its progress to stderr, and prints only the final message to stdout. That shape is made for scripts and CI — for example, generating a changelog draft or running a review pass on every pull request (ayautomate guide; learn.chatgpt.com/codex/cli, fetched 2026-10-29).

Two companion flags extend it. codex --image attaches a screenshot or design spec for visual context — paste a terminal error or a UI mock and ask Codex to diagnose it. codex --search gives the agent live web search during the run. And codex mcp wires in Model Context Protocol servers for tools beyond the filesystem. If you live in an editor rather than a terminal, the same agent ships as the Codex IDE extension for VS Code and Cursor — our Cursor AI beginner guide and VS Code beginner guide cover those surfaces, and our Warp beginner guide covers the agentic-terminal alternative.

Which model should you pick?

If you do not set a model, Codex uses a recommended one. The docs currently point complex coding and agentic work at GPT-6 Sol (with GPT-6.1 Sol as the bundled default since v0.159.1), focused repeatable tasks at GPT-6 Luna, and the heaviest work at GPT-6 Astra as the most capable option (ayautomate guide, checked 2026-10-29). Switch with /model inside a session or codex --model gpt-6-sol at launch.

Usage is metered in local messages per five-hour period, with estimates — not fixed limits — published on the official pricing page (fetched 2026-10-29). The spread is wide on purpose: GPT-6 Luna allows roughly 350–3,000 messages per window, GPT-6.1 Terra 35–285, GPT-6 Sol 15–150, GPT-6.1 Sol 15–160, and GPT-6 Astra 5–45. Weekly limits may also apply — /status shows your remaining plan limits during a session. The practical takeaway: do exploratory work on a cheaper model and switch to Astra only for the hard problems.

Codex vs Claude Code: which should a beginner pick?

Both are terminal agents with the same describe-review-approve loop, and honestly either one teaches you the workflow. Codex is the natural pick if you already pay for ChatGPT Plus or higher, since the CLI is included in the plan, and if you want the OpenAI model family (GPT-6 Sol/Luna/Astra) doing the work. Claude Code is the natural pick inside an Anthropic subscription. The skills transfer completely — approval modes, project memory files, and non-interactive runs exist on both sides — so the choice is mostly about which subscription you already have. Start with our Claude Code beginner guide if you go that way; the safety habits in this guide apply there too.

Common first-week mistakes

First, running Codex in your main project on day one. Use a throwaway repo until the approve-the-diff reflex is automatic. Second, accepting every suggestion — the agent is confident even when it is wrong, and a quick git diff review catches the confident mistakes. Third, pasting secrets into prompts: API keys and tokens in a session can end up in transcripts and logs, so use environment variables and never paste a live key. Fourth, skipping AGENTS.md — ten minutes writing project memory pays back in every session after. Fifth, choosing never approval on the first day because the confirmations feel slow; the confirmations are the product working.

Sources

• OpenAI Codex GitHub README (github.com/openai/codex) — install commands, auth recommendation, plans, IDE/desktop/web flavors, Apache 2.0 license; fetched 2026-10-29
• ayautomate.com "Codex CLI: Install on Mac, Linux, Windows + Is It Free?" — install/auth/first-run steps, /init and AGENTS.md, codex login --with-api-key, model recommendations, sandbox/approval names, version 0.164.0; install commands re-checked 2026-10-29
• lineserve.net "Comprehensive Guide to Installing Codex CLI on Linux" — npm/Homebrew install, ~/.codex/config.toml, /model and /status commands, transcript keys, codex review, codex --upgrade, git-checkpoint habit; fetched 2026-10-29
• learn.chatgpt.com/codex/pricing (official) — Plus-and-up CLI inclusion, Free/Go desktop-app-only limits, API-key path, per-5-hour message estimates by model; fetched 2026-10-29
• learn.chatgpt.com/codex/cli (official) — codex resume, codex --image, codex --search, codex mcp, /permissions, codex exec, /status plan limits; fetched 2026-10-29

Frequently Asked Questions

Is Codex CLI free?

The CLI software itself is free and open source (Apache 2.0), but using it draws on a paid plan or an API key. There is no free-tier CLI access: Free and Go ChatGPT plans only list Codex in the desktop app, subject to rollout. The CLI is included starting at Plus ($20/month) (learn.chatgpt.com/codex/pricing, fetched 2026-10-29).

Do I need a ChatGPT Plus subscription to use Codex CLI?

For the recommended path — Sign in with ChatGPT — yes, Plus or higher (Pro, Business, Edu, Enterprise). The alternative is an API key via codex login --with-api-key, which bills per token at API pricing and drops the cloud features (GitHub code review, Slack) (GitHub README; ayautomate guide, fetched 2026-10-29).

What is the difference between Codex CLI, Codex Web, and the IDE extension?

The CLI runs locally in your terminal against your real filesystem. Codex Web (chatgpt.com/codex) runs the same agent in OpenAI-managed cloud containers — good for delegating tasks while you do something else. The IDE extension puts the agent inside VS Code, Cursor, or Windsurf. All three share your plan's Codex usage (GitHub README, fetched 2026-10-29).

What is AGENTS.md?

A Markdown file of project instructions Codex reads at the start of every session in that repo — test commands, style rules, things to never do. Run /init to generate one, then edit it. It nests: a global ~/.codex/AGENTS.md, a repo-root file, and per-directory overrides (danielvaughan guide; learn.chatgpt.com/pricing, fetched 2026-10-29).

Is it safe to let Codex run commands on my computer?

As safe as you configure it to be. Keep the default workspace-write sandbox and on-request approvals, review every diff, create a Git checkpoint before each session, and reserve danger-full-access plus never approvals for disposable environments only. Never paste live secrets into a session (lineserve and ayautomate guides, fetched 2026-10-29).