|
4 | 4 |
|
5 | 5 | > See `git log` for full commit history. This file records user-facing major updates. |
6 | 6 |
|
| 7 | +## Late April 2026 · OpenAI Codex CLI Guide Added |
| 8 | + |
| 9 | +### 🆕 New Tool: Codex CLI (now 10 tools total) |
| 10 | + |
| 11 | +**📂 [`codex/`](codex/) — OpenAI's open-source terminal agent (Rust, Apache-2.0)** |
| 12 | +- Verified against v0.125.0 (2026-04-24) and `developers.openai.com/codex` official docs |
| 13 | +- Full coverage: core concepts / install & auth / AGENTS.md discovery chain / Approval & Sandbox dual knobs / TOML subagents / MCP / Skills / Plan Mode |
| 14 | +- Side-by-side comparison with Claude Code (sandbox internals, pricing model, sweet spots) |
| 15 | +- 10 common pitfalls (CI hangs on approval prompt, config not taking effect, duplicate installs, etc.) |
| 16 | +- Templates: `AGENTS.md` + `config.toml` (with 4 profiles) + `agent-explorer.toml` |
| 17 | + |
| 18 | +### 🔄 Index Sync |
| 19 | + |
| 20 | +- **README.md / README.en.md**: "9 tools" → "10 tools", tool table now includes Codex CLI, profile-based reading paths add "Already on ChatGPT Plus/Pro" |
| 21 | +- **cheatsheet.md / cheatsheet.en.md**: capability matrix gets a Codex column plus a new "Sandbox" row, config-file table gets AGENTS.md, commands cheat sheet gets a Codex section, decision flow and combo recommendations both updated |
| 22 | + |
| 23 | +### 🔬 Second-pass source-code verification |
| 24 | + |
| 25 | +Before publishing, the guide was cross-checked directly against `codex-rs` source (`utils/cli/src/shared_options.rs`, `tui/src/cli.rs`, `exec/src/cli.rs`, `cli/src/main.rs`, `models-manager/models.json`). Six factual issues were caught and fixed: |
| 26 | + |
| 27 | +1. **Linux sandbox**: `bubblewrap` → `Landlock` kernel LSM (`debug_sandbox.rs` imports `codex_sandboxing::landlock`) |
| 28 | +2. **`--full-auto` removed**: source ships a migration warning *"`--full-auto` is deprecated; use `--sandbox workspace-write` instead."* — every example switched |
| 29 | +3. **`--output-format json` does not exist**: the real flag is `--json` (emits JSONL, not a single JSON object) |
| 30 | +4. **`/side` does not exist**: never appeared in `slash_commands` docs — removed; replaced with real ones (`/diff`, `/mention`, `/debug-config`, `/new`, `/clear`) |
| 31 | +5. **`codex config path` / `codex config validate` do not exist**: there's no `config` subcommand — the right diagnostic is the TUI `/debug-config` slash command |
| 32 | +6. **Added `--yolo` and `--add-dir`**: verified in source as the current recommended danger/expansion flags |
| 33 | + |
| 34 | +Model names verified: `gpt-5.5` / `gpt-5.4` / `gpt-5.3-codex` all present in the canonical `models-manager/models.json` list. |
| 35 | + |
| 36 | +### 🔬 Fourth-pass schema-level verification (config / subagent TOML structures) |
| 37 | + |
| 38 | +Cross-checked against the actual Rust struct definitions (`config_toml.rs::ConfigToml`, `profile_toml.rs::ConfigProfile`, `config_toml.rs::AgentsToml/AgentRoleToml`, `core/src/config/agent_roles.rs::RawAgentRoleFileToml`): |
| 39 | + |
| 40 | +- **`web_search` is a top-level key** (valid values `disabled`/`cached`/`live`), not under `[features]`; template fixed |
| 41 | +- **`multi_agent` is not a simple `[features]` bool** (multi-agent uses its own `[multi_agent_v2]` structure); template field removed |
| 42 | +- **Subagent TOML fields** = `RawAgentRoleFileToml` flattens all of `ConfigToml`, so `name` / `description` / `developer_instructions` / `model` / `model_reasoning_effort` / `sandbox_mode` / `approval_policy` are all valid; `#[serde(deny_unknown_fields)]` rejects typos at startup |
| 43 | +- **`model_reasoning_effort` valid values**: `none` / `minimal` / `low` / `medium` (default) / `high` / `xhigh` (source: `protocol/src/openai_models.rs::ReasoningEffort`) |
| 44 | +- **`[agents]` concurrency keys**: `max_threads` / `max_depth` / `job_max_runtime_seconds` / `interrupt_message` match the `AgentsToml` struct |
| 45 | +- **`AGENTS_MD_MAX_BYTES = 32 * 1024`** (i.e. 32 KiB) — default verified directly in source |
| 46 | + |
| 47 | +### 📚 v2 content expansion (based on high-star community guides) |
| 48 | + |
| 49 | +After studying [RoggeOhta/awesome-codex-cli](https://github.com/RoggeOhta/awesome-codex-cli) (280+ resources) and [shanraisshan/codex-cli-best-practice](https://github.com/shanraisshan/codex-cli-best-practice) (50 battle-tested tips), four real features that v1 missed have been added: |
| 50 | + |
| 51 | +- **Real Skill folder structure**: v1 incorrectly described it as a single `SKILL.md` file; source `core-skills/loader.rs` confirms it's a **directory** with optional `references/`, `scripts/`, `examples/`, `agents/openai.yaml`. Canonical path is `~/.agents/skills/` (`~/.codex/skills/` is deprecated). Added the `$skill-name` explicit invocation syntax. |
| 52 | +- **Hooks** (beta): 6 events — `PreToolUse` / `PermissionRequest` / `PostToolUse` / `SessionStart` / `UserPromptSubmit` / `Stop`. Source engine is named `ClaudeHooksEngine` — the JSON schema reuses Claude Code's `hooks.json` directly, zero-change migration. |
| 53 | +- **Memories** (beta): `/memories` slash command + `[memories] no_memories_if_mcp_or_web_search` safety toggle. |
| 54 | +- **Plugins / Marketplace** (v0.121.0+): `codex plugin marketplace add/upgrade/remove`, TUI `/plugins`. |
| 55 | +- **Fast Mode**: `/fast on|off|status`, gpt-5.4 at 1.5× speed / 2× credits. |
| 56 | + |
| 57 | +A new "High-Signal Prompting & Workflow Patterns" section consolidates 5 buckets of community wisdom (prompting / planning / AGENTS.md / multi-agent / debugging). The References section now lists 6 high-star community indexes and 4 mainstream workflow frameworks (Superpowers / Spec Kit / oh-my-codex / Compound Engineering). |
| 58 | + |
| 59 | +New [`templates/SKILL.md`](codex/templates/SKILL.md) template (with trigger-style description + Gotchas pattern). |
| 60 | + |
| 61 | +### 🔬 Sixth-pass source verification + v3 content additions |
| 62 | + |
| 63 | +Read the `codex-rs/tui/src/slash_command.rs::SlashCommand` enum directly (46 real slash commands) and caught a third-pass over-correction: |
| 64 | + |
| 65 | +- **`/side` is a real command** ("start a side conversation in an ephemeral fork") — round 3 incorrectly removed it based on a WebFetch summary; restored |
| 66 | +- **`/fast` is in the enum** ("toggle Fast mode to enable fastest inference with increased plan usage") — v2 addition was correct |
| 67 | +- **Slash command table expanded to 18 entries**: added `/skills`, `/memories`, `/plugins`, `/apps`, `/goal`, `/rename`, `/feedback`, `/approvals`, etc. |
| 68 | + |
| 69 | +`MemoriesToml` source confirms the canonical field is **`disable_on_external_context`**, with `no_memories_if_mcp_or_web_search` as its serde alias (backward-compat). All docs updated to use the canonical name. |
| 70 | + |
| 71 | +Four new feature sections added (each verified in source): |
| 72 | + |
| 73 | +- **§13 OSS local models** — `--oss --local-provider lmstudio|ollama` (from `utils/oss/src/lib.rs`), fully offline + zero API cost |
| 74 | +- **§14 Official GitHub Action recipe** — `openai/codex-action@v1` (Apache-2.0, 953 stars) with a complete PR-auto-review workflow YAML |
| 75 | +- **§15 Codex as an MCP server** — `codex mcp-server` exposes `codex()` and `codex-reply()` tools for reverse integration with other agents |
| 76 | +- **§16 Rules / Execpolicy** — Starlark DSL (`prefix_rule()` + `host_executable()`), validate offline with `codex execpolicy check` |
| 77 | + |
| 78 | +--- |
| 79 | + |
7 | 80 | ## 2026-04 · Major Update: From "Tool Tutorials" to "Full Hands-On Handbook" |
8 | 81 |
|
9 | 82 | ### 🆕 New Modules |
|
0 commit comments