This folder is the maintainer source of truth for the current system shape. Public user workflows
belong in docs-site/. Development work is recorded in devlog/ units — _plan/ while open,
_fin/ once closed — while docs/ keeps investigations and diagnostic notes worth retaining for
archaeology, debugging, or source research.
Generated from structure/manifest.json by bun run structure:index. Do not edit by hand; bun run structure:check fails when this file and the manifest disagree. The rules for changing anything
in this folder are in AGENTS.md.
What opencodex is, what it owns on disk, and the invariants nothing may break.
| Doc | Scope |
|---|---|
overview.md |
Product boundary, local state ownership, and the non-negotiable invariants index. |
runtime.md |
Entrypoints, process lifecycle, CLI surface, and provider/adapter selection. |
Persisted config, the Codex home it writes into, and the model catalog it publishes.
| Doc | Scope |
|---|---|
config.md |
Persisted config schema, both injection forms, provider validation, and restore. |
codex-home.md |
CODEX_HOME resolution, the files opencodex manages there, and Codex-home diagnostics. |
catalog.md |
Shared Codex catalog assembly, account namespaces, pool rotation, and effort ladders. |
subagents.md |
Multi-agent surface mode and subagent roster ordering. |
The wire surfaces a client actually talks to.
| Doc | Scope |
|---|---|
transports/responses.md |
The Responses HTTP/SSE data plane, combo failover, and streaming commit boundaries. |
transports/streaming-health.md |
Heartbeat and stall deadlines, plus the opt-in WebSocket transport. |
transports/inventory.md |
The per-provider transport table and diagnostic outbound safety. |
data-planes/images.md |
Standalone image generation and edit relay. |
data-planes/search.md |
Hosted search relay and exact account selectors. |
data-planes/inbound-compat.md |
Chat Completions inbound, Anthropic-shaped clients, and JSON-upstream streaming clients. |
remote-workspace.md |
Inactive workspace protocol, cryptographic identity primitives, and bounded framing. |
Per-vendor contracts and the adapter authority that constructs them.
| Doc | Scope |
|---|---|
providers/openai-tiers.md |
Pool/Direct account modes, API-key separation, wire identity, and quota evidence. |
providers/cursor.md |
Cursor native exec, parameterized models, checkpoints, and active-context usage. |
providers/google.md |
Gemini thought-text, response parts, thought-signature replay, and adjacency repair. |
providers/kiro.md |
Kiro parallel-tool hints, Responses text controls, and reasoning round-trip. |
providers/xai-grok.md |
Grok Build contract parity and hardening. |
providers/chat-compat.md |
Cross-vendor Chat Completions behavior: reasoning, tool results, structured output, parallel tools. |
adapters/registry.md |
The single adapter construction authority and contract inheritance. |
adapters/compatibility-contracts.md |
Versioned provider compatibility claims and fixture-evidence boundaries. |
adapters/compatibility-lab.md |
Optional Lab evidence, automation, and its core-runtime isolation boundary. |
The dashboard, the management API, and third-party client config ownership.
| Doc | Scope |
|---|---|
gui-and-management-api.md |
Dashboard serving, authentication boundaries, /api/* ownership, and usage accounting. |
clients/integrations.md |
Third-party client config ownership, snapshots, refresh, disable, and restore. |
clients/claude-desktop.md |
Claude Desktop profile ownership and config-library resolution. |
Background service, docs, release, and design discipline.
| Doc | Scope |
|---|---|
ops/service-and-sidecars.md |
Service install/repair, platform launchers, tray, and sidecar processes. |
ops/docs-and-release.md |
Docs site, workflow map, branch policy, release flow, and cross-platform CI. |
design-methodology.md |
Stage ordering for new GUI, CLI, and user-facing surfaces. |
A source area can be described by more than one doc, because these docs are organised by topic and
src/ is organised by module. Changing an area obliges the same change to update every doc listed
for it; see AGENTS.md.
| Source path | Why |
|---|---|
src/bridge.ts |
no doc names this file; it is the legacy adapter bridge entry and its behavior is described under the adapter registry without a path reference |
src/quota/ |
no doc names a path here; quota evidence is described in providers/openai-tiers.md in prose only |
src/service-manager-probe.ts |
no doc names this file; service probing is described in ops/service-and-sidecars.md without a path reference |
src/sidecar/ |
no doc names a path here; ops/service-and-sidecars.md describes sidecar behavior in prose only |
src/types/ |
shared declarations plus the tool-name and wire-pin resolvers, which no doc currently describes |
Superseded reasoning lives in decisions/ as numbered records. A doc states the contract that holds now and
links the record that explains why; it never carries the reasoning inline.