# openai/codex architecture

> Architecture diagram of the GitHub repository openai/codex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/codex
- Repository: https://github.com/openai/codex
- Video tour (about a minute): https://gitdiagram.com/openai/codex/video

## Overview

Codex CLI is a local coding agent: a user starts a session, the agent works with repository context and tools, and results are presented in the terminal. The repository also includes MCP server integrations, extensible plugins, and app-server interfaces. The source index and excerpts establish several MCP module relationships; the broader session-to-model and CLI-to-terminal flow is described only at product level here, so those links are marked unverified rather than inferred from module names.

Main entry points: [`codex-rs/codex-mcp/src/rmcp_client.rs`](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/rmcp_client.rs) (RMCP client), [`codex-rs/codex-mcp/src/runtime.rs`](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/runtime.rs) (MCP runtime), [`codex-rs/core/src/session/session.rs`](https://github.com/openai/codex/blob/main/codex-rs/core/src/session/session.rs) (Agent session), [`codex-rs/core-plugins/src/manager.rs`](https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/manager.rs) (Plugin manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and interaction"]
  node_cli["CLI entry<br/>[main.rs]"]
  node_terminal["Terminal UI<br/>[app.rs]"]
end

subgraph group_agent["Agent sessions"]
  node_thread["Thread manager<br/>[thread_manager.rs]"]
  node_session["Agent session<br/>[session.rs]"]
  node_execution["Command execution<br/>[process_manager.rs]"]
end

subgraph group_mcp["MCP integrations"]
  node_mcp_runtime["MCP runtime<br/>[runtime.rs]"]
  node_mcp_connections["Connection manager"]
  node_mcp_client["RMCP client<br/>[rmcp_client.rs]"]
  node_mcp_server["Server config<br/>[server.rs]"]
  node_mcp_tools["Tool catalog<br/>[tools.rs]"]
  node_mcp_catalog["Client tool catalog"]
  node_mcp_auth["MCP auth<br/>[auth.rs]"]
  node_mcp_elicitation["User elicitation<br/>[elicitation.rs]"]
  node_mcp_oauth["MCP OAuth<br/>[oauth.rs]"]
end

subgraph group_extensions["Plugins"]
  node_plugin_manager["Plugin manager<br/>[manager.rs]"]
  node_plugin_loader["Plugin loader<br/>[loader.rs]"]
  node_plugin_remote["Remote plugins<br/>[remote.rs]"]
end

subgraph group_interfaces["App interfaces"]
  node_app_server["App server"]
  node_protocol["App protocol"]
end

node_user(("Developer"))

node_user -.->|"starts"| node_cli
node_cli -.->|"starts session"| node_thread
node_thread -.->|"manages"| node_session
node_session -.->|"streams results"| node_terminal
node_session -.->|"runs commands"| node_execution
node_session -.->|"uses tools"| node_mcp_runtime
node_mcp_runtime -->|"manages"| node_mcp_connections
node_mcp_runtime -->|"starts clients"| node_mcp_client
node_mcp_runtime -->|"publishes config"| node_mcp_server
node_mcp_client -->|"connects to"| node_mcp_server
node_mcp_client -->|"filters tools"| node_mcp_tools
node_mcp_client -->|"updates catalog"| node_mcp_catalog
node_mcp_client -->|"uses auth"| node_mcp_auth
node_mcp_client -->|"requests input"| node_mcp_elicitation
node_mcp_client -.->|"uses OAuth"| node_mcp_oauth
node_plugin_manager -->|"loads plugins"| node_plugin_loader
node_plugin_manager -->|"refreshes remotes"| node_plugin_remote
node_plugin_manager -.->|"configures tools"| node_mcp_runtime
node_app_server -.->|"uses protocol"| node_protocol
node_user -.->|"may use app"| node_app_server

click node_cli "https://github.com/openai/codex/blob/main/codex-rs/cli/src/main.rs"
click node_terminal "https://github.com/openai/codex/blob/main/codex-rs/tui/src/app.rs"
click node_thread "https://github.com/openai/codex/blob/main/codex-rs/core/src/thread_manager.rs"
click node_session "https://github.com/openai/codex/blob/main/codex-rs/core/src/session/session.rs"
click node_execution "https://github.com/openai/codex/blob/main/codex-rs/core/src/unified_exec/process_manager.rs"
click node_mcp_runtime "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/runtime.rs"
click node_mcp_connections "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/connection_manager.rs"
click node_mcp_client "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/rmcp_client.rs"
click node_mcp_server "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/server.rs"
click node_mcp_tools "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/tools.rs"
click node_mcp_catalog "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/client_tool_catalog.rs"
click node_mcp_auth "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/auth.rs"
click node_mcp_elicitation "https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/elicitation.rs"
click node_plugin_manager "https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/manager.rs"
click node_plugin_loader "https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/loader.rs"
click node_plugin_remote "https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/remote.rs"
click node_app_server "https://github.com/openai/codex/tree/main/codex-rs/app-server/src"
click node_protocol "https://github.com/openai/codex/tree/main/codex-rs/app-server-protocol"
click node_mcp_oauth "https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/oauth.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_terminal toneBlue
class node_thread,node_session,node_execution toneAmber
class node_mcp_runtime,node_mcp_connections,node_mcp_client,node_mcp_server,node_mcp_tools,node_mcp_catalog,node_mcp_auth,node_mcp_elicitation,node_mcp_oauth toneMint
class node_plugin_manager,node_plugin_loader,node_plugin_remote toneRose
class node_app_server,node_protocol,node_user toneIndigo
```

## Components

### CLI and interaction

- [CLI entry](https://github.com/openai/codex/blob/main/codex-rs/cli/src/main.rs): `codex-rs/cli/src/main.rs`
- [Terminal UI](https://github.com/openai/codex/blob/main/codex-rs/tui/src/app.rs): `codex-rs/tui/src/app.rs`

### Agent sessions

- [Thread manager](https://github.com/openai/codex/blob/main/codex-rs/core/src/thread_manager.rs): `codex-rs/core/src/thread_manager.rs`
- [Agent session](https://github.com/openai/codex/blob/main/codex-rs/core/src/session/session.rs): `codex-rs/core/src/session/session.rs`
- [Command execution](https://github.com/openai/codex/blob/main/codex-rs/core/src/unified_exec/process_manager.rs): `codex-rs/core/src/unified_exec/process_manager.rs`

### MCP integrations

- [MCP runtime](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/runtime.rs): `codex-rs/codex-mcp/src/runtime.rs`
- [Connection manager](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/connection_manager.rs): `codex-rs/codex-mcp/src/connection_manager.rs`
- [RMCP client](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/rmcp_client.rs): `codex-rs/codex-mcp/src/rmcp_client.rs`
- [Server config](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/server.rs): `codex-rs/codex-mcp/src/server.rs`
- [Tool catalog](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/tools.rs): `codex-rs/codex-mcp/src/tools.rs`
- [Client tool catalog](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/client_tool_catalog.rs): `codex-rs/codex-mcp/src/client_tool_catalog.rs`
- [MCP auth](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/auth.rs): `codex-rs/codex-mcp/src/auth.rs`
- [User elicitation](https://github.com/openai/codex/blob/main/codex-rs/codex-mcp/src/elicitation.rs): `codex-rs/codex-mcp/src/elicitation.rs`
- [MCP OAuth](https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/oauth.rs): `codex-rs/rmcp-client/src/oauth.rs`

### Plugins

- [Plugin manager](https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/manager.rs): `codex-rs/core-plugins/src/manager.rs`
- [Plugin loader](https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/loader.rs): `codex-rs/core-plugins/src/loader.rs`
- [Remote plugins](https://github.com/openai/codex/blob/main/codex-rs/core-plugins/src/remote.rs): `codex-rs/core-plugins/src/remote.rs`

### App interfaces

- [App server](https://github.com/openai/codex/tree/main/codex-rs/app-server/src): `codex-rs/app-server/src`
- [App protocol](https://github.com/openai/codex/tree/main/codex-rs/app-server-protocol): `codex-rs/app-server-protocol`

### Other components

- **Developer**

## Connections

- Developer → CLI entry: starts (evidence: `README.md`)
- CLI entry → Thread manager: starts session
- Thread manager → Agent session: manages
- Agent session → Terminal UI: streams results
- Agent session → Command execution: runs commands
- Agent session → MCP runtime: uses tools
- MCP runtime → Connection manager: manages (evidence: `codex-rs/codex-mcp/src/runtime.rs`)
- MCP runtime → RMCP client: starts clients (evidence: `codex-rs/codex-mcp/src/runtime.rs`)
- MCP runtime → Server config: publishes config (evidence: `codex-rs/codex-mcp/src/runtime.rs`)
- RMCP client → Server config: connects to (evidence: `codex-rs/codex-mcp/src/rmcp_client.rs`)
- RMCP client → Tool catalog: filters tools (evidence: `codex-rs/codex-mcp/src/rmcp_client.rs`)
- RMCP client → Client tool catalog: updates catalog (evidence: `codex-rs/codex-mcp/src/rmcp_client.rs`)
- RMCP client → MCP auth: uses auth (evidence: `codex-rs/codex-mcp/src/rmcp_client.rs`)
- RMCP client → User elicitation: requests input (evidence: `codex-rs/codex-mcp/src/rmcp_client.rs`)
- RMCP client → MCP OAuth: uses OAuth
- Plugin manager → Plugin loader: loads plugins
- Plugin manager → Remote plugins: refreshes remotes
- Plugin manager → MCP runtime: configures tools
- App server → App protocol: uses protocol
- Developer → App server: may use app (evidence: `README.md`)
