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.
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 the Remote Hub, sideband, and request-compatibility contracts on that path. |
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. |
config-proxy.md |
Global proxy activation, start flags, and credential-safe CLI output. |
The wire surfaces a client actually talks to.
| Doc | Scope |
|---|---|
transports/byte-accounting.md |
Request-copy and stream-buffer byte accounting shared by parsing, SSE rewriting, the adapters, and the translator budget. |
transports/responses.md |
The Responses HTTP/SSE endpoint, dispatch, credential and upload boundaries, and core module ownership. |
transports/responses-wire-shapes.md |
Mixed-wire model defaults, xAI agent-message continuation, declared-tool membership, and passthrough SSE stream shapes. |
transports/responses-failover.md |
Upstream reset retry, the ambiguous-resend gate, combo failover and commit boundaries, compaction routing, and output headroom. |
transports/responses-spend.md |
Credential-hop and durable spend reservations, and what a spent budget tells the client. |
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. |
data-planes/protocol-paths.md |
Shared protocol vocabulary, declared feature dispositions, the ingress-by-upstream baseline, plan/trace shapes, and protocol settings. |
remote-workspace.md |
Opt-in workspace identity, executor grants, runtime adapters, management and dashboard integration. |
remote-link.md |
SSH machine-link building blocks: OpenSSH argument policy, ssh_config candidates, tunnel lifecycle reducer and the private link store. |
Per-vendor contracts and the adapter authority that constructs them.
| Doc | Scope |
|---|---|
providers-and-adapters.md |
Provider and adapter selection, the adapter inventory, live model discovery, and the hosted-search continuation bridge. |
providers/openai-tiers.md |
Pool/Direct account modes, API-key separation, and the public provider and quota contract. |
providers/openai-accounts.md |
Migration and restore, wire identity, store concurrency, pool ordering and exclusions, quota observations, and account-bound retention. |
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 startup safety. |
dashboard-and-usage.md |
Dashboard page contracts, usage accounting and request metrics, and per-surface management settings. |
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. |
companion.md |
Shared timeline filtering, usage/quotas, native and web tray title, and WidgetKit display contracts. |
codex-account-controls.md |
Account selection order, custom usage thresholds, and stable account-card editing. |
Background service, docs, release, and design discipline.
| Doc | Scope |
|---|---|
desktop-shell.md |
Tauri desktop shell, proxy attachment and sidecar lifecycle, tray controls, bootstrap navigation, and desktop companion presence. |
ops/service-and-sidecars.md |
Service install/repair, platform launchers, tray, and sidecar processes. |
ops/plugins.md |
Plugin loading from OPENCODEX_HOME/plugins and the upstream rewrite slot plugins attach to. |
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. |
ops/cross-platform-ci.md |
Test lanes, platform coverage, aggregate gating, and release CI proof. |
ops/test-sandbox-cleanup.md |
Test-runner home and case-scoped lifecycle teardown ordering. |
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 requires review of every listed document. Edit only the documents whose local explanation changes; named cross-cutting authorities and dependents are listed below.
| Source path | Why |
|---|
Source review remains defined by the source-to-doc map above. This registry names each authoritative statement and the documents that review it. Link validation proves declared topology, not behavioral correctness.
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.