title: "Your First Hour — Codex CLI" tested_with: codex-cli: "0.2.x" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [00-what-is-agentic-dev]

Your First Hour with Codex CLI

A step-by-step walkthrough from installation to your first completed task. Every command below is copy-paste ready. Notes labeled Adapt this tell you what to change for your specific situation.

Step 1: Installation (~2 minutes)

Codex CLI is distributed as an npm package. You need Node.js 18 or later.

npm install -g @openai/codex

Verify the installation:

codex --version

You should see a version number starting with 0.2. If you get a "command not found" error, check that your npm global bin directory is on your PATH.

Adapt this: If you use nvm or fnm, ensure you are on Node 18+ before installing. Run node --version to check.

Step 2: API Key Setup (~2 minutes)

Codex CLI uses the OpenAI API. You need an OpenAI API key. Create one at platform.openai.com if you do not have one.

Set the key as an environment variable:

export OPENAI_API_KEY="sk-your-key-here"

To make this permanent, add the line to your shell profile:

echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.bashrc
source ~/.bashrc

Adapt this: Replace ~/.bashrc with ~/.zshrc for zsh, or use set -gx syntax for fish shell.

Step 3: Navigate to Your Project and Launch (~1 minute)

Go to a project you actively work on. A real codebase, not a tutorial project.

cd ~/projects/your-project
codex

Codex CLI starts an interactive session. You will see a prompt where you can type natural language instructions.

Adapt this: Replace ~/projects/your-project with the actual path to your codebase. Pick something you know well enough to judge the agent's output.

Step 4: The Guided Tour — Orient the Agent (~10 minutes)

Start by asking Codex to explore, not to build.

Explain this project's structure. What are the key directories, the primary
language, and how is the code organized?

Codex will examine your file tree, read key files, and produce a summary. Evaluate that summary against your own knowledge. Where is it accurate? Where does it miss the mark?

Follow up:

What are the 3 most critical files in this project? Explain why each matters.

The point is not to get a perfect answer. The point is to see how the agent reasons about unfamiliar code and to identify what context it is missing. Those gaps will inform your configuration file next.

Adapt this: For very large projects, narrow the scope: "Explain the structure of the src/services directory and how the services interact."

Step 5: Create a Minimal AGENTS.md (~5 minutes)

Create an AGENTS.md file in the root of your project. Codex CLI reads this file for persistent project context. Start with the bare minimum:

# AGENTS.md

## Project overview
This is a [brief description, e.g., "TypeScript CLI tool for database migrations"].
Built with [language/framework, e.g., "TypeScript 5.x and Node.js"].

## Commands
- Install: [e.g., `npm install`]
- Test: [e.g., `npm test`]
- Build: [e.g., `npm run build`]

## Conventions
- [One key convention, e.g., "Use named exports, not default exports"]

Keep it short. Five to seven lines of real content. You will add more as you discover what the agent gets wrong without explicit guidance.

Adapt this: Fill in your project's actual details. If you are unsure what to include, ask Codex: "Based on what you've seen, what should an AGENTS.md for this project contain?" Use its answer as a starting draft and edit it down.

Step 6: Understanding Approval Modes (~5 minutes)

Codex CLI has three approval modes that control how much autonomy the agent has. This is the most important concept to understand before you start building.

Suggest Mode (the default)

codex --approval-mode suggest

The agent proposes changes but writes nothing to disk without your explicit approval. Every file edit, every command execution requires a "yes" from you. This is the safest mode and the right starting point.

Auto-Edit Mode

codex --approval-mode auto-edit

The agent can read and write files without asking, but still requires approval before running shell commands. Use this when you trust the agent's code changes but want to control what gets executed.

Full-Auto Mode

codex --approval-mode full-auto

The agent reads, writes, and executes commands without asking. Everything runs inside a sandboxed environment (more on this in Step 9). Use this only for well-understood, low-risk tasks once you have calibrated your trust.

For your first hour, stay in suggest mode. You want to see and approve every change. This is how you build an accurate mental model of what the agent does.

Step 7: Your First Real Task in Suggest Mode (~15 minutes)

Pick a small, real task from your project. Start in suggest mode so you see everything before it happens.

Option A — Add a test:

Write a unit test for the [function_name] function in [file_path].
Cover the normal case and one edge case. Match the testing style
already used in this project.

Option B — Fix a small bug:

In [file_path], there's a bug where [brief description].
Fix it and explain the root cause.

Option C — Add documentation:

Add JSDoc comments to all exported functions in [file_path].
Follow the documentation style used elsewhere in this project.

When Codex proposes a change, you will see a diff. Read it carefully before approving. This is calibration, not a race.

If the proposed change is wrong, reject it and provide more context:

That's not quite right. The function should [clarification]. Try again.

Adapt this: Replace the bracketed placeholders with real files and functions from your project. If nothing comes to mind, try: "Find a function in this project that lacks tests and write one."

Step 8: Switching to Auto-Edit for a Known-Safe Task (~5 minutes)

Once you have completed a task in suggest mode and feel comfortable with the agent's judgment, try auto-edit mode for a simple, safe task.

Start a new task with auto-edit:

codex --approval-mode auto-edit

Then give it something low-risk where file changes are fine but you want to control execution:

Add type annotations to all functions in [file_path] that are currently untyped.
Do not change any logic, only add types.

Notice the difference in flow. Codex will modify files without asking but will still prompt you before running any commands like tests or linters. This is a good middle ground for tasks where the changes are straightforward and you mainly care about what gets executed.

Adapt this: Choose a file where type annotations or docstrings are missing. This is the safest class of auto-edit task because it is additive — nothing existing is modified.

Step 9: The Sandbox — What Runs Where and Why (~3 minutes)

Codex CLI runs shell commands inside a sandboxed environment. This is a critical safety feature, especially in full-auto mode.

The sandbox restricts:

• Network access: Commands cannot make outbound network requests by default. This prevents accidental data exfiltration or unintended API calls.
• File system access: Commands can only access files within your project directory. They cannot read or modify files outside the project root.
• Process isolation: Commands run in an isolated context that limits what system resources they can touch.

In suggest and auto-edit modes, you approve each command before it runs, so the sandbox is a secondary safety net. In full-auto mode, the sandbox is your primary safety net.

To see the current sandbox configuration:

What sandbox restrictions are currently in place?

For your first hour, the defaults are fine. The key takeaway is that Codex is designed with defense in depth: approval modes control what the agent can do, and the sandbox controls what happens when commands actually execute.

Step 10: Reviewing Changes and Ending the Session (~10 minutes)

Before you close anything, review every change the agent made.

git diff

For new untracked files:

git status

Read every line of the diff. Ask yourself:

• Is this code correct? Would it pass a code review?
• Does it match the project's existing style and conventions?
• Did the agent stay within the scope of what I asked?
• Are there any changes I did not expect or did not request?

If the changes look good:

git add -p
git commit -m "Add tests for [function_name] via Codex CLI"

Using git add -p stages changes interactively, giving you one final review before committing.

If the changes are not right, discard them:

git checkout -- .

To end the Codex CLI session, press Ctrl+C or Ctrl+D.

Your AGENTS.md file is saved on disk and will be read automatically the next time you start a session in this directory.

Quick Reference

Approval mode cheat sheet:

Total estimated cost: $1-5 in API tokens for the full hour.