Agent Architecture

Codex CLI

Codex is a local terminal coding agent with adjacent IDE, desktop app, and cloud surfaces in the OpenAI product family. agent-connector currently targets the CLI adapter because it has a byte-addressable local config, MCP registration, hook files, and content surface directories.

Source reviewed #3Checked 2026-07-06

Setup guide Source

Run type

CLI

Adapter

json-stdio

Source

OSS · openai/codex

Stars

★ 122k

Archive Context

This page is one host entry inside the full architecture archive and keeps multi-surface products visible instead of collapsing them into a single run type.

42 host archive

Host page

codex

Run cohort

CLI: 30

Archive route

/agents

Host Surface Perspectives

The host is the primary architecture boundary. Each runnable surface below separates what the host owns from what agent-connector can safely install for Codex CLI.

1 surface entry

CLI

cli

Host entry: A terminal command owns the process, current working directory, stdin/stdout, shell environment, and project file discovery.
Host owns: The CLI host owns agent loop timing, approval prompts, tool execution, session files, and how hook or MCP subprocesses are launched.
Connector role: agent-connector can only write the host's documented CLI config, prompt, memory, hook, MCP, or package files and point them at the home binary. Current wired connector surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory.
Implementation consequence: A CLI surface is byte-addressable and smoke-testable from a temporary HOME, but terminal UI behavior still belongs to the host process. No visible host-native gap is currently tracked for this surface.

Verified Architecture

Source-checked on 2026-07-06. These notes are intentionally separate from the generated surface matrix below.

Sequence #3

Source pass

Current source review findings are kept as the first architecture section so readers can separate external evidence from the generated local coverage model.

The public repository identifies Codex CLI as a local terminal coding agent, while also distinguishing IDE, desktop app, and cloud Codex surfaces from the CLI adapter target.
The repository layout exposes the CLI and Rust implementation roots, matching the adapter's local config/runtime focus rather than a browser-only integration.
Hook behavior remains tied to Codex-specific hook docs and source, so this page treats statusline/actions as absent rather than inferring them from other hosts.

Runtime boundary

The targeted surface is Codex CLI. The host owns the model loop, local shell/apply_patch/MCP tool execution, permission decisions, and transcript context. agent-connector stays outside that loop and writes the native files Codex already reads.

User scope resolves through CODEX_HOME or ~/.codex.
Project scope mirrors the same shape under <project>/.codex.
Codex App, IDE extension, and Codex Web are adjacent product surfaces, not this adapter id.

MCP registration

The adapter renders TOML into config.toml under [mcp_servers.<id>]. Local stdio servers carry command, args, and env values; remote streamable HTTP servers use the Codex URL/header shape. Env references are resolved by agent-connector before writing because Codex does not provide the same native interpolation contract as some other hosts.

Hook bridge

Codex uses a json-stdio hook bridge. The host launches a command, sends a PascalCase event payload on stdin, and receives JSON plus an exit code. agent-connector's hook runtime normalizes that payload, runs the connector handler, then emits Codex's native reply envelope.

PreToolUse can provide context, deny, or modify supported tool inputs when Codex accepts the updatedInput envelope.
PermissionRequest has its own decision envelope and should not be treated as a normal PreToolUse rewrite point.
PostToolUse output rewriting is not exposed as a wired agent-connector capability here.

Content surfaces

Codex has multiple local content surfaces. agent-connector writes prompt commands, skills, subagents, and memory/rules into the paths this adapter can verify, while keeping statusline and actions off because they are not wired for this host today.

Commands: user-scope prompt files under the Codex prompts directory.
Skills: project .codex/skills plus the shared user skills location.
Subagents: TOML definitions under the Codex agents directory.
Memory: AGENTS.md-style standing guidance through the shared memory surface.

Host-only affordances

Codex spans CLI, IDE extension, desktop app, web, GitHub, Slack, Linear, app server, SDK, MCP server, skills, plugins, and subagents in the wider product documentation. This adapter page deliberately keeps those adjacent surfaces visible while treating only the CLI file and hook contracts as installed connector surfaces.

The CLI row should not imply support for Codex App, Codex Web, or IDE extension storage.
OpenAI docs list hooks, AGENTS.md, MCP, plugins, skills, and subagents as configuration topics, so the archive should preserve those as separate study axes.
Automation surfaces such as GitHub Action, App Server, SDK, and MCP Server are adjacent integration channels, not the local adapter target.

Host-specific shape

Codex CLI is a local terminal agent with MCP, hooks, prompts/skills/subagents, and AGENTS.md memory; statusline and action affordances are intentionally not treated as wired surfaces.

Form factor: CLI.
Native surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory.
Wired surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory.
Visible gaps: none.

Hooks

Hooks enter through a host-launched command that exchanges event JSON over stdio.

MCP

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

A marketplace or plugin-driver path is wired, so install/update/uninstall can be driven rather than only emitted as files.

Runtime handlers: none.
User-visible affordances: Users see managed commands + skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Known Limits

This page documents the CLI adapter, not Codex Web or the Codex desktop app runtime.
Statusline and action affordances are intentionally shown as not wired until a native Codex surface exists.
Hook behavior should continue to be checked against the current Codex hooks docs and the openai/codex source before changing claims.

Evidence checked

OpenAI Codex docs OpenAI Codex hooks openai/codex repository

Architecture Diagram

Host-specific flow for the CLI surface.

json-stdio

