Prompt Time Substitution
Introduction
Welcome back to Mastering Advanced AI Tooling in Codex! In previous lessons, we configured Codex through config.toml, enabled secure web search, and built custom commands (both simple and argument-based) that encode project-specific workflows.
Today, we are learning about inline shell capture: the ability to run local shell commands directly from the Codex CLI using the ! prefix. When we execute these commands, Codex captures their output and injects it into our conversation history as context. This transforms our interactions from static questions into dynamic ones that reflect the current state of our repository. We will build a practical workflow that gathers repository status, recent commits, and current changes, then asks Codex to propose next steps based on real-time information.
Understanding Inline Shell Capture
Before diving into syntax, let us understand what inline shell capture solves. When we ask Codex to help with our codebase, it needs context: which files changed, which commits occurred recently, and what is currently staged. Without this information, Codex provides generic advice; with it, responses become specific and actionable.
We could manually run commands like git status and git diff in a separate terminal, copy their output, and paste it into our prompt. This works but creates friction: we repeat the same steps every time, risk copying stale data, and may forget important context. Inline shell capture automates this pattern.
Here is how it works: when we prefix a line with !, Codex executes that command locally, captures its output (stdout and stderr), and adds the captured text to the conversation history as if we had typed it ourselves. The language model then sees this output as user-provided context when processing our next question. This means a command like !git status runs on our machine, produces output, and that output becomes available for the model to reason over—without us copying and pasting anything.
The Shell Escape Syntax
Codex uses the exclamation mark (!) prefix to mark lines as local shell commands. This syntax mirrors environments like IPython and Jupyter notebooks:
Everything after the exclamation mark is treated as a shell command and executed in the session's current working directory (typically your repo root). The command runs subject to your approval settings and sandbox limits—if you have configured approval_policy = "on-request" or restrictive sandbox_mode, you may be prompted or blocked depending on what the command does.
Multiple commands can be run in sequence:
Each command executes independently, captures its own output, and adds that output to the conversation. Once all commands complete, we can ask our question, and the model will have access to all the captured context.
