Codex‑CLI Power User Guide (2025)

From Qiki
Revision as of 10:48, 10 October 2025 by Ryan (talk | contribs) (Created page with "<span id="codexcli-power-user-guide-2025"></span> = Codex‑CLI Power User Guide (2025) = <span id="what-is-codexcli"></span> == 1) What is Codex‑CLI? == Codex‑CLI is a '''local coding agent''' you run from your terminal. It can '''read files''', '''edit code''', and '''run commands''' in the directory you choose. You talk to it with plain English (and even attach screenshots). It plans, makes diffs, runs tests, and iterates — like a teammate who works directly i...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Codex‑CLI Power User Guide (2025)

1) What is Codex‑CLI?

Codex‑CLI is a local coding agent you run from your terminal. It can read files, edit code, and run commands in the directory you choose. You talk to it with plain English (and even attach screenshots). It plans, makes diffs, runs tests, and iterates — like a teammate who works directly in your repo.

Great for: fixing CI failures, adding tests, refactors, feature spikes, migration work, documentation, “what broke?” investigations.


2) Quick Setup (macOS & Linux)

# Install (pick one)
npm install -g @openai/codex
brew install codex

# Run
codex

First run: log in with your ChatGPT account (Plus/Pro/Team/Edu/Enterprise) or use an API key.

Windows: use WSL for best results.


3) Your First Session (5 minutes)

  1. Open the repo you want Codex to work in:

    cd ~/code/my-app
codex

  2. Tell it the job:

    "Add unit tests for the cart service and fix any failing ones."

  3. Watch the plan → diffs → runs.

  4. If you like the changes, commit (you can ask Codex to make a conventional commit message too).

Tip: Start with one clear goal. Let Codex finish, then give the next goal.

4) Models & Reasoning — use the best

  • In the Codex UI, type:

    /model

    then choose GPT‑5‑Codex and set Reasoning: High for tough jobs.

  • From the shell (non‑interactive):

    codex --model gpt-5-codex

When to pick High reasoning: big refactors, flaky CI hunts, performance work, multi‑step migrations.


5) Approval & Sandbox Modes (safety vs. speed)

Codex can act with different levels of freedom:

  • Auto (default): edits and runs inside the current directory. Asks before touching things outside your workspace or using the network.
  • Read‑Only: plan and review only. No file writes or command runs.
  • Full Access: no prompts — fastest, but use with care.

Switch inside the UI: 

/approvals

Tip: Keep Auto for everyday use. Switch to Full Access only when you trust the task and the repo state.

6) Attach Images (logs, screenshots, diagrams)

Codex understands images — useful for test failures, UI issues, or error screenshots. 

codex -i screenshot.png "Explain this error and fix the cause"
# or multiple
codex --image img1.png,img2.jpg "Summarize these diagrams and generate code"

7) Non‑interactive mode (scripts & CI)

Run a single instruction without opening the TUI: 

codex exec "find TODOs and create a .plans/ file per TODO with a step‑by‑step implementation plan"

Ideas: nightly autofix for flaky tests, automated changelog cleanups, codebase audits, dead‑code sweeps.


8) Best‑practice Workflow

Before each big task

  • Make a git checkpoint:

    git checkout -b chore/codex-checkpoint-2025-10-10
git commit -am "checkpoint: before Codex task"

  • Tell Codex the constraints (style, frameworks, minimum versions, CI tools).

  • Keep prompts short and concrete; let Codex propose a plan.

While it works

  • Ask Codex to explain diffs and justify changes.
  • If it’s heading the wrong way, say “stop, new plan”.

After

  • Run your test suite yourself once.
  • Ask Codex for a conventional commit message or a PR description.


9) Powerful Prompt Patterns (copy‑paste)

  • Refactor safely

    “Refactor the user/profile module to remove duplicated logic. Keep public APIs stable. Add tests that codify the new behavior.”

  • Kill a flaky test

    “Find the three flakiest tests in this repo and stabilize them. Show me a short summary of root causes.”

  • Performance pass

    “Profile the slowest API endpoint locally, propose 3 fixes, implement the least risky one, and add a benchmark script.”

  • Security sweep

    “Scan for unsafe deserialization or SQL injection in server/. Add minimal fixes and unit tests.”

  • Documentation

    “Create a docs/architecture.md with an overview diagram and key data flows. Link to code folders.”

  • Bug report to fix

    “Reproduce the bug described in issues/1245.md. Write a failing test, then fix it.”


