codex

Codex CLI

Use the OpenAI Codex CLI when the user wants an autonomous coding pass in a git repository: feature work, bug fixes, refactors, review passes, or isolated experiments.

Prerequisites

• Install: npm install -g @openai/codex
• Authenticate with the Codex CLI login flow, or provide a valid OpenAI API key.
• Run inside a git repository. For scratch work, create a temporary repo first.
• Use pty=true for interactive Codex commands.

Codex CLI OAuth usually lives under ~/.codex/auth.json. Do not assume Codex is unauthenticated only because OPENAI_API_KEY is missing.

When to Use

• User asks for a second coding agent to implement, review, or investigate.
• Work can be scoped to a repository, branch, or worktree.
• A task benefits from a separate autonomous pass while Gini keeps the main approval, audit, and trace path.

When NOT to Use

• User only needs a small direct edit that Gini can do faster.
• The working directory is not a git repo and the user did not ask for scratch prototyping.
• The request involves secrets, credential files, or destructive commands without explicit approval boundaries.

Quick Tasks

Run a focused one-shot from the target repo:

codex exec "Find why the dashboard test is flaky, patch the smallest fix, and run the targeted test."

Review local changes:

codex exec "Review git diff --stat and git diff for bugs, regressions, and missing tests. Return findings only."

Scratch prototype in a disposable repo:

tmp=$(mktemp -d)
cd "$tmp"
git init
codex exec "Create a tiny Bun CLI that parses a JSON file and prints a summary."

Long-Running Work

For long tasks, launch in the background with a PTY, then poll the process rather than starting duplicate Codex runs.

codex exec --full-auto "Refactor the settings loader. Keep the diff narrow and commit when tests pass."

Use --full-auto only when repository writes are expected and the user has accepted the risk. Avoid --yolo unless the user explicitly asks for it.

Worktree Pattern

Use worktrees for parallel issue fixes so each Codex instance has its own branch and filesystem.

git worktree add -b fix/runtime-health /tmp/gini-runtime-health main
git worktree add -b fix/skills-copy /tmp/gini-skills-copy main

cd /tmp/gini-runtime-health
codex exec --full-auto "Fix the runtime health regression and run the related tests."

cd /tmp/gini-skills-copy
codex exec --full-auto "Add coverage for bundled skill loading changes."

After each run, inspect the diff, run the expected checks, and remove completed worktrees with git worktree remove <path>.

PR Review Pattern

git fetch origin main
codex exec "Review the current branch against origin/main. Prioritize correctness, security, and missing tests."

For a GitHub PR:

gh pr checkout 42
codex exec "Review this PR against origin/main. Return only actionable findings with file and line notes."

Rules

1. Keep Codex scoped to a git repo or throwaway initialized repo.
2. Prefer codex exec "prompt" for one-shot tasks.
3. Use pty=true for interactive Codex sessions.
4. Prefer --full-auto over --yolo for write-heavy work.
5. Monitor long runs before launching another agent on the same branch.
6. Inspect Codex changes before trusting or committing them.