#Quick Start

#Start an interactive session

From your project root:

cd your-project
codex

In the TUI (Terminal UI), describe a task in natural language, for example:

Read the src/auth directory, summarize the auth flow, and list three potential security risks.

Common TUI commands:

#Recommended safe defaults

For local development, set sandbox and approvals explicitly (or persist in config.toml):

codex --sandbox workspace-write --ask-for-approval on-request

Codex can edit and run tests inside the workspace; out-of-bounds actions pause for approval.

#Non-interactive: codex exec

For scripts, CI, and one-shot tasks:

codex exec "Run npm test and fix failing cases; do not change package.json"

CI-friendly combination:

codex exec \
  --sandbox workspace-write \
  --ask-for-approval never \
  --json \
  --output-last-message \
  "Generate changelog entries from the PR diff"

When using never for approvals in CI, pair it with a strict sandbox and read-only checkout to avoid accidental repo changes.

#Set working directory

codex --cd services/api "List public API routes for this service"

Codex loads the AGENTS.md chain from the repo root down to services/api.

#Attach images

The CLI supports screenshots and design assets (see codex --help for flags), e.g. for UI tasks:

codex "Implement the Settings page layout from the attached screenshot using existing Tailwind conventions"

#First end-to-end mini project: health check endpoint

Goal: Add GET /health to an existing web service and add tests.

1. (Optional) Create a Git checkpoint

git checkout -b feat/health-endpoint

2. Add a minimal AGENTS.md at the repo root

# AGENTS.md

## Testing
- Run `npm test` to verify changes
- Do not commit node_modules

3. Start Codex

codex --sandbox workspace-write --ask-for-approval on-request

4. Example prompt

Add GET /health returning { "status": "ok" }.
Follow existing route registration patterns and add a unit test.
Run tests when done and report results.

5. Human review

git diff
npm test

#Work with Git checkpoints

Codex edits files directly. Recommended workflow:

• Before: git stash or a new branch
• After: git diff + tests + manual commit
• App / IDE may offer checkpoint concepts depending on version

#Next steps

• Architecture & Runtime: instruction chain and tool loop
• AGENTS.md: team conventions in the repo
• Practical Examples: longer end-to-end flows