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

Author: abhishek-oai

codex-rs/README.md

@@ -91,6 +91,17 @@ 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. This feature is supported on Unix platforms (macOS, Linux). On other platforms, input beginning with `!` is treated as a normal message. For example:
+ 
+```text
+!ls -la src
+```
+ 
+- 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 150 lines). You can change this via `tui.local_shell_max_lines` in `config.toml`. See [`config.md`](./config.md#tui).
 
 ## 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

@@ -87,6 +87,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;
@@ -282,6 +284,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.
@@ -536,6 +539,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,
@@ -1047,6 +1051,114 @@ 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 } => {
+                #[cfg(unix)]
+                {
+                    // 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;
+                            }
+                        }
+                    });
+                }
+                #[cfg(not(unix))]
+                {
+                    let _ = &raw_cmd; // silence unused var on non-Unix
+                    // Local exec is only supported on Unix (includes macOS). Immediately reply with an error.
+                    let end_event = Event {
+                        id: sub.id.clone(),
+                        msg: EventMsg::LocalCommandEnd(LocalCommandEndEvent {
+                            stdout: String::new(),
+                            stderr: "local exec is not supported on this platform".to_string(),
+                            exit_code: 1,
+                        }),
+                    };
+                    let _ = sess.tx_event.send(end_event).await;
+                }
             }
             Op::OverrideTurnContext {
                 cwd,

codex-rs/core/src/config_types.rs

@@ -74,9 +74,30 @@ pub enum HistoryPersistence {
     None,
 }
 
+pub const LOCAL_SHELL_MAX_LINES_DEFAULT: usize = 150;
+
+fn local_shell_max_lines_default() -> usize {
+    LOCAL_SHELL_MAX_LINES_DEFAULT
+}
+
 /// Collection of settings that are specific to the TUI.
-#[derive(Deserialize, Debug, Clone, PartialEq, Default)]
-pub struct Tui {}
+#[derive(Deserialize, Debug, Clone, PartialEq)]
+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 = "local_shell_max_lines_default")]
+    pub local_shell_max_lines: usize,
+}
+
+impl Default for Tui {
+    fn default() -> Self {
+        Self {
+            local_shell_max_lines: LOCAL_SHELL_MAX_LINES_DEFAULT,
+        }
+    }
+}
 
 #[derive(Deserialize, Debug, Clone, PartialEq, Default)]
 pub struct SandboxWorkspaceWrite {

codex-rs/core/src/lib.rs

@@ -26,6 +26,7 @@ mod flags;
 pub mod git_info;
 mod is_safe_command;
 pub mod landlock;
+mod local_exec;
 mod mcp_connection_manager;
 mod mcp_tool_call;
 mod message_history;

codex-rs/core/src/local_exec.rs

@@ -0,0 +1,55 @@
+use std::sync::Mutex;
+
+pub(crate) struct LocalExecRuntime {
+    pgid: Mutex<Option<i32>>,
+}
+
+impl LocalExecRuntime {
+    pub(crate) fn new() -> Self {
+        Self {
+            pgid: Mutex::new(None),
+        }
+    }
+}
+
+/// Configure child process before exec: on Unix, create a new process group so
+/// we can signal the entire tree later.
+pub(crate) fn configure_child(cmd: &mut tokio::process::Command) {
+    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>) {
+    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);
+        }
+    }
+}
+
+/// Clear any recorded child state after it exits or upon spawn failure.
+pub(crate) fn clear(runtime: &LocalExecRuntime) {
+    if let Ok(mut guard) = runtime.pgid.lock() {
+        *guard = None;
+    }
+}
+
+/// Attempt to interrupt a recorded child process tree.
+pub(crate) fn interrupt(runtime: &LocalExecRuntime) {
+    if let Ok(mut guard) = runtime.pgid.lock()
+        && let Some(pgid) = guard.take()
+    {
+        unsafe {
+            let _ = libc::kill(-pgid, libc::SIGINT);
+        }
+    }
+}

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 {