# microsoft/codex-cli architecture

> Architecture diagram of the GitHub repository microsoft/codex-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/codex-cli
- Repository: https://github.com/microsoft/codex-cli

## Overview

1. This repository is a local shell assistant, not a service. The architecture is split between shell-specific integration scripts and a small Python core that turns natural-language comments into shell commands via the OpenAI Codex API.

2. The main user-facing boundary is the shell plugin layer in `scripts/`. There are separate setup/plugin/cleanup scripts for Bash, zsh, and PowerShell. These scripts bind the interaction to the terminal experience, capture the current line/comment, and hand it off to the Python code. They also handle shell-idiomatic insertion of the generated command back into the prompt buffer.

3. The Python runtime lives in `src/` and is the language-agnostic core. `src/codex_query.py` is the orchestration entry point for building the prompt, calling OpenAI, and returning the model’s completion. This is the only part that talks to the external AI service.

4. `src/commands.py` is the control plane for in-band “meta commands” entered as comments, such as starting or stopping multi-turn mode, loading/saving contexts, viewing context, showing config, and changing settings. This is distinct from ordinary natural-language requests, which are forwarded for code generation.

5. Prompt construction is data-driven. The `contexts/` directory contains shell- and use-case-specific few-shot examples that steer Codex toward idiomatic output for Bash, zsh, or PowerShell. The README calls out that these example files are the main prompt-engineering mechanism.

6. `src/prompt_file.py` appears to centralize which context file is considered the default for each shell and how context files are loaded. That makes context selection a configuration boundary rather than hardcoded behavior, which is important for diagramming how the assistant adapts across shells.

7. Multi-turn mode is implemented as local conversational state, not server-side memory. The tool appends prior interactions into a `current_context.txt`-style file and reuses that text on later requests. This introduces a stateful path in an otherwise stateless request/response flow.

8. The data flow is: user types a comment-like natural language request in the shell → shell plugin intercepts it on `Ctrl+G` → Python builds a prompt from default context plus any multi-turn history → Codex returns shell code → the plugin inserts or prints that code back into the active shell session.

9. The external dependency boundary is very small: the only runtime backend is OpenAI’s API and the model/engine selected via user config. There is no repository-managed database, queue, or web server. Any persistence is local files in the working directory or `contexts/`.

10. The repository also includes an example alternate context for Azure Cognitive Services text-to-speech behavior, showing that the system is designed to be extensible by swapping prompt contexts rather than changing core logic. That’s a useful diagram element: the same engine can be repurposed by changing few-shot examples.

11. `requirements.txt` and the installation docs define the Python dependency/runtime layer, while the shell scripts define platform-specific installation and teardown. So the overall architecture is: shell integration on the edges, prompt/context/state management in the middle, and OpenAI Codex as the external intelligence provider.

