# 0xsero/codex-local architecture

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

- Interactive diagram: https://gitdiagram.com/0xsero/codex-local
- Repository: https://github.com/0xsero/codex-local

## Overview

Codex-Local is an interactive coding-agent CLI, extended for configurable providers and multi-agent work. The main workflow starts at the CLI, accepts a prompt through the terminal UI, runs a conversation using the model and tool system, and presents streamed results. Tool handlers cover repository inspection and modification, command execution, and external MCP tools; agents can be spawned and report progress. The tree and excerpts support the principal entry points and internal layers; several feature links reflect README documentation rather than inspected implementation.

Main entry points: [`codex-rs/core/src/conversation_manager.rs`](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/conversation_manager.rs) (Conversation manager), [`codex-rs/core/src/codex_conversation.rs`](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/codex_conversation.rs) (Agent conversation), [`codex-rs/core/src/tools/handlers/mod.rs`](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/handlers/mod.rs) (Tool handlers), [`codex-rs/tui/src/chatwidget.rs`](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/tui/src/chatwidget.rs) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Interface"]
  node_cli["CLI dispatch<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[app.rs]"]
  node_chatui["Chat interface<br/>[chatwidget.rs]"]
  node_stream["Stream rendering<br/>[controller.rs]"]
end

subgraph group_conversation["Agent Runtime"]
  node_config["Configuration<br/>[config.rs]"]
  node_manager["Conversation manager"]
  node_engine["Agent conversation"]
  node_client["Model client<br/>[client.rs]"]
  node_history[("Session history<br/>[recorder.rs]")]
end

subgraph group_tools["Tools and Execution"]
  node_registry["Tool registry<br/>[registry.rs]"]
  node_router["Tool router<br/>[router.rs]"]
  node_handlers["Tool handlers<br/>[mod.rs]"]
  node_exec["Command execution<br/>[session_manager.rs]"]
  node_sandbox["Sandbox controls<br/>[sandbox.rs]"]
end

subgraph group_extensions["Agents and Integrations"]
  node_agenttools["Agent tools<br/>[spawn_agent.rs]"]
  node_bridge["Child agent bridge"]
  node_orchestrator["Agent orchestration<br/>[runtime.rs]"]
  node_mcpmanager["MCP connections"]
  node_login["Authentication<br/>[auth.rs]"]
  node_otel["Telemetry events"]
end

node_user(("CLI user"))
node_model(("Model provider"))
node_mcpserver(("MCP servers"))

node_user -->|"starts command"| node_cli
node_cli -->|"launches UI"| node_tui
node_tui -->|"routes events"| node_chatui
node_chatui -->|"submits prompt"| node_manager
node_chatui -->|"renders deltas"| node_stream
node_manager -->|"uses settings"| node_config
node_manager -->|"spawns conversation"| node_engine
node_engine -->|"requests response"| node_client
node_client -->|"sends requests"| node_model
node_manager -->|"resumes sessions"| node_history
node_engine -->|"records rollout"| node_history
node_engine -->|"loads tools"| node_registry
node_registry -->|"dispatches tools"| node_router
node_router -->|"routes calls"| node_handlers
node_handlers -->|"runs commands"| node_exec
node_exec -->|"applies isolation"| node_sandbox
node_handlers -->|"invokes MCP tools"| node_mcpmanager
node_mcpmanager -->|"calls tools"| node_mcpserver
node_handlers -->|"handles agent calls"| node_agenttools
node_agenttools -->|"spawns agents"| node_orchestrator
node_orchestrator -->|"creates conversations"| node_manager
node_agenttools -->|"reports progress"| node_bridge
node_manager -->|"uses credentials"| node_login
node_engine -->|"emits events"| node_otel