10) Configuration (make it yours)

Codex stores settings in ~/.codex/config.toml. Common tweaks: 

# ~/.codex/config.toml

# Use the best model by default
model = "gpt-5-codex"
# Reasoning effort: "low" | "medium" | "high"
model_reasoning_effort = "high"

# When to pause for approval: "read-only" | "on-request" | "auto"
approval_policy = "auto"

# How much access Codex has to your files/network
sandbox_mode = "workspace-write"

# Limit which env vars Codex can forward to spawned commands
[shell_environment_policy]
include_only = ["PATH", "HOME"]

# Optional: different setups
[profiles.safe]
model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "read-only"

[profiles.speed]
model = "gpt-5-codex"
model_reasoning_effort = "high"
approval_policy = "auto"

Use a profile on the fly: 

codex --profile safe

Tip: Check this file into dotfiles, not into your project repo.

11) MCP (Model Context Protocol) — give Codex tools

MCP lets Codex connect to external tools and extra context (docs, browsers, etc.). Two common ways:

  • Interactive:

    codex mcp add

    (Follow the prompts to register a server.)

  • Config‑based (example):

    # ~/.codex/config.toml
[mcp_servers.docs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-docs"]

Good starters: a docs server for your framework, a browser/search server, a GitHub helper. Only connect servers you trust.


12) Login, Upgrades, and Headless machines

  • Normal login: run codex and choose Sign in with ChatGPT.

  • API‑key login (headless / CI):

    printenv OPENAI_API_KEY | codex login --with-api-key

  • Upgrade:

    npm install -g @openai/codex@latest
# or
brew upgrade codex


13) Speed & Reliability Tips

  • Keep your working directory small (avoid checking out giant monorepos if you only need one package; cd into the subfolder you care about).
  • State is power: add an AGENTS.md at your repo root with architecture notes, naming rules, and “how to run tests”. Codex will use it as memory.
  • Prefer one big goal → finish → next big goal. Avoid stacking five unrelated tasks.
  • When Codex stalls, ask: “Summarize the plan so far and what you need.”
  • Save reusable prompts in .plans/ or scripts/codex/.


14) Safety & Privacy

  • Use Read‑Only when exploring unfamiliar repos.
  • Keep Auto for day‑to‑day to avoid surprises outside your workspace.
  • Consider Zero‑Data Retention options if your company requires it.
  • Limit environment variables (see shell_environment_policy).


15) Troubleshooting Quick Wins

  • Login fails on a remote server: try API‑key login via stdin (see above).
  • CLI is old: upgrade Codex (see upgrade commands) and try again.
  • MCP server flaky: disable the server, re‑add later. Keep only what you need.
  • Weird diffs? Ask Codex to explain the change and back it out if needed.
  • Windows quirks: prefer WSL.


16) Handy One‑Liners

# Switch model on launch
codex --model gpt-5-codex

# Use a safer profile
yes | codex --profile safe "Review all changes in src/ and propose a cleanup plan"

# Fix CI quickly (non‑interactive)
codex exec "Diagnose failing CI job and push the minimal fix with tests"

# Add tests for a folder
codex "Write unit tests for services/payment. Keep public APIs stable."

# Generate release notes from commits
yarn release && codex "Draft release notes from last 50 commits with links"

17) Where to go next

  • Try the IDE extension (VS Code, Cursor, Windsurf) if you prefer editing in your editor.
  • Explore cloud tasks if you want to spin up parallel sandboxes for larger jobs.
  • Wire up the TypeScript SDK or GitHub Action for CI / automation.


You’re ready! Keep prompts clear, review diffs, and let Codex handle the heavy lifting. Happy shipping 🚀

Retrieved from "https://www.qfqu.com/w/index.php?title=Codex‑CLI_Power_User_Guide_(2025)&oldid=124"