How zoeynine/local-codex-bridge works
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: tools.ts Tool control surface · index.ts Bridge startup · mcp.ts MCP stdio server · observe-compact.ts Compact observation
Components 21
MCP entry
- MCP stdio server
src/mcp.ts - Tool control surface
src/tools.ts - Bridge startup
src/index.ts - Protocol version
src/version.ts
Turn supervision
- App-server manager
src/app-server.ts - Live runtime state
src/runtime.ts - Compact observation
src/observe-compact.ts
Native data access
- Persistent history
src/history.ts - Native goal
src/goal.ts - Native follow-up queue
src/queue.ts - Native search mapping
src/search.ts - Supervisor checkpoint
src/checkpoint.ts
Projection and safety
- Exact JSON validation
src/exact-json.ts - Secret detection
src/redaction.ts - Compact policies
src/compact-schema.ts - Compact descriptors
src/compact-descriptors.ts - Shape validation
src/compact-shape.ts - UX projection
src/ux-projection.ts
Platform boundary
- Platform policy
src/platform.ts
Other components
- External supervisor
- Native Codex app-server
Connections 25
- External supervisor → MCP stdio server: sends MCP requests
README.md - MCP stdio server → Tool control surface: dispatches tools
src/mcp.ts - Bridge startup → MCP stdio server: starts server
src/index.ts - Bridge startup → App-server manager: creates manager
src/index.ts - Bridge startup → Tool control surface: creates surface
src/index.ts - Bridge startup → Live runtime state: creates store
src/index.ts - Bridge startup → UX projection: configures projection
src/index.ts - MCP stdio server → Protocol version: reports version
src/mcp.ts - Tool control surface → App-server manager: issues native requests
src/tools.ts - App-server manager → Native Codex app-server: exchanges JSONL
README.md - App-server manager → Live runtime state: tracks live state
src/app-server.ts - Live runtime state → Compact observation: projects events
src/runtime.ts - Compact observation → Compact policies: applies policies
src/observe-compact.ts - Compact observation → Compact descriptors: checks descriptors
src/observe-compact.ts - Compact observation → Shape validation: validates shapes
src/observe-compact.ts - Compact descriptors → Shape validation: uses descriptor types
src/compact-descriptors.ts - Tool control surface → Persistent history: validates pages
src/tools.ts - Tool control surface → Native goal: validates responses
src/tools.ts - Tool control surface → Native follow-up queue: maps queue tools
src/tools.ts - Tool control surface → Native search mapping: maps search tools
src/tools.ts - Tool control surface → Supervisor checkpoint: uses checkpoint store
src/tools.ts - Tool control surface → Exact JSON validation: preflights writes
src/tools.ts - Exact JSON validation → Secret detection: checks secret content
src/exact-json.ts - Tool control surface → Platform policy: validates workspace paths
src/tools.ts - MCP stdio server → Persistent history: formats tool results
src/mcp.ts