click node_cli "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/cli/src/main.rs"
click node_tui "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/tui/src/app.rs"
click node_chatui "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/tui/src/chatwidget.rs"
click node_stream "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/tui/src/streaming/controller.rs"
click node_config "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/config.rs"
click node_manager "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/conversation_manager.rs"
click node_engine "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/codex_conversation.rs"
click node_client "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/client.rs"
click node_history "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/rollout/recorder.rs"
click node_registry "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/registry.rs"
click node_router "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/router.rs"
click node_handlers "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/handlers/mod.rs"
click node_exec "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/exec_command/session_manager.rs"
click node_sandbox "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/executor/sandbox.rs"
click node_agenttools "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/handlers/spawn_agent.rs"
click node_bridge "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/child_agent_bridge.rs"
click node_orchestrator "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/orchestrator/src/runtime.rs"
click node_mcpmanager "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/mcp_connection_manager.rs"
click node_login "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/auth.rs"
click node_otel "https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/otel/src/otel_event_manager.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_tui,node_chatui,node_stream,node_user toneBlue
class node_config,node_manager,node_engine,node_client,node_history toneAmber
class node_registry,node_router,node_handlers,node_exec,node_sandbox,node_mcpserver toneMint
class node_agenttools,node_bridge,node_orchestrator,node_mcpmanager,node_login,node_otel toneRose
class node_model toneIndigo
```

## Components

### CLI and Interface

- [CLI dispatch](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/cli/src/main.rs): `codex-rs/cli/src/main.rs`
- [Terminal UI](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/tui/src/app.rs): `codex-rs/tui/src/app.rs`
- [Chat interface](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/tui/src/chatwidget.rs): `codex-rs/tui/src/chatwidget.rs`
- [Stream rendering](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/tui/src/streaming/controller.rs): `codex-rs/tui/src/streaming/controller.rs`

### Agent Runtime

- [Configuration](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/config.rs): `codex-rs/core/src/config.rs`
- [Conversation manager](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/conversation_manager.rs): `codex-rs/core/src/conversation_manager.rs`
- [Agent conversation](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/codex_conversation.rs): `codex-rs/core/src/codex_conversation.rs`
- [Model client](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/client.rs): `codex-rs/core/src/client.rs`
- [Session history](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/rollout/recorder.rs): `codex-rs/core/src/rollout/recorder.rs`

### Tools and Execution

- [Tool registry](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/registry.rs): `codex-rs/core/src/tools/registry.rs`
- [Tool router](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/router.rs): `codex-rs/core/src/tools/router.rs`
- [Tool handlers](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/handlers/mod.rs): `codex-rs/core/src/tools/handlers/mod.rs`
- [Command execution](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/exec_command/session_manager.rs): `codex-rs/core/src/exec_command/session_manager.rs`
- [Sandbox controls](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/executor/sandbox.rs): `codex-rs/core/src/executor/sandbox.rs`

### Agents and Integrations

- [Agent tools](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/tools/handlers/spawn_agent.rs): `codex-rs/core/src/tools/handlers/spawn_agent.rs`
- [Child agent bridge](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/child_agent_bridge.rs): `codex-rs/core/src/child_agent_bridge.rs`
- [Agent orchestration](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/orchestrator/src/runtime.rs): `codex-rs/orchestrator/src/runtime.rs`
- [MCP connections](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/mcp_connection_manager.rs): `codex-rs/core/src/mcp_connection_manager.rs`
- [Authentication](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/core/src/auth.rs): `codex-rs/core/src/auth.rs`
- [Telemetry events](https://github.com/0xsero/codex-local/blob/local/llms/codex-rs/otel/src/otel_event_manager.rs): `codex-rs/otel/src/otel_event_manager.rs`

### Other components

- **CLI user**
- **Model provider**
- **MCP servers**

## Connections

- CLI user → CLI dispatch: starts command
- CLI dispatch → Terminal UI: launches UI
- Terminal UI → Chat interface: routes events
- Chat interface → Conversation manager: submits prompt
- Chat interface → Stream rendering: renders deltas
- Conversation manager → Configuration: uses settings
- Conversation manager → Agent conversation: spawns conversation
- Agent conversation → Model client: requests response
- Model client → Model provider: sends requests
- Conversation manager → Session history: resumes sessions
- Agent conversation → Session history: records rollout
- Agent conversation → Tool registry: loads tools
- Tool registry → Tool router: dispatches tools
- Tool router → Tool handlers: routes calls
- Tool handlers → Command execution: runs commands
- Command execution → Sandbox controls: applies isolation
- Tool handlers → MCP connections: invokes MCP tools
- MCP connections → MCP servers: calls tools
- Tool handlers → Agent tools: handles agent calls
- Agent tools → Agent orchestration: spawns agents
- Agent orchestration → Conversation manager: creates conversations
- Agent tools → Child agent bridge: reports progress
- Conversation manager → Authentication: uses credentials
- Agent conversation → Telemetry events: emits events