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-provider-routing.md |
Explicit provider-ID routing consent, URL-only publication and recovery. |
codex-home.md |
CODEX_HOME resolution, the files opencodex manages there, and Codex-home diagnostics. |
codex-prompts.md |
Prompt-layer repair, base import previews and bounded text-probe sources. |
codex-cli-update.md |
Content-bound planning and explicit POSIX/Windows x64 apply with isolated npm, artifact validation, installation leases and readback. |
catalog.md |
Shared Codex catalog assembly, account namespaces, pool rotation, and effort ladders. |
catalog-vendor-context.md |
Bundled model-ID window fallback, ambiguity handling, and inferred-capacity provenance. |
catalog-effort-clamp.md |
Persisted effort-clamp observation identity and idempotent sync notices. |
catalog-routed-ownership.md |
Generated routed-row ownership signals and combo catalog description overrides. |
subagents.md |
Multi-agent surface mode and subagent roster ordering. |
subagent-capacity.md |
Surface mode, hybrid global flag, concurrent child limits and canonical Codex setting ownership. |
advisor.md |
The optional expert consultation sidecar: manual/preflight/adaptive policies, evidence, durable task allowance, metadata activity, and loopback routing. |
config-proxy.md |
Global proxy activation, start flags, and credential-safe CLI output. |
account-auto-pause.md |
Opt-in permanent account refusal classification, credential fences, durable pause metadata, bounded recovery and resume. |
The wire surfaces a client actually talks to.
| Doc | Scope |
|---|---|
transports/timeouts.md |
Local header and JSON body deadlines, cancellation and optional OpenCode timeout export. |
remote-messaging.md |
Explicit peer enrollment, connection-bound capabilities, bounded foreground SSH ownership and queued remote replies. |
local-messaging.md |
Loaded-session Unix messaging and opt-in stored-queue MCP tools, explicit final-turn reads, receipts and owned helper bounds. |
transports/byte-accounting.md |
Request-copy and stream-buffer byte accounting shared by parsing, SSE rewriting, the adapters, and the translator budget, plus durable spill admission. |
transports/anthropic-thinking-recovery.md |
One-shot exact signature-binding recovery before output, and successful-retry memo boundaries. |
transports/response-turn-membership.md |
Embedding-owned signing material, dedicated authenticated caller/own-thread scope and pre-parser structural normalization. |
transports/response-citations.md |
OpenAI-operated outbound citation repair and generated JSON/SSE annotation titles. |
transports/max-output-completion.md |
Default-off translated Responses text-only token-limit completion and exclusions. |
transports/responses.md |
The Responses HTTP/SSE endpoint, dispatch, credential and upload boundaries, and core module ownership. |
transports/native-reasoning-retention.md |
Optional native reasoning ciphertext forwarding on model/account switches, configuration and management controls. |
transports/responses-citations.md |
Destination-gated citation repair for ordinary Responses and every native compact send. |
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-combo-boundaries.md |
Combo preflight output commitment, turn lease lifetime, and bounded hop warnings. Original client labels on terminal envelopes and failed-turn request identities. |
transports/policy-fallback.md |
Original policy authorization, concrete candidate retries and physical destination deduplication. |
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/edit relay and local hosted Responses image display. |
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/claude-tool-loading.md |
Physical-adapter tool-loading projections (Responses additional_tools and the Chat use_loaded_tool dispatcher with its response rewrite), preserved catalogs, fallback exclusions and opt-in prerequisites. |
data-planes/ollama-inbound.md |
Ollama-shaped version/tags/show/chat/generate routes translated onto Chat Completions, their admission, native error shape and final request-log ownership. |
data-planes/error-detail.md |
Closed error codes, upstream condition classification, numeric quota reset, closed failure detail, service tier and model identity bounds on request-log rows; response metadata header normalization and the client Retry-After format. Chat client error envelopes, literal tables, proxy-authored message provenance, collector verdicts and internal evidence channels; fixed undeclared-tool refusals, producer-owned incomplete-event origins and constructor-bounded destination labels, branded original client selectors, bounded combo exclusions and fixed retry-evidence diagnostics. Original model labels on synthetic terminal envelopes and compact/Messages ingress handoffs. Messages error envelopes, construction-registered fixed local-refusal guidance, sliced outcome comparisons and baseline client recovery outcomes across special codes and catch returns, non-2xx passthrough envelopes and unchanged 2xx passthrough bodies and original collector evidence and error-event identity, overflow/native-stream golden parity and normalized Anthropic response headers with full-fraction reset dates and success media types. |
data-planes/chat-reasoning-details.md |
The reasoning_details carrier that lets Chat Completions clients round-trip signed Anthropic thinking across tool steps (#7429). |
data-planes/protocol-paths.md |
Shared protocol vocabulary, declared feature dispositions, the ingress-by-upstream baseline, plan/trace shapes, and protocol settings. |
providers/codex-installation-identity.md |
Per-account Pool wire installation identity, private secret, existence gates and fail-closed delivery. |
providers/codex-request-owned-affinity.md |
Opt-in conversation affinity for a caller's own ChatGPT bearer in Pool mode, honest selection-time affinity labels, and the persistence exclusion contract. |
fallback-policy.md |
OCX-11 fallback off: what is a model or provider fallback (and what intra-pool rotation is not), scope precedence, the guarded hop sites, the fallback_refused and home_unreachable contracts, and the ocx.fallback/1 state. |
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, the private link store, and standalone pairing-grant delivery. |
Per-vendor contracts and the adapter authority that constructs them.
| Doc | Scope |
|---|---|
quota-snapshots.md |
Bounded write deferral and cancellation for Codex and provider account quota snapshots. |
providers/generic-account-pool.md |
Opt-in conversation ownership, request-local selection receipts and bounded release for generic OAuth pools. |
config-ownership.md |
Owner marker, uninstall manifest, its cross-process lock, and the uninstall tombstone. |
providers/anthropic-progress.md |
Opus 5.5 progress display, visible commentary, and exact signed-block replay. |
providers/anthropic-account-thresholds.md |
Account-owned usage thresholds, inheritance, routing boundaries and durable policy changes. |
providers/meta-muse.md |
CLI credential import, approval lifecycle, explicit recovery, account-free login diagnostics and the runtime plan-refusal classification. |
providers/oauth-reconciliation.md |
Operator limits and per-model declarations across startup reconciliation and OAuth upsert. |
providers/antigravity-account-import.md |
Cockpit Tools import schema, identity check, probe-gated project_id fallback and no-write failure paths. |
providers/claude-cli-replay.md |
Claude CLI stable replay, canonical tool schemas, capture-only client tool ownership and subscription usage admission. |
providers-and-adapters.md |
Provider and adapter selection, the adapter inventory, live model discovery, and the hosted-search continuation bridge. |
providers/opengateway.md |
Preset discovery, paired Responses tool-result projection and bounded empty-completion recovery. |
providers/jev-decision.md |
JEV Combo decision methods (TypeSafe, self-hosted System One rows, opencodex models), the decision request path, dashboard surfaces, and the content-free statistics projection. |
providers/anthropic-output-caps.md |
Routed omitted-output caps for adapter:anthropic rows keyed by Claude model id, precedence and unknown-id fallback. |
providers/anthropic-key-billing.md |
Exact billing refusal evidence, immutable physical credential ownership, pacing provenance and bounded pre-output key recovery. |
providers/workbuddy.md |
Browser login, account-bound refresh and catalogs, fixed-origin Chat transport, tool continuity and display-only credit balances. |
providers/dsh-account.md |
Explicit read-only DSH credential import, verified account identity, disabled refresh, pinned inference and probe destinations, and authoritative-empty quota. |
providers/anthropic-account-pool.md |
Anthropic OAuth instances (primary and Pool 2), account pause, model routes, quota labels, and pool-bound helpers, quota, reset grants and management surfaces. |
providers/oauth-code-display-login.md |
Headless code-display OAuth login: flow ownership, expiry, unsupported providers, single-operator store. |
providers/openai-tiers.md |
Pool/Direct account modes, API-key separation, and the public provider and quota contract. |
providers/codex-pool-affinity.md |
Restart persistence of Codex pool pins and conversation-state issuers: store, fences, single-writer lease, fail-closed recovery. |
providers/pool-credit-renewal.md |
Independent credit-evidence renewal for opted-in exhausted Codex pool accounts. |
providers/openai-accounts.md |
Migration and restore, wire identity, store concurrency, pool ordering and exclusions, quota observations, and account-bound retention. |
providers/codex-round-robin-placement.md |
Round-robin new-conversation placement preferring accounts under their effective auto-switch threshold, with all-over fallback and bound, failover and lineage boundaries. |
providers/openai-signed-in-preservation.md |
Opt-in effective priority bands that spend other pool accounts before the signed-in identity, its identity observation and management API. |
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, structured-output emulation, and reasoning round-trip. |
providers/xai-grok.md |
Grok Build contract parity and hardening. |
providers/lm-studio-chat.md |
Preset-scoped single-leading-system normalization, configuration and editor policy. |
providers/mistral-chat.md |
Canonical Mistral request-field projection, native effort clamping and typed-content normalization. |
providers/chat-compat.md |
Cross-vendor Chat Completions behavior: reasoning, tool results, structured output, parallel tools. |
providers/hosted-tool-denials.md |
Provider-declared Responses hosted-tool denials, unconditional and conditional on client tools, with their validation and save carry. |
providers/completed-tool-blocks.md |
Explicit response-only block completion, ordered safe-call delivery and terminal ownership. |
providers/mimo-bare-calls.md |
Standalone MiMo bare-block recovery into declared freeform calls, separate from identified-wrapper reconciliation. |
providers/chat-required-tool-results.md |
Translated Chat terminal guard that fails a clean completion missing a mandatory client tool call. |
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 |
|---|---|
cli-management.md |
Terminal help and capability metadata, management-client output and the generated operating reference. |
gui-and-management-api.md |
Dashboard serving, authentication boundaries, /api/* ownership, and startup safety. |
provider-completion-diagnostic.md |
Explicit single-model completion test: consent, applicability gate, send-time authority fingerprint, bounded streaming and metadata comparison. |
dashboard-and-usage.md |
Dashboard page contracts, usage accounting and request metrics, and per-surface management settings. |
usage-client-attribution.md |
Privacy-bounded client labels carried from request ingress into usage records. |
quota-pool.md |
The passive GET /api/quota-pool read GOAT consumes (ocx.quota-pool/1): sources, window mapping, absent-not-zero, and the install identity behind homeId and accountRef. |
pricing.md |
User price policies, prompt-length rate selection, persistence and estimate cache invalidation. |
clients/export-model-names.md |
Per-connection naming policy, router-proven aliases and passive export previews. |
clients/omo-export-dialect.md |
Opt-in Responses dialect for the managed Pi-based omo export and its refresh lifecycle. |
clients/integrations.md |
Third-party client config ownership, snapshots, refresh, disable, and restore. |
clients/codex-desktop.md |
Windows package activation, restart context, and protected compatibility authority persistence. |
clients/chatgpt-desktop.md |
Experimental macOS app-server stdout shim, opt-in launch, restore and failure boundaries. |
clients/claude-desktop.md |
Claude Desktop profile ownership and config-library resolution. |
clients/claude-desktop-config-reads.md |
Verified regular-file reads of Claude Desktop config-library metadata, profiles and snapshots. |
clients/claude-desktop-model-visibility.md |
Per-client selection of the rows the Claude Desktop 3P model list carries. |
clients/hermes.md |
Hermes profile discovery, per-profile selection, ownership stores, and boundaries. |
clients/qoder.md |
Qoder settings.json provider and custom-model ownership, export and loopback placeholder rules. |
clients/client-support-matrix.md |
Generated client support page: registry sources, curated protocol and test claims, drift checks. |
clients/t3code.md |
T3 Code settings.json Claude provider-instance ownership, proxy environment, custom models and loopback marker rules. |
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. |
telemetry.md |
Anonymous daily usage telemetry contract, consent state, install identity, ledger aggregation, scheduler, management API, CLI, and Cloudflare Worker collector. |
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. |
desktop-recovery.md |
Native recovery intent, independently anchored executable and accepted-connection proof, cold-start decisions and installation scope. |
desktop-terminal-command.md |
Desktop-owned ocx command on PATH: record and journal, POSIX shim and shell blocks, Windows user Path, private-path ACL policy, and the local Terminal command page. |
desktop-start-at-login.md |
macOS tray Start at Login judgment shared with Startup safety, its parity fixture, click rules, and the guarded launch-origin migration. |
ops/service-and-sidecars.md |
Service install/repair, platform launchers, tray, and sidecar processes. |
ops/desktop-supervision.md |
Durable Desktop ownership read, takeover-consent handling, live-supervision evidence, the Windows probe's trusted system-directory acquisition, and the supervision latch blocking contract consumed by service and update guards. |
ops/service-logging.md |
Service-only console timestamps and bounded copy-truncate log retention. Producer bounds for combo positions, target providers and effort diagnostics. |
ops/service-health-recovery.md |
Opt-in sentinel that turns a hung but listening managed service proxy into an exit its manager restarts. |
ops/windows-checked-stop.md |
Windows process evidence, the wrapper binding rule, and the checked manager stop and port confirmation that are not yet wired to a stop path. |
ops/update-supervised-recovery.md |
Manager-first recovery after a failed post-update service refresh, and the non-zero unsupervised fallback. |
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, case-scoped lifecycle teardown, and Bun test lock generation ownership. |
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.