Main entry points: [`src/codex_query.py`](https://github.com/microsoft/codex-cli/blob/main/src/codex_query.py) (Codex query), [`src/prompt_file.py`](https://github.com/microsoft/codex-cli/blob/main/src/prompt_file.py) (Context loader), [`src/commands.py`](https://github.com/microsoft/codex-cli/blob/main/src/commands.py) (Meta commands), [`scripts/bash_plugin.sh`](https://github.com/microsoft/codex-cli/blob/main/scripts/bash_plugin.sh) (Bash plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Shell integration"]
  node_bash_plugin["Bash plugin<br/>shell hook<br/>[bash_plugin.sh]"]
  node_bash_setup["Bash setup<br/>install script<br/>[bash_setup.sh]"]
  node_bash_cleanup["Bash cleanup<br/>remove script<br/>[bash_cleanup.sh]"]
  node_zsh_plugin["Zsh plugin<br/>shell hook<br/>[zsh_plugin.zsh]"]
  node_zsh_setup["Zsh setup<br/>install script<br/>[zsh_setup.sh]"]
  node_zsh_cleanup["Zsh cleanup<br/>remove script<br/>[zsh_cleanup.sh]"]
  node_ps_plugin["PowerShell plugin<br/>shell hook"]
  node_ps_setup["PowerShell setup<br/>install script"]
  node_ps_cleanup["PowerShell cleanup<br/>remove script"]
end

subgraph group_core["Python core"]
  node_codex_query["Codex query<br/>orchestrator<br/>[codex_query.py]"]
  node_commands["Meta commands<br/>control plane<br/>[commands.py]"]
  node_prompt_file["Context loader<br/>context config<br/>[prompt_file.py]"]
  node_multi_turn_state["Conversation state<br/>local state"]
end

subgraph group_prompts["Prompt assets"]
  node_bash_context["Bash context<br/>few-shot prompt<br/>[bash-context.txt]"]
  node_zsh_context["Zsh context<br/>few-shot prompt<br/>[zsh-context.txt]"]
  node_ps_context["PowerShell context<br/>few-shot prompt"]
  node_azure_voice_context["Azure voice context<br/>alternate prompt"]
end

subgraph group_external["External API"]
  node_openai_api[("OpenAI API<br/>external model")]
end

node_bash_setup -->|"installs"| node_bash_plugin
node_bash_plugin -->|"requests"| node_codex_query
node_bash_plugin -->|"meta input"| node_commands
node_bash_cleanup -->|"removes"| node_bash_plugin
node_zsh_setup -->|"installs"| node_zsh_plugin
node_zsh_plugin -->|"requests"| node_codex_query
node_zsh_plugin -->|"meta input"| node_commands
node_zsh_cleanup -->|"removes"| node_zsh_plugin
node_ps_setup -->|"installs"| node_ps_plugin
node_ps_plugin -->|"requests"| node_codex_query
node_ps_plugin -->|"meta input"| node_commands
node_ps_cleanup -->|"removes"| node_ps_plugin
node_codex_query -->|"loads"| node_prompt_file
node_prompt_file -->|"default shell"| node_bash_context
node_prompt_file -->|"default shell"| node_zsh_context
node_prompt_file -->|"default shell"| node_ps_context
node_prompt_file -->|"alternate mode"| node_azure_voice_context
node_commands -->|"updates"| node_multi_turn_state
node_codex_query -->|"includes"| node_multi_turn_state
node_codex_query -->|"calls"| node_openai_api
node_openai_api -->|"returns"| node_codex_query
node_commands -->|"routes"| node_codex_query

click node_bash_plugin "https://github.com/microsoft/codex-cli/blob/main/scripts/bash_plugin.sh"
click node_bash_setup "https://github.com/microsoft/codex-cli/blob/main/scripts/bash_setup.sh"
click node_bash_cleanup "https://github.com/microsoft/codex-cli/blob/main/scripts/bash_cleanup.sh"
click node_zsh_plugin "https://github.com/microsoft/codex-cli/blob/main/scripts/zsh_plugin.zsh"
click node_zsh_setup "https://github.com/microsoft/codex-cli/blob/main/scripts/zsh_setup.sh"
click node_zsh_cleanup "https://github.com/microsoft/codex-cli/blob/main/scripts/zsh_cleanup.sh"
click node_ps_plugin "https://github.com/microsoft/codex-cli/blob/main/scripts/powershell_plugin.ps1"
click node_ps_setup "https://github.com/microsoft/codex-cli/blob/main/scripts/powershell_setup.ps1"
click node_ps_cleanup "https://github.com/microsoft/codex-cli/blob/main/scripts/powershell_cleanup.ps1"
click node_codex_query "https://github.com/microsoft/codex-cli/blob/main/src/codex_query.py"
click node_commands "https://github.com/microsoft/codex-cli/blob/main/src/commands.py"
click node_prompt_file "https://github.com/microsoft/codex-cli/blob/main/src/prompt_file.py"
click node_bash_context "https://github.com/microsoft/codex-cli/blob/main/contexts/bash-context.txt"
click node_zsh_context "https://github.com/microsoft/codex-cli/blob/main/contexts/zsh-context.txt"
click node_ps_context "https://github.com/microsoft/codex-cli/blob/main/contexts/powershell-context.txt"
click node_azure_voice_context "https://github.com/microsoft/codex-cli/blob/main/contexts/powershell-voice-cognitive-service.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bash_plugin,node_bash_setup,node_bash_cleanup,node_zsh_plugin,node_zsh_setup,node_zsh_cleanup,node_ps_plugin,node_ps_setup,node_ps_cleanup toneBlue
class node_codex_query,node_commands,node_prompt_file,node_multi_turn_state toneAmber
class node_bash_context,node_zsh_context,node_ps_context,node_azure_voice_context toneMint
class node_openai_api toneRose
```

## Components

### Shell integration

Terminal-specific setup, plugin, and cleanup scripts for each supported shell.

- [Bash plugin](https://github.com/microsoft/codex-cli/blob/main/scripts/bash_plugin.sh): shell hook · Intercepts shell input, captures the current line, and inserts generated commands back into Bash. · `scripts/bash_plugin.sh`
- [Bash setup](https://github.com/microsoft/codex-cli/blob/main/scripts/bash_setup.sh): install script · Installs Bash integration and wires the plugin into the shell environment. · `scripts/bash_setup.sh`
- [Bash cleanup](https://github.com/microsoft/codex-cli/blob/main/scripts/bash_cleanup.sh): remove script · Removes Bash integration and restores shell state. · `scripts/bash_cleanup.sh`
- [Zsh plugin](https://github.com/microsoft/codex-cli/blob/main/scripts/zsh_plugin.zsh): shell hook · Intercepts Zsh input and reinserts generated output into the active prompt buffer. · `scripts/zsh_plugin.zsh`
- [Zsh setup](https://github.com/microsoft/codex-cli/blob/main/scripts/zsh_setup.sh): install script · Installs Zsh integration and configures the terminal hook. · `scripts/zsh_setup.sh`
- [Zsh cleanup](https://github.com/microsoft/codex-cli/blob/main/scripts/zsh_cleanup.sh): remove script · Removes Zsh integration and shell hooks. · `scripts/zsh_cleanup.sh`
- [PowerShell plugin](https://github.com/microsoft/codex-cli/blob/main/scripts/powershell_plugin.ps1): shell hook · Captures PowerShell input and returns generated commands to the buffer. · `scripts/powershell_plugin.ps1`
- [PowerShell setup](https://github.com/microsoft/codex-cli/blob/main/scripts/powershell_setup.ps1): install script · Installs PowerShell integration and binds the assistant to the terminal. · `scripts/powershell_setup.ps1`
- [PowerShell cleanup](https://github.com/microsoft/codex-cli/blob/main/scripts/powershell_cleanup.ps1): remove script · Removes PowerShell integration and related hooks. · `scripts/powershell_cleanup.ps1`

### Python core

Language-agnostic orchestration, command handling, and prompt assembly.

- [Codex query](https://github.com/microsoft/codex-cli/blob/main/src/codex_query.py): orchestrator · Builds the prompt, calls OpenAI, and returns the completion for shell command generation. · `src/codex_query.py`
- [Meta commands](https://github.com/microsoft/codex-cli/blob/main/src/commands.py): control plane · Parses in-band comment commands for multi-turn mode, context management, and settings. · `src/commands.py`
- [Context loader](https://github.com/microsoft/codex-cli/blob/main/src/prompt_file.py): context config · Selects default context files and loads prompt context based on shell or mode. · `src/prompt_file.py`
- **Conversation state**: local state · Local history reused across turns by appending prior interactions into a working context file.

### Prompt assets

Few-shot context files that steer output by shell and use case.

- [Bash context](https://github.com/microsoft/codex-cli/blob/main/contexts/bash-context.txt): few-shot prompt · Bash-specific examples that guide idiomatic command generation. · `contexts/bash-context.txt`
- [Zsh context](https://github.com/microsoft/codex-cli/blob/main/contexts/zsh-context.txt): few-shot prompt · Zsh-specific examples for prompt steering and shell-idiomatic output. · `contexts/zsh-context.txt`
- [PowerShell context](https://github.com/microsoft/codex-cli/blob/main/contexts/powershell-context.txt): few-shot prompt · PowerShell-specific examples for the command-generation prompt. · `contexts/powershell-context.txt`
- [Azure voice context](https://github.com/microsoft/codex-cli/blob/main/contexts/powershell-voice-cognitive-service.txt): alternate prompt · Example alternate context for Azure Cognitive Services voice-related behavior. · `contexts/powershell-voice-cognitive-service.txt`

### External API

Remote model backend used for command generation.

- **OpenAI API**: external model · Remote completion service used as the only runtime intelligence backend.

## Connections

- Bash setup → Bash plugin: installs · Sets up the Bash terminal hook.
- Bash plugin → Codex query: requests · Forwards shell comments and current line content to the Python core.
- Bash plugin → Meta commands: meta input · Routes comment-style meta commands through the control plane.
- Bash cleanup → Bash plugin: removes · Tears down the Bash integration.
- Zsh setup → Zsh plugin: installs · Sets up the Zsh terminal hook.
- Zsh plugin → Codex query: requests · Hands off the captured request to the Python core.
- Zsh plugin → Meta commands: meta input · Recognizes in-band control commands.
- Zsh cleanup → Zsh plugin: removes · Tears down the Zsh integration.
- PowerShell setup → PowerShell plugin: installs · Sets up the PowerShell terminal hook.
- PowerShell plugin → Codex query: requests · Forwards captured input to the Python core.
- PowerShell plugin → Meta commands: meta input · Handles comment-like control commands.
- PowerShell cleanup → PowerShell plugin: removes · Tears down the PowerShell integration.
- Codex query → Context loader: loads · Selects the active prompt context before building the request.
- Context loader → Bash context: default shell · Uses Bash examples when Bash is the active shell.
- Context loader → Zsh context: default shell · Uses Zsh examples when Zsh is the active shell.
- Context loader → PowerShell context: default shell · Uses PowerShell examples when PowerShell is the active shell.
- Context loader → Azure voice context: alternate mode · Supports swapping in alternate few-shot context files.
- Meta commands → Conversation state: updates · Starts, stops, loads, saves, or views local conversational state.
- Codex query → Conversation state: includes · Appends prior interactions when multi-turn mode is active.
- Codex query → OpenAI API: calls · Sends the constructed prompt to the external model backend.
- OpenAI API → Codex query: returns · Provides the generated shell completion back to the orchestrator.
- Meta commands → Codex query: routes · Separates meta commands from ordinary natural-language requests.