# Codex CLI Guide

Codex CLI is OpenAI's lightweight local coding agent. It runs in your terminal, reads your codebase, edits files, and executes commands. Part of ChatGPT Plus/Pro/Business plans or usable with an API key.

**Official docs:** https://developers.openai.com/codex
**GitHub:** https://github.com/openai/codex

---

## Installation

```bash
# macOS / Linux (recommended)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Homebrew
brew install --cask codex

# npm (global)
npm install -g @openai/codex

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

---

## Authentication

```bash
codex   # On first run, select "Sign in with ChatGPT"
```

**With API key instead:**
```bash
export OPENAI_API_KEY=sk-...
codex
```

For full auth options: https://developers.openai.com/codex/auth

---

## Basic Usage

```bash
# Start interactive session in current directory
codex

# One-shot task (non-interactive)
codex "add input validation to the login form"

# Quiet mode (minimal output)
codex -q "fix the TypeScript errors"

# Full auto mode (no confirmations — use carefully)
codex --approval-mode full-auto "refactor the API layer"
```

---

## Approval Modes

| Mode | Behavior |
|------|----------|
| `suggest` (default) | Shows proposed changes, waits for approval |
| `auto-edit` | Edits files automatically, asks before shell commands |
| `full-auto` | Runs everything without asking (use in sandboxed environments) |

```bash
codex --approval-mode auto-edit "clean up unused imports"
codex --approval-mode full-auto "run tests and fix failures"
```

---

## Key Flags

| Flag | Description |
|------|-------------|
| `--model <model>` | Specify model (`o4-mini`, `o3`, etc.) |
| `--approval-mode <mode>` | Set approval level |
| `-q` / `--quiet` | Minimal output |
| `--no-project-doc` | Ignore `AGENTS.md` / `CODEX.md` |
| `--project-doc <file>` | Use custom instructions file |
| `--full-stdout` | Show all shell output (not truncated) |

---

## AGENTS.md / CODEX.md (Project Instructions)

Codex automatically reads `AGENTS.md` from the project root (and parent directories). Put project-specific instructions there:

```markdown
# Project Instructions
- Use TypeScript strict mode
- Run `npm test` to verify changes
- Never modify files in /dist directly
```

In this environment, `AGENTS.md` is already used by Silma's workspace. For a client project, create one in the repo root.

---

## Using with Local LLMs

Codex CLI supports OpenAI-compatible endpoints:

```bash
# Point at local llama.cpp (Gemma models on Tabitha)
OPENAI_BASE_URL=http://localhost:8080/v1 \
OPENAI_API_KEY=local \
codex --model gemma-4-e4b "explain this codebase"
```

See `tools/local-llm.llm.md` for available local models and endpoints.

---

## Working with This Environment

```bash
# Clone from Gitea first, then run codex in the repo
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cd aarete-doczyai-app
codex

# Load credentials before running if the task touches AWS/GitHub
source /Users/Tabitha/.openclaw/workspace/credentials/secrets.env
codex "deploy the latest build to Amplify"
```

---

## IDE Integration

Codex also works as a VS Code / Cursor / Windsurf extension:

```
VS Code:   https://marketplace.visualstudio.com/items?itemName=OpenAI.codex
Cursor:    Install from Cursor extensions panel (search "Codex")
```

---

## Tips

- Start with `suggest` mode to review changes before they land
- Use `full-auto` only in throwaway branches or sandboxed environments
- For long-running tasks, use the Codex web app at https://chatgpt.com/codex (cloud-based, parallel agents)
- Codex reads `AGENTS.md` — keep it concise and action-oriented