# bytepioneer-ai/codex-host architecture

> Architecture diagram of the GitHub repository bytepioneer-ai/codex-host, 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/bytepioneer-ai/codex-host
- Repository: https://github.com/bytepioneer-ai/codex-host

## Overview

CodexHost embeds multiple agent harnesses in Codex Desktop. The user launches CodexHost, which starts the desktop integration; the Host Runtime coordinates harness sessions, while adapters translate harness-specific behavior into CodexHost’s shared protocol and renderer-facing experience. The repository also includes remote execution, delegation, diagnostics, and update paths. The README establishes the product capabilities; sampled source confirms selected entry points and services, but not all runtime wiring, so uncertain links are omitted.

Main entry points: [`packages/host-runtime/src/main.ts`](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/main.ts) (Host Runtime), [`crates/launcher/src/main.rs`](https://github.com/bytepioneer-ai/codex-host/blob/main/crates/launcher/src/main.rs) (Launcher), [`packages/renderer-extension/src/production-entry.ts`](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/renderer-extension/src/production-entry.ts) (Renderer Extension), [`packages/renderer-extension/src/console/app.ts`](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/renderer-extension/src/console/app.ts) (Console UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and Platform"]
  node_launcher["Launcher<br/>[main.rs]"]
  node_platform["Platform Services<br/>[lib.rs]"]
  node_shim["Desktop Shim<br/>[main.rs]"]
end

subgraph group_runtime["Harness Runtime"]
  node_host["Host Runtime<br/>[main.ts]"]
  node_discovery["Harness Discovery<br/>[index.ts]"]
  node_adapters["Harness Adapters"]
  node_protocol["Protocol Core<br/>[index.ts]"]
  node_broker["Harness Broker<br/>[server.ts]"]
end

subgraph group_experience["Desktop Experience"]
  node_renderer["Renderer Extension"]
  node_desktop_control["Desktop Control"]
  node_mapping[("Session Mapping<br/>[mapping-store.ts]")]
end

subgraph group_remote["Remote and Collaboration"]
  node_delegation["Delegation<br/>[delegation-cli.ts]"]
  node_remote_host["Remote Host<br/>[remote-host-cli.ts]"]
  node_remote_bridge["Remote Bridge"]
end

subgraph group_operations["Operations"]
  node_console_server["Console Server<br/>[server.ts]"]
  node_console_ui["Console UI<br/>[app.ts]"]
  node_update_manager["Update Manager<br/>[update-manager.ts]"]
  node_updater["Updater<br/>[main.rs]"]
end

node_user(("User"))
node_codex["Codex Desktop"]
node_harnesses["Agent Harnesses"]

node_user -->|"launches"| node_launcher
node_launcher -->|"uses platform services"| node_platform
node_launcher -->|"starts desktop integration"| node_codex
node_codex -->|"invokes"| node_shim
node_shim -->|"starts runtime"| node_host
node_host -->|"discovers harnesses"| node_discovery
node_host -->|"loads integrations"| node_adapters
node_adapters -->|"translates harness behavior"| node_harnesses
node_host -->|"uses shared protocol"| node_protocol
node_host -->|"brokers harness sessions"| node_broker
node_host -->|"supplies session experience"| node_renderer
node_renderer -->|"integrates with interface"| node_codex
node_desktop_control -->|"controls renderer"| node_codex
node_renderer -->|"maps sessions"| node_mapping
node_host -->|"dispatches delegation"| node_delegation
node_host -.->|"supports remote execution"| node_remote_host
node_remote_bridge -.->|"bridges remote control"| node_remote_host
node_user -->|"opens console"| node_console_ui
node_console_ui -->|"requests diagnostics"| node_console_server
node_console_server -->|"inspects runtime"| node_host
node_console_ui -->|"requests updates"| node_update_manager
node_update_manager -->|"prepares update"| node_updater

click node_launcher "https://github.com/bytepioneer-ai/codex-host/blob/main/crates/launcher/src/main.rs"
click node_platform "https://github.com/bytepioneer-ai/codex-host/blob/main/crates/platform/src/lib.rs"
click node_shim "https://github.com/bytepioneer-ai/codex-host/blob/main/crates/shim/src/main.rs"
click node_host "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/main.ts"
click node_discovery "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/harness-discovery/src/index.ts"
click node_adapters "https://github.com/bytepioneer-ai/codex-host/tree/main/packages/adapters"
click node_protocol "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/protocol-core/src/index.ts"
click node_broker "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/harness-broker/src/server.ts"
click node_renderer "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/renderer-extension/src/production-entry.ts"
click node_desktop_control "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/desktop-control/src/production-controller.ts"
click node_mapping "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/mapping-store/src/mapping-store.ts"
click node_delegation "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/delegation-cli.ts"
click node_remote_host "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/remote-host-cli.ts"
click node_remote_bridge "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/remote-control-app-server.ts"
click node_console_server "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/console-server/src/server.ts"
click node_console_ui "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/renderer-extension/src/console/app.ts"
click node_update_manager "https://github.com/bytepioneer-ai/codex-host/blob/main/packages/update-manager/src/update-manager.ts"
click node_updater "https://github.com/bytepioneer-ai/codex-host/blob/main/crates/updater/src/main.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_launcher,node_platform,node_shim,node_user toneBlue
class node_host,node_discovery,node_adapters,node_protocol,node_broker toneAmber
class node_renderer,node_desktop_control,node_mapping toneMint
class node_delegation,node_remote_host,node_remote_bridge toneRose
class node_console_server,node_console_ui,node_update_manager,node_updater,node_codex,node_harnesses toneIndigo
```

## Components

### Launch and Platform

- [Launcher](https://github.com/bytepioneer-ai/codex-host/blob/main/crates/launcher/src/main.rs): `crates/launcher/src/main.rs`
- [Platform Services](https://github.com/bytepioneer-ai/codex-host/blob/main/crates/platform/src/lib.rs): `crates/platform/src/lib.rs`
- [Desktop Shim](https://github.com/bytepioneer-ai/codex-host/blob/main/crates/shim/src/main.rs): `crates/shim/src/main.rs`

### Harness Runtime

- [Host Runtime](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/main.ts): `packages/host-runtime/src/main.ts`
- [Harness Discovery](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/harness-discovery/src/index.ts): `packages/harness-discovery/src/index.ts`
- [Harness Adapters](https://github.com/bytepioneer-ai/codex-host/tree/main/packages/adapters): `packages/adapters`
- [Protocol Core](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/protocol-core/src/index.ts): `packages/protocol-core/src/index.ts`
- [Harness Broker](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/harness-broker/src/server.ts): `packages/harness-broker/src/server.ts`

### Desktop Experience

- [Renderer Extension](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/renderer-extension/src/production-entry.ts): `packages/renderer-extension/src/production-entry.ts`
- [Desktop Control](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/desktop-control/src/production-controller.ts): `packages/desktop-control/src/production-controller.ts`
- [Session Mapping](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/mapping-store/src/mapping-store.ts): `packages/mapping-store/src/mapping-store.ts`

### Remote and Collaboration

- [Delegation](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/delegation-cli.ts): `packages/host-runtime/src/delegation-cli.ts`
- [Remote Host](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/remote-host-cli.ts): `packages/host-runtime/src/remote-host-cli.ts`
- [Remote Bridge](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/host-runtime/src/remote-control-app-server.ts): `packages/host-runtime/src/remote-control-app-server.ts`

### Operations

- [Console Server](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/console-server/src/server.ts): `packages/console-server/src/server.ts`
- [Console UI](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/renderer-extension/src/console/app.ts): `packages/renderer-extension/src/console/app.ts`
- [Update Manager](https://github.com/bytepioneer-ai/codex-host/blob/main/packages/update-manager/src/update-manager.ts): `packages/update-manager/src/update-manager.ts`
- [Updater](https://github.com/bytepioneer-ai/codex-host/blob/main/crates/updater/src/main.rs): `crates/updater/src/main.rs`

### Other components

- **User**
- **Codex Desktop**
- **Agent Harnesses**

## Connections

- User → Launcher: launches
- Launcher → Platform Services: uses platform services
- Launcher → Codex Desktop: starts desktop integration
- Codex Desktop → Desktop Shim: invokes
- Desktop Shim → Host Runtime: starts runtime
- Host Runtime → Harness Discovery: discovers harnesses
- Host Runtime → Harness Adapters: loads integrations
- Harness Adapters → Agent Harnesses: translates harness behavior
- Host Runtime → Protocol Core: uses shared protocol
- Host Runtime → Harness Broker: brokers harness sessions
- Host Runtime → Renderer Extension: supplies session experience
- Renderer Extension → Codex Desktop: integrates with interface
- Desktop Control → Codex Desktop: controls renderer
- Renderer Extension → Session Mapping: maps sessions
- Host Runtime → Delegation: dispatches delegation
- Host Runtime → Remote Host: supports remote execution
- Remote Bridge → Remote Host: bridges remote control
- User → Console UI: opens console
- Console UI → Console Server: requests diagnostics
- Console Server → Host Runtime: inspects runtime
- Console UI → Update Manager: requests updates
- Update Manager → Updater: prepares update