# zoeynine/local-codex-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/zoeynine/local-codex-bridge
- Repository: https://github.com/zoeynine/local-codex-bridge

## Overview

Local Codex Bridge is a thin MCP stdio supervisor adapter to native Codex, not a replacement execution system. An external supervisor invokes the MCP surface; the Bridge maps tool requests to the native app-server and returns bounded results. The principal workflow is start or resume a native turn, observe live state, then steer, answer a pending request, or interrupt as needed. Persistent History, Goal, Queue, and Search remain distinct native capabilities. Source excerpts show the transport, orchestration, and compact-observation layers; README statements establish several native capability boundaries where implementation details were not sampled.

Main entry points: [`src/tools.ts`](https://github.com/zoeynine/local-codex-bridge/blob/main/src/tools.ts) (Tool control surface), [`src/index.ts`](https://github.com/zoeynine/local-codex-bridge/blob/main/src/index.ts) (Bridge startup), [`src/mcp.ts`](https://github.com/zoeynine/local-codex-bridge/blob/main/src/mcp.ts) (MCP stdio server), [`src/observe-compact.ts`](https://github.com/zoeynine/local-codex-bridge/blob/main/src/observe-compact.ts) (Compact observation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_mcp["MCP stdio server<br/>[mcp.ts]"]
  node_tools["Tool control surface<br/>[tools.ts]"]
  node_bridge["Bridge startup<br/>[index.ts]"]
  node_version["Protocol version<br/>[version.ts]"]
end

subgraph group_supervision["Turn supervision"]
  node_appserver["App-server manager<br/>[app-server.ts]"]
  node_runtime["Live runtime state<br/>[runtime.ts]"]
  node_observe["Compact observation<br/>[observe-compact.ts]"]
end

subgraph group_native_data["Native data access"]
  node_history["Persistent history<br/>[history.ts]"]
  node_goal["Native goal<br/>[goal.ts]"]
  node_queue["Native follow-up queue<br/>[queue.ts]"]
  node_search["Native search mapping<br/>[search.ts]"]
  node_checkpoint[("Supervisor checkpoint<br/>[checkpoint.ts]")]
end

subgraph group_safety["Projection and safety"]
  node_exact_json["Exact JSON validation<br/>[exact-json.ts]"]
  node_redaction["Secret detection<br/>[redaction.ts]"]
  node_compact_schema["Compact policies<br/>[compact-schema.ts]"]
  node_compact_descriptors["Compact descriptors"]
  node_compact_shape["Shape validation<br/>[compact-shape.ts]"]
  node_ux["UX projection<br/>[ux-projection.ts]"]
end

subgraph group_platform["Platform boundary"]
  node_platform_policy["Platform policy<br/>[platform.ts]"]
end

node_supervisor(("External supervisor"))
node_codex["Native Codex app-server"]

node_supervisor -->|"sends MCP requests"| node_mcp
node_mcp -->|"dispatches tools"| node_tools
node_bridge -->|"starts server"| node_mcp
node_bridge -->|"creates manager"| node_appserver
node_bridge -->|"creates surface"| node_tools
node_bridge -->|"creates store"| node_runtime
node_bridge -->|"configures projection"| node_ux
node_mcp -->|"reports version"| node_version
node_tools -->|"issues native requests"| node_appserver
node_appserver -->|"exchanges JSONL"| node_codex
node_appserver -->|"tracks live state"| node_runtime
node_runtime -->|"projects events"| node_observe
node_observe -->|"applies policies"| node_compact_schema
node_observe -->|"checks descriptors"| node_compact_descriptors
node_observe -->|"validates shapes"| node_compact_shape
node_compact_descriptors -->|"uses descriptor types"| node_compact_shape
node_tools -->|"validates pages"| node_history
node_tools -->|"validates responses"| node_goal
node_tools -->|"maps queue tools"| node_queue
node_tools -->|"maps search tools"| node_search
node_tools -->|"uses checkpoint store"| node_checkpoint
node_tools -->|"preflights writes"| node_exact_json
node_exact_json -->|"checks secret content"| node_redaction
node_tools -->|"validates workspace paths"| node_platform_policy
node_mcp -->|"formats tool results"| node_history

click node_mcp "https://github.com/zoeynine/local-codex-bridge/blob/main/src/mcp.ts"
click node_tools "https://github.com/zoeynine/local-codex-bridge/blob/main/src/tools.ts"
click node_bridge "https://github.com/zoeynine/local-codex-bridge/blob/main/src/index.ts"
click node_appserver "https://github.com/zoeynine/local-codex-bridge/blob/main/src/app-server.ts"
click node_runtime "https://github.com/zoeynine/local-codex-bridge/blob/main/src/runtime.ts"
click node_observe "https://github.com/zoeynine/local-codex-bridge/blob/main/src/observe-compact.ts"
click node_history "https://github.com/zoeynine/local-codex-bridge/blob/main/src/history.ts"
click node_goal "https://github.com/zoeynine/local-codex-bridge/blob/main/src/goal.ts"
click node_queue "https://github.com/zoeynine/local-codex-bridge/blob/main/src/queue.ts"
click node_search "https://github.com/zoeynine/local-codex-bridge/blob/main/src/search.ts"
click node_checkpoint "https://github.com/zoeynine/local-codex-bridge/blob/main/src/checkpoint.ts"
click node_exact_json "https://github.com/zoeynine/local-codex-bridge/blob/main/src/exact-json.ts"
click node_redaction "https://github.com/zoeynine/local-codex-bridge/blob/main/src/redaction.ts"
click node_compact_schema "https://github.com/zoeynine/local-codex-bridge/blob/main/src/compact-schema.ts"
click node_compact_descriptors "https://github.com/zoeynine/local-codex-bridge/blob/main/src/compact-descriptors.ts"
click node_compact_shape "https://github.com/zoeynine/local-codex-bridge/blob/main/src/compact-shape.ts"
click node_ux "https://github.com/zoeynine/local-codex-bridge/blob/main/src/ux-projection.ts"
click node_platform_policy "https://github.com/zoeynine/local-codex-bridge/blob/main/src/platform.ts"
click node_version "https://github.com/zoeynine/local-codex-bridge/blob/main/src/version.ts"

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_mcp,node_tools,node_bridge,node_version toneBlue
class node_appserver,node_runtime,node_observe toneAmber
class node_history,node_goal,node_queue,node_search,node_checkpoint,node_codex toneMint
class node_exact_json,node_redaction,node_compact_schema,node_compact_descriptors,node_compact_shape,node_ux toneRose
class node_platform_policy,node_supervisor toneIndigo
```

## Components

### MCP entry

- [MCP stdio server](https://github.com/zoeynine/local-codex-bridge/blob/main/src/mcp.ts): `src/mcp.ts`
- [Tool control surface](https://github.com/zoeynine/local-codex-bridge/blob/main/src/tools.ts): `src/tools.ts`
- [Bridge startup](https://github.com/zoeynine/local-codex-bridge/blob/main/src/index.ts): `src/index.ts`
- [Protocol version](https://github.com/zoeynine/local-codex-bridge/blob/main/src/version.ts): `src/version.ts`

### Turn supervision

- [App-server manager](https://github.com/zoeynine/local-codex-bridge/blob/main/src/app-server.ts): `src/app-server.ts`
- [Live runtime state](https://github.com/zoeynine/local-codex-bridge/blob/main/src/runtime.ts): `src/runtime.ts`
- [Compact observation](https://github.com/zoeynine/local-codex-bridge/blob/main/src/observe-compact.ts): `src/observe-compact.ts`

### Native data access

- [Persistent history](https://github.com/zoeynine/local-codex-bridge/blob/main/src/history.ts): `src/history.ts`
- [Native goal](https://github.com/zoeynine/local-codex-bridge/blob/main/src/goal.ts): `src/goal.ts`
- [Native follow-up queue](https://github.com/zoeynine/local-codex-bridge/blob/main/src/queue.ts): `src/queue.ts`
- [Native search mapping](https://github.com/zoeynine/local-codex-bridge/blob/main/src/search.ts): `src/search.ts`
- [Supervisor checkpoint](https://github.com/zoeynine/local-codex-bridge/blob/main/src/checkpoint.ts): `src/checkpoint.ts`

### Projection and safety

- [Exact JSON validation](https://github.com/zoeynine/local-codex-bridge/blob/main/src/exact-json.ts): `src/exact-json.ts`
- [Secret detection](https://github.com/zoeynine/local-codex-bridge/blob/main/src/redaction.ts): `src/redaction.ts`
- [Compact policies](https://github.com/zoeynine/local-codex-bridge/blob/main/src/compact-schema.ts): `src/compact-schema.ts`
- [Compact descriptors](https://github.com/zoeynine/local-codex-bridge/blob/main/src/compact-descriptors.ts): `src/compact-descriptors.ts`
- [Shape validation](https://github.com/zoeynine/local-codex-bridge/blob/main/src/compact-shape.ts): `src/compact-shape.ts`
- [UX projection](https://github.com/zoeynine/local-codex-bridge/blob/main/src/ux-projection.ts): `src/ux-projection.ts`

### Platform boundary

- [Platform policy](https://github.com/zoeynine/local-codex-bridge/blob/main/src/platform.ts): `src/platform.ts`

### Other components

- **External supervisor**
- **Native Codex app-server**

## Connections

- External supervisor → MCP stdio server: sends MCP requests (evidence: `README.md`)
- MCP stdio server → Tool control surface: dispatches tools (evidence: `src/mcp.ts`)
- Bridge startup → MCP stdio server: starts server (evidence: `src/index.ts`)
- Bridge startup → App-server manager: creates manager (evidence: `src/index.ts`)
- Bridge startup → Tool control surface: creates surface (evidence: `src/index.ts`)
- Bridge startup → Live runtime state: creates store (evidence: `src/index.ts`)
- Bridge startup → UX projection: configures projection (evidence: `src/index.ts`)
- MCP stdio server → Protocol version: reports version (evidence: `src/mcp.ts`)
- Tool control surface → App-server manager: issues native requests (evidence: `src/tools.ts`)
- App-server manager → Native Codex app-server: exchanges JSONL (evidence: `README.md`)
- App-server manager → Live runtime state: tracks live state (evidence: `src/app-server.ts`)
- Live runtime state → Compact observation: projects events (evidence: `src/runtime.ts`)
- Compact observation → Compact policies: applies policies (evidence: `src/observe-compact.ts`)
- Compact observation → Compact descriptors: checks descriptors (evidence: `src/observe-compact.ts`)
- Compact observation → Shape validation: validates shapes (evidence: `src/observe-compact.ts`)
- Compact descriptors → Shape validation: uses descriptor types (evidence: `src/compact-descriptors.ts`)
- Tool control surface → Persistent history: validates pages (evidence: `src/tools.ts`)
- Tool control surface → Native goal: validates responses (evidence: `src/tools.ts`)
- Tool control surface → Native follow-up queue: maps queue tools (evidence: `src/tools.ts`)
- Tool control surface → Native search mapping: maps search tools (evidence: `src/tools.ts`)
- Tool control surface → Supervisor checkpoint: uses checkpoint store (evidence: `src/tools.ts`)
- Tool control surface → Exact JSON validation: preflights writes (evidence: `src/tools.ts`)
- Exact JSON validation → Secret detection: checks secret content (evidence: `src/exact-json.ts`)
- Tool control surface → Platform policy: validates workspace paths (evidence: `src/tools.ts`)
- MCP stdio server → Persistent history: formats tool results (evidence: `src/mcp.ts`)
