codex-core

This crate implements the business logic for Codex. It is designed to be used by the various Codex UIs written in Rust.

System Prompt Composition

Codex composes the initial system message that seeds every chat completion turn as follows:

Load the built-in system prompt from prompt.md (unless overridden/disabled).
If the CODEX_BASE_INSTRUCTIONS_FILE env var is set, use that file instead of prompt.md.
Append any user instructions (e.g. from instructions.md and merged AGENTS.md).
Append the apply-patch tool instructions when using GPT-4.1 models.
Finally, the user's command or prompt is sent as the first user message.

This “system” prompt is delivered to the OpenAI Chat Completions API as the very first message with role system in the JSON messages array, e.g.:

{
  "model": "gpt-4.1",
  "messages": [
    {"role": "system", "content": "<base instructions here>"},
    {"role": "system", "content": "<user_instructions here>"},
    {"role": "system", "content": "<apply-patch tool instructions>"},
    {"role": "user",   "content": "<your prompt>"}
  ],
  ...
}

The base instructions behavior can be customized with CODEX_BASE_INSTRUCTIONS_FILE:

If unset, the built-in prompt (prompt.md) is used.
If set to a valid file path, that file's contents will be used instead (failure to read will abort).
If set to an empty string or -, no system prompt will be sent.

For implementation details, see client_common.rs and project_doc.rs.

Though for non-Rust UIs, we are also working to define a protocol for talking to Codex. See:

You can use the proto subcommand using the executable in the cli crate to speak the protocol using newline-delimited-JSON over stdin/stdout.