f0911e65ed
New AI.dev/CHEATSHEETS/ reference set for delegating to terminal AI agents: - README.md: comparison matrix, 'which CLI?' decision guide, official-docs links, cross-CLI rules + ByteLyst environment facts - devin-cli.md: sessions, --permission-mode dangerous vs --sandbox, resume, the sandbox-stall gotcha, delegation pattern + prompt preamble - claude-code-cli.md: REPL/-p/-c/--resume, permission+plan modes, slash commands, MCP - codex-cli.md: interactive vs codex exec for CI, sandbox x approval matrix, config.toml Flags hedged with 'confirm via --help' since they drift between versions; durable value is the ByteLyst workflow. Does not reference .devin/config.local.json contents.
129 lines
6.3 KiB
Markdown
129 lines
6.3 KiB
Markdown
# 🟢 Codex CLI — Cheat Sheet
|
|
|
|
> **What it is:** OpenAI's **Codex CLI** — an open-source terminal coding agent that
|
|
> edits files and runs commands inside a built-in sandbox, interactively or as a
|
|
> scriptable one-shot (`codex exec`).
|
|
> **Best for:** Fast local edits, and **automation** — `codex exec` slots cleanly into
|
|
> CI / Gitea Actions and one-shot scripts.
|
|
> **Per-repo rules:** reads `AGENTS.md` (merged with `~/.codex/AGENTS.md` and any
|
|
> project-local `AGENTS.md`).
|
|
> **In this repo:** delegation examples live under
|
|
> [`docs/ecosystem/delegation/codex/`](../../docs/ecosystem/delegation/codex/) and
|
|
> [`docs/CODEX_RESUME_PROMPT.md`](../../docs/CODEX_RESUME_PROMPT.md).
|
|
|
|
> ⚠️ **Flags/modes drift between versions.** Confirm with `codex --help`.
|
|
>
|
|
> **Official docs:** <https://developers.openai.com/codex/cli> · source: <https://github.com/openai/codex>
|
|
|
|
---
|
|
|
|
## Install & auth
|
|
|
|
```bash
|
|
npm install -g @openai/codex # or: brew install codex
|
|
codex --version
|
|
codex login # ChatGPT sign-in, or set OPENAI_API_KEY
|
|
```
|
|
|
|
- Config & state live under `~/.codex/` (notably `~/.codex/config.toml`).
|
|
|
|
## Launching
|
|
|
|
```bash
|
|
codex # interactive TUI in the current dir
|
|
codex "add a vitest for src/lib/utils.ts" # seed the first instruction
|
|
codex exec "run the test suite and fix failures" # non-interactive one-shot (scripts/CI)
|
|
codex resume # resume a previous session
|
|
```
|
|
|
|
## Approval + sandbox modes
|
|
|
|
Codex couples **what it can touch** (sandbox) with **when it asks** (approvals).
|
|
|
|
| Flag | Meaning |
|
|
| ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
| `--sandbox read-only` | Can read; no writes, no commands |
|
|
| `--sandbox workspace-write` | Can edit the working dir + run commands in it (default-ish) |
|
|
| `--sandbox danger-full-access` | No sandbox restrictions |
|
|
| `--ask-for-approval untrusted` \| `on-failure` \| `on-request` \| `never` | When to prompt you |
|
|
| `--full-auto` | Convenience: low-friction auto (workspace-write + minimal prompts) |
|
|
| `--dangerously-bypass-approvals-and-sandbox` | **No approvals, no sandbox** (CI/throwaway only) |
|
|
|
|
```bash
|
|
codex --full-auto # everyday autonomy, still sandboxed
|
|
codex --sandbox workspace-write --ask-for-approval on-failure
|
|
codex exec --dangerously-bypass-approvals-and-sandbox "..." # CI only, isolated runner
|
|
```
|
|
|
|
> 🧠 The sandbox is **built in** (unlike Devin's optional `--sandbox`). For ByteLyst,
|
|
> `workspace-write` is fine for single-package work, but cross-package `workspace:*`
|
|
> builds and the corp proxy / Gitea tunnel may need broader access — prefer running from
|
|
> the monorepo root and, if installs fail, loosen the sandbox rather than fighting it.
|
|
|
|
## Config (`~/.codex/config.toml`)
|
|
|
|
```toml
|
|
model = "..." # default model
|
|
approval_policy = "on-failure"
|
|
sandbox_mode = "workspace-write"
|
|
# [mcp_servers.*] # wire external tools via MCP
|
|
```
|
|
|
|
Project-level `AGENTS.md` is layered on top of `~/.codex/AGENTS.md`.
|
|
|
|
## `codex exec` for automation (the high-value mode)
|
|
|
|
```bash
|
|
# One-shot, non-interactive — perfect for Gitea Actions / scripts:
|
|
codex exec "typecheck the repo and fix any TS errors" \
|
|
--sandbox workspace-write --ask-for-approval never
|
|
```
|
|
|
|
- Deterministic, no TUI; exits with a status you can gate CI on.
|
|
- Pair with a tight prompt + explicit verify commands (see below).
|
|
|
|
## ByteLyst workflow
|
|
|
|
Lead with the shared guardrails (Codex reads `AGENTS.md`, but restate scope):
|
|
|
|
```text
|
|
Follow AGENTS.md + AI.dev/SKILLS/agent-behavior-guidelines.md.
|
|
Scope: <paths> only. Tests are sacred. No console.log. productId on Cosmos docs.
|
|
Verify: pnpm --filter <pkg> typecheck && ... test && ... build (next build --webpack).
|
|
pnpm workspace; @bytelyst/* via workspace:*. Conventional commits, one per change.
|
|
Only mark done after verify passes; never fabricate results.
|
|
```
|
|
|
|
- Start in `read-only` for a plan, then switch to `workspace-write` to execute.
|
|
- Reserve `--dangerously-bypass-approvals-and-sandbox` for the isolated CI runner.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Fix |
|
|
| ------------------------------------- | ------------------------------------------------------------------------------- |
|
|
| "permission denied" writing files | Sandbox is `read-only`; use `--sandbox workspace-write` |
|
|
| Can't build `@bytelyst/*` deps | Sandbox can't see sibling `packages/*` — run from monorepo root, loosen sandbox |
|
|
| Network/registry errors | Corp proxy must be active; workspace deps avoid the registry |
|
|
| `next build` fails (Turbopack) | Use `next build --webpack` |
|
|
| Non-interactive run hangs on a prompt | Add `--ask-for-approval never` to `codex exec` |
|
|
|
|
## Quick-reference card
|
|
|
|
```text
|
|
codex # interactive
|
|
codex "..." # seed an instruction
|
|
codex exec "..." # one-shot (CI/scripts)
|
|
codex resume # resume session
|
|
--sandbox read-only|workspace-write|danger-full-access
|
|
--ask-for-approval untrusted|on-failure|on-request|never
|
|
--full-auto # convenient autonomy (still sandboxed)
|
|
~/.codex/config.toml # defaults: model, approval_policy, sandbox_mode
|
|
```
|
|
|
|
---
|
|
|
|
**Related:** [`devin-cli.md`](./devin-cli.md) · [`claude-code-cli.md`](./claude-code-cli.md) ·
|
|
[`../PROMPTS/`](../PROMPTS/) · [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md)
|
|
|
|
_Last updated: 2026-05-28 · verify flags against your installed version (`codex --help`)._
|