1
Entry point: CLI
Terminal agent process reads user/project config and invokes the connector home binary for runtime callbacks.
2
Connector package
defineConnector package declares server, hooks, content, memory, and actions.
3
Adapter module: codex
json-stdio renderer at src/adapters/codex/index.ts.
4
Native host artifacts
Adapter writes MCP config + hook config + content files + memory/rules + marketplace bundle through this host's native file, package, or marketplace surface.
5
Runtime boundary
host launches JSON-stdio hook command
6
User-visible surface
Users see managed commands + skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary.
7
Coverage ceiling
6/6 native surfaces wired. No visible host-native gap in the current coverage matrix.

Component Diagram

Static parts of the Codex CLI integration and which side owns each one.

Codex CLI host
CLI surface owns the model loop, UI shell, config discovery, and native lifecycle for this integration.
agent-connector package
Normalizes connector declarations into MCP, hook, memory, content, and action payloads before delegating to a host adapter.
codex adapter
Implements the json-stdio translation layer in src/adapters/codex/index.ts.
Native artifacts
Adapter writes MCP config + hook config + content files + memory/rules + marketplace bundle through this host's native file, package, or marketplace surface.
Runtime bridge
host launches JSON-stdio hook command
User-visible surface
Users see managed commands + skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary.

Runtime Sequence Flow

Message order from install to runtime for the CLI surface.

1 · User / project
Choose host adapter
Install or update starts against Codex CLI; the selected surface is CLI.
2 · agent-connector
Resolve connector declaration
The package reads connector metadata and routes it to the codex adapter instead of exposing a generic host contract.
3 · codex adapter
Render host-native shape
Adapter writes MCP config + hook config + content files + memory/rules + marketplace bundle through this host's native file, package, or marketplace surface.
4 · Codex CLI
Host loads artifacts
host launches JSON-stdio hook command
5 · Agent runtime
Run through host boundary
Users see managed commands + skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary.
6 · Coverage matrix
Expose remaining ceiling
6/6 native surfaces wired. No visible host-native gap in the current coverage matrix.

Architecture Archive

The same five study axes are rendered for every host: runtime shape, hooks, MCP, memory, and host-only affordances.

Host-specific shape

Codex CLI is a local terminal agent with MCP, hooks, prompts/skills/subagents, and AGENTS.md memory; statusline and action affordances are intentionally not treated as wired surfaces.

Form factor: CLI.
Native surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory.
Wired surfaces: MCP server, Hooks, Commands, Skills, Subagents, Memory.
Visible gaps: none.

Hooks

Hooks enter through a host-launched command that exchanges event JSON over stdio.

MCP

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

A marketplace or plugin-driver path is wired, so install/update/uninstall can be driven rather than only emitted as files.

Runtime handlers: none.
User-visible affordances: Users see managed commands + skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Special Feature Inventory

Host-specific capabilities separated from the generic surface matrix: lifecycle hooks, MCP registration, memory/rules, marketplace delivery, and UI or content affordances owned by the host.

Lifecycle hooks

Wired

Hooks enter through a host-launched command that exchanges event JSON over stdio.

MCP registration

Wired

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory and rules

Wired

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace delivery

Driver wired

A marketplace or plugin-driver path is wired, so install/update/uninstall can be driven rather than only emitted as files.

Host-only affordances

3/3 wired

Wired host affordances: Commands, Skills, Subagents. Host-native gaps: none. Not confirmed: Statusline handler, Action affordances.

Source Review Notes

Latest source pass for host-specific architecture details. This is separate from generated adapter coverage and local drift guards.

Checked 2026-07-06Open review source

OpenAI Codex docs and openai/codex repository

The public repository identifies Codex CLI as a local terminal coding agent, while also distinguishing IDE, desktop app, and cloud Codex surfaces from the CLI adapter target.
The repository layout exposes the CLI and Rust implementation roots, matching the adapter's local config/runtime focus rather than a browser-only integration.
Hook behavior remains tied to Codex-specific hook docs and source, so this page treats statusline/actions as absent rather than inferring them from other hosts.

Evidence Map

Each host page ties public source evidence to the local adapter and drift guards that keep the rendered archive aligned with code.

Public source: openai/codex

Primary public repository or product source used for current host status and source links.

external

Open source

Local adapter implementation

Defines the install/uninstall behavior, native config rendering, capability flags, and any runtime parse/format bridge for this host.

local

src/adapters/codex/index.ts

Platform metadata and host-native matrix

Records the form factor, public source target, ranking source, native host surfaces, and current agent-connector coverage cells.

local

site/src/platform-data.ts

Architecture drift guard

Asserts that every registered host has a page, diagram, host-specific brief, source link, form-factor band, and adapter-aligned surface data.

local

tests/docs/platform-drift.test.ts

Marketplace driver registry

Shows this host has a drivable package/plugin install path beyond direct native-file writes.

local

src/core/marketplace-drivers/registry.ts

Runtime Shape

Hooks are dispatched through a host-launched command. The adapter parses host JSON, calls the connector handler, and formats the reply back to the host contract.

MCP registration: Wired through this adapter
Hook bridge: Wired

Connector Surfaces

Static content

MCP server, Hooks, Commands, Skills, Subagents, Memory

Runtime handlers

No runtime handler surfaces wired

Surface Matrix

Wired means agent-connector installs it now. Host native marks support we know about but have not wired yet.

SurfaceStatus

MCP server

Static content