Skip to content

Codex integration contract

New to gald3r on this platform? Start at Use gald3r with OpenAI Codex for a short overview before the full breakdown below.

This is a configuration guide, not a live installation certificate. Check the target executable's help and current official docs when implementing an adapter.

Host migration (confirmed live 2026-09-13): every developers.openai.com/codex/* doc path this spec previously cited now 308-permanently-redirects to learn.chatgpt.com/docs/... (all five URLs re-verified: agents-md, hooks, subagents, skills, mcp). The old URLs still resolve today because a 308 is followed automatically, so nothing was broken for a reader -- but learn.chatgpt.com is the new canonical host and is what docs_url/docs_url_secondary above now point at. Content-wise, nothing below drifted: the AGENTS.md merge chain, .agents/skills locations, .codex/agents/*.toml fields, the 12-event hook list, and the config.toml MCP tables all matched a live re-fetch. See .gald3r/reports/20260913_025150_Claude_USER_EXTENSION_SURFACE_COMPARISON.md for the full sourced comparison against Cursor and Claude Code.

Instructions, skills and agents

Codex reads AGENTS.md instructions and discovers open-standard SKILL.md skills under .agents/skills/. Use AGENTS.override.md only deliberately; fallback filenames are configurable, not an unconditional discovery promise. Keep shared Gald3r rules in the generated instruction surface.

Custom agents use TOML definitions under .codex/agents/, with fields such as name, description and developer_instructions. Check current agent schema before generating definitions. Delegation depends on the user's request and the host's active instructions/capabilities; do not impose an assumed universal explicit-spawn-only rule.

Use skills for reusable workflows. Deprecated custom-prompt directories and built-in slash commands are not interchangeable with a generated Gald3r command.

Configuration and MCP

User and trusted project configuration use config.toml. Managed requirements and command-line settings also participate. Preserve unrelated configuration and do not assume every setting follows a single replacement rule: hook sources merge.

MCP uses named [mcp_servers.<name>] tables. A stdio entry needs a working executable and argument list; a configured server is not necessarily reachable or healthy. Keep credentials out of generated project files. Check discovery with codex mcp list and validate one read-only tool call.

Hook registration and trust

Hooks may be configured in hooks.json or inline [hooks] in the relevant configuration layer. Avoid duplicating the same handlers in both forms. Project trust allows the project layer to load; nonmanaged hook definitions require separate user review. Codex exposes that review through /hooks. Modified definitions need renewed trust. Never fabricate trust state, set a bypass flag, or call a trust-writing API to avoid asking the user.

Native protocol event names include SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, Stop and Interrupt. Gald3r's generated Codex integration currently registers five canonical entrypoints: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse and Stop. Do not claim the other events are wired.

Commands run in the session working directory. Generated command paths must be anchored for the actual project; moving a project requires refreshing those paths. Validate Windows quoting separately from POSIX quoting. An absolute executable path must also be quoted correctly for the selected shell; directory names with spaces are a test case, not a reason to rely on a batch launcher.

Adapter boundary

Keep concern logic shared; translate input/output at the Codex boundary. Context for supported events uses hookSpecificOutput.additionalContext together with hookEventName. Decisions are event-specific: test permitted allow/deny/block behavior rather than assuming a generic continue flag blocks every event. Read the current hooks reference for exact schemas and timeout semantics.

Transcript paths are not a stable vendor-independent log format. Select a parser for the observed platform shape. Keep tool output and reasoning out of human chat logs; avoid counting duplicate transcript representations twice. Repeated Stop must not duplicate records, while distinct turns with identical text must remain distinct. Treat native session IDs as identities, not optional display labels.

Evidence required before calling an install operational

Use an isolated consumer project first. Verify generation, actual installed command paths, interpreter/native-engine discovery, and preservation of custom configuration. Then inspect hook discovery and trust through the target Codex host. Have the user review the final definitions before a real lifecycle test.

For the real test, record the executable version, project, event and session ID, and resulting durable artifact. Do not copy private transcript content into diagnostic reports. Distinguish event-ledger writes from chat-log/database ingestion. A manually invoked hook, a synthetic fixture, a successful MCP configuration listing and a green source suite each prove different things; none alone proves a real trusted session hook ran.

Official references

  • Instructions: https://learn.chatgpt.com/docs/agent-configuration/agents-md (redirected from https://developers.openai.com/codex/guides/agents-md, 308, confirmed 2026-09-13)
  • Skills: https://learn.chatgpt.com/docs/build-skills (redirected from https://developers.openai.com/codex/skills, 308, confirmed 2026-09-13)
  • Agents: https://learn.chatgpt.com/docs/agent-configuration/subagents (redirected from https://developers.openai.com/codex/subagents, 308, confirmed 2026-09-13)
  • Hooks and event schemas: https://learn.chatgpt.com/docs/hooks (redirected from https://developers.openai.com/codex/hooks, 308, confirmed 2026-09-13)
  • Configuration: https://developers.openai.com/codex/config-reference (not re-verified this pass -- not in this task's fetch list)
  • MCP: https://learn.chatgpt.com/docs/extend/mcp?surface=cli (redirected from https://developers.openai.com/codex/mcp, 308, confirmed 2026-09-13)

Reference page — canonical source: g-skl-platform-codex/PLATFORM_SPEC.md in the engine repo, generated by scripts/generate_platform_support_docs.py. Pages marked curated are hand-assessed and not yet live-verified.