Knowledge Base updated: 2026-11-16
Knowledge Base Index
Orientation
This repository is the OpenAI Codex CLI monorepo. Its highest-level flow is: a user invokes codex, the CLI starts the TUI or another command mode, the core agent runtime talks to model/backend clients, and tool calls execute through policy-controlled sandbox layers while local state and history are persisted.
Main parts:
- npm launcher (
codex-cli/): published@openai/codexwrapper and binary handoff. - Rust workspace (
codex-rs/): CLI, TUI, core agent runtime, tool execution, sandboxing, app server, extensions, clients, and local state. - SDKs (
sdk/): TypeScript and Python SDK/runtime packages shipped with the repo. - Build and release infrastructure: Cargo, pnpm, Bazel, scripts, packaging, and repo-maintenance tooling.
Critical state lives primarily in local Codex home/config/auth stores, rollout/history/thread/state stores, extension/plugin storage, message-board collaboration stores, and external OpenAI/cloud/model-provider services reached through backend clients.
Architecture diagrams
flowchart LR
User[User terminal]
subgraph Packaging
Npm[codex-cli npm package]
Build[repo build and release scripts]
SDK[SDK packages]
end
subgraph RustWorkspace[codex-rs workspace]
CLI[cli entrypoints]
TUI[tui interactive client]
Core[core agent runtime]
Config[config auth local state]
Clients[backend and model clients]
Exec[tool execution sandboxing]
App[app-server and code-mode]
Ext[extensions plugins capabilities]
Collab[collaboration agents message-board]
end
subgraph External
OpenAI[OpenAI/cloud/model services]
OS[local shell filesystem sandbox]
end
User --> Npm --> CLI
User --> CLI
CLI --> TUI --> Core
CLI --> App
Core --> Config
Core --> Clients --> OpenAI
Core --> Exec --> OS
Core --> Ext
Ext --> Collab
App --> Core
SDK --> App
Build --> Npm
Build --> RustWorkspace
Build --> SDK
sequenceDiagram
participant U as User
participant CLI as cli/arg0
participant TUI as tui
participant Core as core runtime
participant Client as backend/model client
participant Exec as exec/sandbox
participant State as history/rollout/state
U->>CLI: codex command
CLI->>TUI: start interactive session
TUI->>Core: submit prompt/input
Core->>State: load context and history
Core->>Client: request model response
Client-->>Core: stream events/tool requests
Core->>Exec: authorize and run tool call
Exec-->>Core: output/status
Core->>State: persist rollout/history
Core-->>TUI: protocol events
TUI-->>U: render transcript and status
flowchart TD
Request[Tool request from core] --> Policy[execpolicy and approvals]
Policy --> Shell[shell-command representation]
Shell --> Server{exec-server?}
Server -->|local| Sandbox[sandboxing facade]
Server -->|server mode| ExecServer[exec-server protocol]
ExecServer --> Sandbox
Sandbox --> Linux[linux/bwrap/mxc sandbox]
Sandbox --> Windows[windows sandbox service]
Sandbox --> FS[file/search/patch helpers]
Linux --> Result[streamed output]
Windows --> Result
FS --> Result
Result --> Core[core protocol event]
flowchart LR
AppClient[app-server client] --> Transport[app-server transport]
Transport --> Daemon[app-server daemon]
Daemon --> Protocol[app-server protocol]
Protocol --> CodeMode[code-mode host/runtime]
CodeMode --> AgentInstance[runtime agent instance]
AgentInstance --> Core[core runtime]
Core --> Exec[tool execution]
Core --> Clients[backend/model clients]
Glossary
- Codex home: Local filesystem area used by Codex for configuration, auth material, history, and state.
- Rollout: The persisted trace/history representation of an agent conversation and its events.
- Exec server: A separate execution service/protocol used to run tool commands outside the main CLI process when configured.
- Code mode: App-server mediated runtime/host flow for embedding or driving Codex agent instances outside the plain terminal UI.
- Message board: Collaboration substrate for agent identity, roles, queues/items, and guardian/reviewer flows.
Codebase-wide invariants
- The primary Rust implementation is organized as a Cargo workspace rooted at codex-rs/Cargo.toml; workspace crates are listed as
membersand internal dependencies point at paths undercodex-rs/**. - The JavaScript package workspace is declared in pnpm-workspace.yaml, with package roots including
codex-cli,codex-rs/responses-api-proxy/npm, andsdk/typescript. - The published npm CLI package exposes the
codexbinary from codex-cli/package.json viabin.codex = bin/codex.js. - Top-level repo formatting and schema maintenance commands are centralized in package.json scripts, while Rust build/test/package behavior is also represented by codex-rs/Cargo.toml, Bazel files, and
scripts/**.
Routing table
-
.npmrc-> docs/repo-and-build-system.md -
.nvmrc-> docs/repo-and-build-system.md -
justfile-> docs/repo-and-build-system.md -
BUILD.bazel-> docs/repo-and-build-system.md -
MODULE.bazel-> docs/repo-and-build-system.md -
.bazel*-> docs/repo-and-build-system.md -
defs.bzl-> docs/repo-and-build-system.md -
rbe.bzl-> docs/repo-and-build-system.md -
bazel/**-> docs/repo-and-build-system.md -
scripts/**-> docs/repo-and-build-system.md -
tools/**-> docs/repo-and-build-system.md -
patches/**-> docs/repo-and-build-system.md -
third_party/**-> docs/repo-and-build-system.md -
workspace_root_test_launcher.*.tpl-> docs/repo-and-build-system.md -
codex-rs/BUILD.bazel-> docs/repo-and-build-system.md -
codex-rs/.cargo/**-> docs/repo-and-build-system.md -
codex-rs/scripts/**-> docs/repo-and-build-system.md -
codex-rs/tools/**-> docs/repo-and-build-system.md -
codex-rs/vendor/**-> docs/repo-and-build-system.md -
codex-cli/**-> docs/codex-cli-npm-launcher.md -
codex-rs/cli/**-> docs/rust-cli-entrypoints.md -
codex-rs/arg0/**-> docs/rust-cli-entrypoints.md -
codex-rs/build-info/**-> docs/rust-cli-entrypoints.md -
codex-rs/install-context/**-> docs/rust-cli-entrypoints.md -
codex-rs/terminal-detection/**-> docs/rust-cli-entrypoints.md -
codex-rs/exec-server-cli/**-> docs/rust-cli-entrypoints.md -
codex-rs/chatgpt/**-> docs/rust-cli-entrypoints.md -
any change to command parsing or process startup behavior -> docs/rust-cli-entrypoints.md
-
codex-rs/tui/**-> docs/tui-interactive-client.md -
codex-rs/ansi-escape/**-> docs/tui-interactive-client.md -
codex-rs/utils/pty/**-> docs/tui-interactive-client.md -
codex-rs/utils/fuzzy-match/**-> docs/tui-interactive-client.md -
codex-rs/utils/head-tail-buffer/**-> docs/tui-interactive-client.md -
codex-rs/utils/output-truncation/**-> docs/tui-interactive-client.md -
codex-rs/utils/sleep-inhibitor/**-> docs/tui-interactive-client.md -
codex-rs/diagnostics/**-> docs/tui-interactive-client.md -
codex-rs/direct-tool-timing/**-> docs/tui-interactive-client.md -
any change to interactive terminal rendering, input handling, transcript display, or TUI diagnostics -> docs/tui-interactive-client.md
-
codex-rs/core/**-> docs/core-agent-runtime.md -
codex-rs/core-api/**-> docs/core-agent-runtime.md -
codex-rs/protocol/**-> docs/core-agent-runtime.md -
codex-rs/prompts/**-> docs/core-agent-runtime.md -
codex-rs/rollout/**-> docs/core-agent-runtime.md -
codex-rs/rollout-trace/**-> docs/core-agent-runtime.md -
codex-rs/history/**-> docs/core-agent-runtime.md -
codex-rs/message-history/**-> docs/core-agent-runtime.md -
codex-rs/thread-store/**-> docs/core-agent-runtime.md -
codex-rs/state/**-> docs/core-agent-runtime.md -
codex-rs/context-fragments/**-> docs/core-agent-runtime.md -
codex-rs/response-debug-context/**-> docs/core-agent-runtime.md -
codex-rs/attachment-store/**-> docs/core-agent-runtime.md -
codex-rs/feedback/**-> docs/core-agent-runtime.md -
codex-rs/analytics/**-> docs/core-agent-runtime.md -
any change to conversation orchestration, agent events, prompt assembly, history, rollout persistence, or protocol event shapes -> docs/core-agent-runtime.md
-
codex-rs/config/**-> docs/config-auth-and-local-state.md -
codex-rs/config-schema/**-> docs/config-auth-and-local-state.md -
codex-rs/codex-home/**-> docs/config-auth-and-local-state.md -
codex-rs/login/**-> docs/config-auth-and-local-state.md -
codex-rs/keyring-store/**-> docs/config-auth-and-local-state.md -
codex-rs/secrets/**-> docs/config-auth-and-local-state.md -
codex-rs/user-verification/**-> docs/config-auth-and-local-state.md -
codex-rs/cloud-config/**-> docs/config-auth-and-local-state.md -
codex-rs/features/**-> docs/config-auth-and-local-state.md -
codex-rs/hooks/**-> docs/config-auth-and-local-state.md -
codex-rs/workload-identity/**-> docs/config-auth-and-local-state.md -
codex-rs/aws-auth/**-> docs/config-auth-and-local-state.md -
codex-rs/worktree/**-> docs/config-auth-and-local-state.md -
codex-rs/git-utils/**-> docs/config-auth-and-local-state.md -
any change to config precedence, auth tokens, keyring behavior, Codex home layout, hooks, feature flags, or local worktree/git helpers -> docs/config-auth-and-local-state.md
-
codex-rs/backend-client/**-> docs/backend-model-and-network-clients.md -
codex-rs/codex-api/**-> docs/backend-model-and-network-clients.md -
codex-rs/codex-client/**-> docs/backend-model-and-network-clients.md -
codex-rs/codex-backend-openapi-models/**-> docs/backend-model-and-network-clients.md -
codex-rs/cloud-client/**-> docs/backend-model-and-network-clients.md -
codex-rs/cloud-tasks/**-> docs/backend-model-and-network-clients.md -
codex-rs/cloud-tasks-client/**-> docs/backend-model-and-network-clients.md -
codex-rs/cloud-tasks-mock-client/**-> docs/backend-model-and-network-clients.md -
codex-rs/http-client/**-> docs/backend-model-and-network-clients.md -
codex-rs/http-headers-helper/**-> docs/backend-model-and-network-clients.md -
codex-rs/model-provider/**-> docs/backend-model-and-network-clients.md -
codex-rs/model-provider-info/**-> docs/backend-model-and-network-clients.md -
codex-rs/models-manager/**-> docs/backend-model-and-network-clients.md -
codex-rs/responses-api-proxy/**-> docs/backend-model-and-network-clients.md -
codex-rs/realtime-webrtc/**-> docs/backend-model-and-network-clients.md -
codex-rs/voice-host/**-> docs/backend-model-and-network-clients.md -
codex-rs/websocket-client/**-> docs/backend-model-and-network-clients.md -
codex-rs/websocket-auth/**-> docs/backend-model-and-network-clients.md -
codex-rs/otel/**-> docs/backend-model-and-network-clients.md -
codex-rs/otel-trace-websocket/**-> docs/backend-model-and-network-clients.md -
codex-rs/network-proxy/**-> docs/backend-model-and-network-clients.md -
codex-rs/lmstudio/**-> docs/backend-model-and-network-clients.md -
codex-rs/ollama/**-> docs/backend-model-and-network-clients.md -
any change to OpenAI/cloud/model-provider APIs, network headers, websocket/realtime transport, local model providers, or tracing transport -> docs/backend-model-and-network-clients.md
-
codex-rs/exec/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/exec-server/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/exec-server-protocol/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/exec-server/tests/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/execpolicy/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/sandboxing/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/linux-sandbox/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/windows-sandbox-rs/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/windows-sandbox-service/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/mxc-sandbox/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/bwrap/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/process-hardening/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/shell-command/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/apply-patch/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/file-system/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/tools/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/file-search/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/file-watcher/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/stdio-to-uds/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/tcp-tunnel/**-> docs/tool-execution-and-sandboxing.md -
codex-rs/uds/**-> docs/tool-execution-and-sandboxing.md -
any change to tool approval, command execution, sandbox policy, shell command modeling, patch application, file search, or streamed tool output -> docs/tool-execution-and-sandboxing.md
-
codex-rs/app-server/**-> docs/app-server-and-code-mode.md -
codex-rs/app-server-client/**-> docs/app-server-and-code-mode.md -
codex-rs/app-server-daemon/**-> docs/app-server-and-code-mode.md -
codex-rs/app-server-protocol/**-> docs/app-server-and-code-mode.md -
codex-rs/app-server-protocol-noop-macros/**-> docs/app-server-and-code-mode.md -
codex-rs/app-server-test-client/**-> docs/app-server-and-code-mode.md -
codex-rs/app-server-transport/**-> docs/app-server-and-code-mode.md -
codex-rs/code-mode/**-> docs/app-server-and-code-mode.md -
codex-rs/code-mode-host/**-> docs/app-server-and-code-mode.md -
codex-rs/code-mode-protocol/**-> docs/app-server-and-code-mode.md -
codex-rs/code-mode-runtime/**-> docs/app-server-and-code-mode.md -
codex-rs/runtime-agent-instance/**-> docs/app-server-and-code-mode.md -
codex-rs/thread-manager-sample/**-> docs/app-server-and-code-mode.md -
any change to app-server daemon/client/protocol/transport, code-mode host/runtime, or runtime agent instance management -> docs/app-server-and-code-mode.md
-
codex-rs/ext/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/plugin/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/plugin-host/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/core-plugin-common/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/core-plugins/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/codex-mcp/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/rmcp-client/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/message-board-mcp/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/connectors/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/skills/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/memories/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/external-agent-migration/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/collaboration-mode-templates/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/mermaid/**-> docs/extensions-plugins-and-capabilities.md -
codex-rs/codex-experimental-api-macros/**-> docs/extensions-plugins-and-capabilities.md -
any change to plugin lifecycle, built-in extensions, MCP integration, skills, memories, connectors, or extension macros -> docs/extensions-plugins-and-capabilities.md
-
codex-rs/agent-graph-store/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/agent-identity/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/agent-roles/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/agent-message-board-client/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/agent-message-board-host/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/message-board/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/guardian-context/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/agent/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/agent-message-board/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/guardian-reviewer/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/guardian-v2/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/guardian-v3/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/git-attribution/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/history-notes/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/items/**-> docs/collaboration-agents-and-message-board.md -
codex-rs/ext/queue/**-> docs/collaboration-agents-and-message-board.md -
any change to agent identities, roles, message-board host/client behavior, graph collaboration storage, guardian/reviewer extensions, queues, items, history notes, or git attribution -> docs/collaboration-agents-and-message-board.md
-
sdk/**-> docs/external-sdks.md -
any change to TypeScript or Python SDK package APIs, generated SDK types, runtime helpers, or SDK build/test configuration -> docs/external-sdks.md