# zeromac/codex architecture

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

- Interactive diagram: https://gitdiagram.com/zeromac/codex
- Repository: https://github.com/zeromac/codex

## Overview

Codex CLI is a local coding agent: a user starts a session, supplies a coding task, and receives streamed responses and workspace changes. The visible tree indicates a Rust runtime with terminal and app-server interfaces, thread and model management, command execution with sandboxing, authentication, and optional MCP/plugin integrations. The README establishes the product and local workflow; most Rust implementation files were not sampled, so the graph uses tree-supported module paths and omits uncertain internal call links.

Main entry points: [`codex-rs/core/src`](https://github.com/zeromac/codex/tree/main/codex-rs/core/src) (Thread manager), [`codex-rs/tui/src`](https://github.com/zeromac/codex/tree/main/codex-rs/tui/src) (Terminal UI), [`codex-rs/core/src/unified_exec/process_manager.rs`](https://github.com/zeromac/codex/blob/main/codex-rs/core/src/unified_exec/process_manager.rs) (Command execution), [`codex-rs/codex-mcp/src`](https://github.com/zeromac/codex/tree/main/codex-rs/codex-mcp/src) (MCP connections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI launcher<br/>[codex.js]"]
  node_terminal["Terminal UI"]
  node_appserver["App server"]
  node_protocol["App protocol"]
end

subgraph group_agent["Agent runtime"]
  node_threads["Thread manager"]
  node_streaming["Stream rendering<br/>[controller.rs]"]
  node_memory["Conversation memory<br/>[storage.rs]"]
end

subgraph group_execution["Workspace execution"]
  node_exec["Command execution<br/>[process_manager.rs]"]
  node_sandbox["Sandbox policy<br/>[manager.rs]"]
  node_workspace[("Local workspace")]
end

subgraph group_services["Accounts and models"]
  node_models["Model manager"]
  node_auth["Authentication<br/>[storage.rs]"]
  node_analytics["Analytics"]
end

subgraph group_extensions["Extensions"]
  node_mcp["MCP connections"]
  node_plugins["Plugins"]
end

node_user(("User"))
node_model_service{{"Model service"}}
node_mcp_services{{"MCP servers"}}

node_user -->|"starts"| node_cli
node_cli -->|"opens"| node_terminal
node_user -->|"enters task"| node_terminal
node_terminal -->|"submits task"| node_threads
node_threads -->|"streams response"| node_streaming
node_streaming -->|"renders"| node_terminal
node_threads -->|"requests model"| node_models
node_models -->|"fetches models"| node_model_service
node_threads -->|"runs commands"| node_exec
node_exec -->|"applies policy"| node_sandbox
node_exec -->|"reads and writes"| node_workspace
node_threads -->|"stores memories"| node_memory
node_threads -->|"uses credentials"| node_auth
node_threads -.->|"records events"| node_analytics
node_threads -.->|"uses tools"| node_mcp
node_mcp -.->|"connects"| node_mcp_services
node_plugins -.->|"configures servers"| node_mcp
node_user -.->|"connects"| node_appserver
node_appserver -->|"exchanges messages"| node_protocol

click node_cli "https://github.com/zeromac/codex/blob/main/codex-cli/bin/codex.js"
click node_terminal "https://github.com/zeromac/codex/tree/main/codex-rs/tui/src"
click node_appserver "https://github.com/zeromac/codex/tree/main/codex-rs/app-server-daemon/src"
click node_protocol "https://github.com/zeromac/codex/tree/main/codex-rs/app-server-protocol/src"
click node_threads "https://github.com/zeromac/codex/tree/main/codex-rs/core/src"
click node_streaming "https://github.com/zeromac/codex/blob/main/codex-rs/tui/src/streaming/controller.rs"
click node_memory "https://github.com/zeromac/codex/blob/main/codex-rs/memories/write/src/storage.rs"
click node_models "https://github.com/zeromac/codex/tree/main/codex-rs/models-manager/src"
click node_auth "https://github.com/zeromac/codex/blob/main/codex-rs/login/src/auth/storage.rs"
click node_analytics "https://github.com/zeromac/codex/tree/main/codex-rs/analytics/src"
click node_exec "https://github.com/zeromac/codex/blob/main/codex-rs/core/src/unified_exec/process_manager.rs"
click node_sandbox "https://github.com/zeromac/codex/blob/main/codex-rs/sandboxing/src/manager.rs"
click node_mcp "https://github.com/zeromac/codex/tree/main/codex-rs/codex-mcp/src"
click node_plugins "https://github.com/zeromac/codex/tree/main/codex-rs/core-plugins/src"

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,node_appserver,node_protocol,node_user toneBlue
class node_threads,node_streaming,node_memory toneAmber
class node_exec,node_sandbox,node_workspace,node_mcp_services toneMint
class node_models,node_auth,node_analytics toneRose
class node_mcp,node_plugins,node_model_service toneIndigo
```

## Components

### User interfaces

- [CLI launcher](https://github.com/zeromac/codex/blob/main/codex-cli/bin/codex.js): `codex-cli/bin/codex.js`
- [Terminal UI](https://github.com/zeromac/codex/tree/main/codex-rs/tui/src): `codex-rs/tui/src`
- [App server](https://github.com/zeromac/codex/tree/main/codex-rs/app-server-daemon/src): `codex-rs/app-server-daemon/src`
- [App protocol](https://github.com/zeromac/codex/tree/main/codex-rs/app-server-protocol/src): `codex-rs/app-server-protocol/src`

### Agent runtime

- [Thread manager](https://github.com/zeromac/codex/tree/main/codex-rs/core/src): `codex-rs/core/src`
- [Stream rendering](https://github.com/zeromac/codex/blob/main/codex-rs/tui/src/streaming/controller.rs): `codex-rs/tui/src/streaming/controller.rs`
- [Conversation memory](https://github.com/zeromac/codex/blob/main/codex-rs/memories/write/src/storage.rs): `codex-rs/memories/write/src/storage.rs`

### Workspace execution

- [Command execution](https://github.com/zeromac/codex/blob/main/codex-rs/core/src/unified_exec/process_manager.rs): `codex-rs/core/src/unified_exec/process_manager.rs`
- [Sandbox policy](https://github.com/zeromac/codex/blob/main/codex-rs/sandboxing/src/manager.rs): `codex-rs/sandboxing/src/manager.rs`
- **Local workspace**

### Accounts and models

- [Model manager](https://github.com/zeromac/codex/tree/main/codex-rs/models-manager/src): `codex-rs/models-manager/src`
- [Authentication](https://github.com/zeromac/codex/blob/main/codex-rs/login/src/auth/storage.rs): `codex-rs/login/src/auth/storage.rs`
- [Analytics](https://github.com/zeromac/codex/tree/main/codex-rs/analytics/src): `codex-rs/analytics/src`

### Extensions

- [MCP connections](https://github.com/zeromac/codex/tree/main/codex-rs/codex-mcp/src): `codex-rs/codex-mcp/src`
- [Plugins](https://github.com/zeromac/codex/tree/main/codex-rs/core-plugins/src): `codex-rs/core-plugins/src`

### Other components

- **User**
- **Model service**
- **MCP servers**

## Connections

- User → CLI launcher: starts
- CLI launcher → Terminal UI: opens
- User → Terminal UI: enters task
- Terminal UI → Thread manager: submits task
- Thread manager → Stream rendering: streams response
- Stream rendering → Terminal UI: renders
- Thread manager → Model manager: requests model
- Model manager → Model service: fetches models
- Thread manager → Command execution: runs commands
- Command execution → Sandbox policy: applies policy
- Command execution → Local workspace: reads and writes
- Thread manager → Conversation memory: stores memories
- Thread manager → Authentication: uses credentials
- Thread manager → Analytics: records events
- Thread manager → MCP connections: uses tools
- MCP connections → MCP servers: connects
- Plugins → MCP connections: configures servers
- User → App server: connects
- App server → App protocol: exchanges messages