Codex CLI Setup

Requirements

• A supported local environment with Git and the project's own build and test tools installed.
• A ChatGPT sign-in or another authentication method presented by the CLI.
• On Windows, use native Codex when Windows tools own the repository or WSL 2 when the project and toolchain live in Linux.
• A clean Git checkpoint before the first task that can modify files.

Quick setup

Install, verify, and open a project

curl -fsSL https://chatgpt.com/codex/install.sh | sh

codex --version

cd path/to/your-project
codex

/status
/permissions

Step 1

Keep Codex and the repository in one environment

Codex runs local commands, so the shell, repository paths, dependencies, and test tools should agree about where the project lives.

1. On macOS or Linux, install from the shell used for normal development.
2. On Windows with WSL 2, store repositories under ~/code instead of /mnt/c for faster I/O and fewer permission problems.
3. Do not open a Windows checkout from WSL and then expect Windows-only commands to behave like Linux commands.

Step 2

Install, verify, and sign in

The official quickstart uses a standalone installer for macOS and Linux. The first `codex` launch asks you to choose an available sign-in method.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

codex --version

cd path/to/your-project
codex

Important: If you use WSL, run both installation and Codex inside the WSL shell. WSL 1 is no longer supported by current Codex releases; use WSL 2.

Step 3

Inspect the active model, directory, and permissions

Before delegating work, confirm that Codex is operating in the intended repository with an access level appropriate for the task.

1. Confirm the directory shown by `/status` is the repository root you intended.
2. Start with approval-based or restricted permissions for unfamiliar work.
3. Do not grant network, deployment, or secret access merely because a task may eventually need it.

/status
/permissions

Step 4

Create AGENTS.md from verified repository facts

Codex can create an AGENTS.md with `/init`, but the generated file still needs human review and real project commands.

1. Compare detected commands with package files, task runners, and CI.
2. Remove generic advice and document concrete directories, commands, and prohibitions.
3. Commit AGENTS.md so later sessions and collaborators use the same rules.

Explain the architecture, development commands, test commands, and boundaries. Do not edit files.

/init

Step 5

Run one small task with a Git checkpoint

The first task should test context, editing, command execution, and review without putting production data or a large refactor at risk.

1. Commit or stash the current working tree.
2. Ask for one bounded change with a named file area and acceptance check.
3. Review every changed file and run the relevant tests yourself.
4. Use `/review` as an additional pass, not as a replacement for human diff review.

Step 6

Use WSL 2 correctly on Windows

WSL 2 is appropriate for Linux-native repositories and tools. Keep both the repository and Codex inside the Linux filesystem.

wsl --install

mkdir -p ~/code
cd ~/code
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Common setup errors