[tui][core] ! commands passthrough to shell for execution

Author: abhishek-oai

codex-rs/README.md

@@ -91,6 +91,18 @@ codex --sandbox danger-full-access
 ```
 
 The same setting can be persisted in `~/.codex/config.toml` via the top-level `sandbox_mode = "MODE"` key, e.g. `sandbox_mode = "workspace-write"`.
+ 
+### Run a local command with `!`
+ 
+Inside the TUI, prefix your input with `!` to run it locally in your shell instead of sending it to the model. For example:
+ 
+```text
+!ls -la src
+```
+ 
+- While running, Codex shows a “working” indicator with a spinner.
+- Press Ctrl-C to interrupt the running command (sends SIGINT on Unix).
+- Output is shown directly in the chat history with a sensible line cap (default 100 lines). You can change this via `tui.local_shell_max_lines` in `config.toml`. See [`config.md`](./config.md#tuilocal_shell_max_lines).
 
 ## Code Organization
 

codex-rs/config.md

@@ -560,5 +560,7 @@ Options that are specific to the TUI.
 
 ```toml
 [tui]
-# More to come here
+# Maximum number of lines to show for locally executed `!` commands
+# in the TUI before summarizing with an ellipsis. Defaults to 100.
+local_shell_max_lines = 150
 ```

codex-rs/core/src/codex.rs

@@ -86,6 +86,8 @@ use crate::protocol::ExecCommandBeginEvent;
 use crate::protocol::ExecCommandEndEvent;
 use crate::protocol::FileChange;
 use crate::protocol::InputItem;
+use crate::protocol::LocalCommandBeginEvent;
+use crate::protocol::LocalCommandEndEvent;
 use crate::protocol::Op;
 use crate::protocol::PatchApplyBeginEvent;
 use crate::protocol::PatchApplyEndEvent;
@@ -280,6 +282,7 @@ pub(crate) struct Session {
     codex_linux_sandbox_exe: Option<PathBuf>,
     user_shell: shell::Shell,
     show_raw_agent_reasoning: bool,
+    local_exec: crate::local_exec::LocalExecRuntime,
 }
 
 /// The context needed for a single turn of the conversation.
@@ -533,6 +536,7 @@ impl Session {
             codex_linux_sandbox_exe: config.codex_linux_sandbox_exe.clone(),
             user_shell: default_shell,
             show_raw_agent_reasoning: config.show_raw_agent_reasoning,
+            local_exec: crate::local_exec::LocalExecRuntime::new(),
         });
 
         // record the initial user instructions and environment context,
@@ -1044,6 +1048,94 @@ async fn submission_loop(
         match sub.op {
             Op::Interrupt => {
                 sess.interrupt_task();
+                // Also interrupt any running local exec.
+                crate::local_exec::interrupt(&sess.local_exec);
+            }
+            Op::LocalExec { raw_cmd } => {
+                // Wrap into a default shell invocation (bash -lc)
+                let mut argv = vec!["bash".to_string(), "-lc".to_string(), raw_cmd];
+                // Allow shell translation (e.g., PowerShell, zsh profile) if applicable
+                if let Some(cmd) = sess
+                    .user_shell
+                    .format_default_shell_invocation(argv.clone())
+                {
+                    argv = cmd;
+                }
+
+                // Emit LocalCommandBegin
+                let begin_event = Event {
+                    id: sub.id.clone(),
+                    msg: EventMsg::LocalCommandBegin(LocalCommandBeginEvent {
+                        command: argv.clone(),
+                    }),
+                };
+                let _ = sess.tx_event.send(begin_event).await;
+
+                // Spawn child process in background to keep submission loop responsive
+                let cwd_to_use = turn_context.cwd.clone();
+                let env = create_env(&turn_context.shell_environment_policy);
+                let program = argv.first().cloned().unwrap_or_default();
+                let args = argv.iter().skip(1).cloned().collect::<Vec<_>>();
+                let sess_for_local = sess.clone();
+                let tx_event = sess.tx_event.clone();
+                let sub_id = sub.id.clone();
+                tokio::spawn(async move {
+                    let mut cmd = tokio::process::Command::new(&program);
+                    cmd.args(&args)
+                        .current_dir(&cwd_to_use)
+                        .stdout(std::process::Stdio::piped())
+                        .stderr(std::process::Stdio::piped());
+
+                    crate::local_exec::configure_child(&mut cmd);
+
+                    // Start from a clean environment to avoid inheriting unpredictable or
+                    // sensitive variables from the parent process (PATH tweaks, proxies,
+                    // credentials, locale, toolchain settings, etc.). We then repopulate
+                    // only the approved set via `create_env(...)` for deterministic, safe
+                    // command execution aligned with the session's policy.
+                    cmd.env_clear();
+                    for (k, v) in env.into_iter() {
+                        cmd.env(k, v);
+                    }
+
+                    match cmd.spawn() {
+                        Ok(child) => {
+                            crate::local_exec::record_child(&sess_for_local.local_exec, child.id());
+                            let out_res = child.wait_with_output().await;
+                            crate::local_exec::clear(&sess_for_local.local_exec);
+
+                            let (exit_code, stdout, stderr) = match out_res {
+                                Ok(output) => (
+                                    output.status.code().unwrap_or(-1),
+                                    String::from_utf8_lossy(&output.stdout).to_string(),
+                                    String::from_utf8_lossy(&output.stderr).to_string(),
+                                ),
+                                Err(e) => (1, String::new(), format!("failed to wait: {e}")),
+                            };
+                            let end_event = Event {
+                                id: sub_id.clone(),
+                                msg: EventMsg::LocalCommandEnd(LocalCommandEndEvent {
+                                    stdout,
+                                    stderr,
+                                    exit_code,
+                                }),
+                            };
+                            let _ = tx_event.send(end_event).await;
+                        }
+                        Err(e) => {
+                            crate::local_exec::clear(&sess_for_local.local_exec);
+                            let end_event = Event {
+                                id: sub_id.clone(),
+                                msg: EventMsg::LocalCommandEnd(LocalCommandEndEvent {
+                                    stdout: String::new(),
+                                    stderr: format!("failed to spawn: {e}"),
+                                    exit_code: 1,
+                                }),
+                            };
+                            let _ = tx_event.send(end_event).await;
+                        }
+                    }
+                });
             }
             Op::OverrideTurnContext {
                 cwd,

codex-rs/core/src/config_types.rs

@@ -76,7 +76,14 @@ pub enum HistoryPersistence {
 
 /// Collection of settings that are specific to the TUI.
 #[derive(Deserialize, Debug, Clone, PartialEq, Default)]
-pub struct Tui {}
+pub struct Tui {
+    /// Maximum number of lines to display for the output of a locally executed
+    /// shell command entered via a leading `!` in the composer. Output beyond
+    /// this limit is summarized with an ellipsis in the UI. The full output is
+    /// still retained in the transcript.
+    #[serde(default)]
+    pub local_shell_max_lines: Option<usize>,
+}
 
 #[derive(Deserialize, Debug, Clone, PartialEq, Default)]
 pub struct SandboxWorkspaceWrite {

codex-rs/core/src/lib.rs

@@ -29,6 +29,7 @@ pub mod landlock;
 mod mcp_connection_manager;
 mod mcp_tool_call;
 mod message_history;
+mod local_exec;
 mod model_provider_info;
 pub mod parse_command;
 pub use model_provider_info::BUILT_IN_OSS_MODEL_PROVIDER_ID;

codex-rs/core/src/local_exec.rs

@@ -0,0 +1,98 @@
+use std::sync::Mutex;
+
+#[cfg(unix)]
+pub(crate) struct LocalExecRuntime {
+    pgid: Mutex<Option<i32>>,
+}
+
+#[cfg(not(unix))]
+pub(crate) struct LocalExecRuntime {
+    running: Mutex<bool>,
+}
+
+impl LocalExecRuntime {
+    pub(crate) fn new() -> Self {
+        #[cfg(unix)]
+        {
+            Self {
+                pgid: Mutex::new(None),
+            }
+        }
+        #[cfg(not(unix))]
+        {
+            Self {
+                running: Mutex::new(false),
+            }
+        }
+    }
+}
+
+/// Configure child process before exec: on Unix, create a new process group so
+/// we can signal the entire tree later. No-op on other platforms.
+pub(crate) fn configure_child(cmd: &mut tokio::process::Command) {
+    #[cfg(unix)]
+    unsafe {
+        cmd.pre_exec(|| {
+            libc::setpgid(0, 0);
+            Ok(())
+        });
+    }
+}
+
+/// Record the spawned child so future interrupts can target it.
+pub(crate) fn record_child(runtime: &LocalExecRuntime, pid_opt: Option<u32>) {
+    #[cfg(unix)]
+    {
+        if let Some(pid_u32) = pid_opt {
+            let pid = pid_u32 as i32;
+            // If getpgid fails, fall back to pid.
+            let pgid = unsafe { libc::getpgid(pid) };
+            let value = if pgid > 0 { pgid } else { pid };
+            if let Ok(mut guard) = runtime.pgid.lock() {
+                *guard = Some(value);
+            }
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        if let Ok(mut guard) = runtime.running.lock() {
+            *guard = true;
+        }
+    }
+}
+
+/// Clear any recorded child state after it exits or upon spawn failure.
+pub(crate) fn clear(runtime: &LocalExecRuntime) {
+    #[cfg(unix)]
+    {
+        if let Ok(mut guard) = runtime.pgid.lock() {
+            *guard = None;
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        if let Ok(mut guard) = runtime.running.lock() {
+            *guard = false;
+        }
+    }
+}
+
+/// Attempt to interrupt a recorded child process tree.
+pub(crate) fn interrupt(runtime: &LocalExecRuntime) {
+    #[cfg(unix)]
+    {
+        if let Ok(mut guard) = runtime.pgid.lock()
+            && let Some(pgid) = guard.take()
+        {
+            unsafe {
+                let _ = libc::kill(-pgid, libc::SIGINT);
+            }
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        if let Ok(mut guard) = runtime.running.lock() {
+            *guard = false;
+        }
+    }
+}

codex-rs/exec/src/event_processor_with_human_output.rs

@@ -14,6 +14,7 @@ use codex_core::protocol::EventMsg;
 use codex_core::protocol::ExecCommandBeginEvent;
 use codex_core::protocol::ExecCommandEndEvent;
 use codex_core::protocol::FileChange;
+use codex_core::protocol::LocalCommandEndEvent;
 use codex_core::protocol::McpInvocation;
 use codex_core::protocol::McpToolCallBeginEvent;
 use codex_core::protocol::McpToolCallEndEvent;
@@ -269,7 +270,7 @@ impl EventProcessor for EventProcessorWithHumanOutput {
                 call_id,
                 command,
                 cwd,
-                parsed_cmd: _,
+                ..
             }) => {
                 self.call_id_to_command.insert(
                     call_id.clone(),
@@ -321,6 +322,25 @@ impl EventProcessor for EventProcessorWithHumanOutput {
                 }
                 println!("{}", truncated_output.style(self.dimmed));
             }
+            EventMsg::LocalCommandBegin(_) => {
+                // no-op; print only at end
+            }
+            EventMsg::LocalCommandEnd(LocalCommandEndEvent {
+                stdout,
+                stderr,
+                exit_code,
+            }) => match exit_code {
+                0 => {
+                    for line in stdout.lines().take(MAX_OUTPUT_LINES_FOR_EXEC_TOOL_CALL) {
+                        println!("{}", line.style(self.dimmed));
+                    }
+                }
+                _ => {
+                    for line in stderr.lines().take(MAX_OUTPUT_LINES_FOR_EXEC_TOOL_CALL) {
+                        println!("{}", line.style(self.dimmed));
+                    }
+                }
+            },
             EventMsg::McpToolCallBegin(McpToolCallBeginEvent {
                 call_id: _,
                 invocation,

codex-rs/mcp-server/src/codex_tool_runner.rs

@@ -267,6 +267,8 @@ async fn run_codex_tool_session_inner(
                     | EventMsg::ExecCommandBegin(_)
                     | EventMsg::ExecCommandOutputDelta(_)
                     | EventMsg::ExecCommandEnd(_)
+                    | EventMsg::LocalCommandBegin(_)
+                    | EventMsg::LocalCommandEnd(_)
                     | EventMsg::BackgroundEvent(_)
                     | EventMsg::StreamError(_)
                     | EventMsg::PatchApplyBegin(_)

codex-rs/protocol/src/protocol.rs

@@ -44,6 +44,12 @@ pub enum Op {
     /// Abort current task.
     /// This server sends [`EventMsg::TurnAborted`] in response.
     Interrupt,
+    /// User-initiated local command execution (non-model). Runs a shell
+    /// command immediately without involving the model.
+    LocalExec {
+        /// Raw command following a "!". Only whitespace is stripped.
+        raw_cmd: String,
+    },
 
     /// Input from the user
     UserInput {
@@ -447,6 +453,12 @@ pub enum EventMsg {
 
     ExecCommandEnd(ExecCommandEndEvent),
 
+    /// Local user-initiated command (bang command) begin.
+    LocalCommandBegin(LocalCommandBeginEvent),
+
+    /// Local user-initiated command (bang command) end.
+    LocalCommandEnd(LocalCommandEndEvent),
+
     ExecApprovalRequest(ExecApprovalRequestEvent),
 
     ApplyPatchApprovalRequest(ApplyPatchApprovalRequestEvent),
@@ -704,6 +716,22 @@ pub struct ExecCommandEndEvent {
     pub formatted_output: String,
 }
 
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct LocalCommandBeginEvent {
+    /// The command to be executed (post shell-translation), for transparency.
+    pub command: Vec<String>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct LocalCommandEndEvent {
+    /// Captured stdout
+    pub stdout: String,
+    /// Captured stderr
+    pub stderr: String,
+    /// The command's exit code.
+    pub exit_code: i32,
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[serde(rename_all = "snake_case")]
 pub enum ExecOutputStream {