How microsoft/codex-cli works
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: codex_query.py Codex query · prompt_file.py Context loader · commands.py Meta commands · bash_plugin.sh Bash plugin
Components 18
Shell integration
Terminal-specific setup, plugin, and cleanup scripts for each supported shell.
- Bash plugin · Intercepts shell input, captures the current line, and inserts generated commands back into Bash.
scripts/bash_plugin.sh - Bash setup · Installs Bash integration and wires the plugin into the shell environment.
scripts/bash_setup.sh - Bash cleanup · Removes Bash integration and restores shell state.
scripts/bash_cleanup.sh - Zsh plugin · Intercepts Zsh input and reinserts generated output into the active prompt buffer.
scripts/zsh_plugin.zsh - Zsh setup · Installs Zsh integration and configures the terminal hook.
scripts/zsh_setup.sh - Zsh cleanup · Removes Zsh integration and shell hooks.
scripts/zsh_cleanup.sh - PowerShell plugin · Captures PowerShell input and returns generated commands to the buffer.
scripts/powershell_plugin.ps1 - PowerShell setup · Installs PowerShell integration and binds the assistant to the terminal.
scripts/powershell_setup.ps1 - PowerShell cleanup · Removes PowerShell integration and related hooks.
scripts/powershell_cleanup.ps1
Python core
Language-agnostic orchestration, command handling, and prompt assembly.
- Codex query · Builds the prompt, calls OpenAI, and returns the completion for shell command generation.
src/codex_query.py - Meta commands · Parses in-band comment commands for multi-turn mode, context management, and settings.
src/commands.py - Context loader · Selects default context files and loads prompt context based on shell or mode.
src/prompt_file.py - Conversation 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 · Bash-specific examples that guide idiomatic command generation.
contexts/bash-context.txt - Zsh context · Zsh-specific examples for prompt steering and shell-idiomatic output.
contexts/zsh-context.txt - PowerShell context · PowerShell-specific examples for the command-generation prompt.
contexts/powershell-context.txt - Azure voice context · 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 · Remote completion service used as the only runtime intelligence backend.
Connections 22
- 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.