shell_session
Run shell commands in a background process for installs, scripts, and file operations. Executes commands to completion and returns exit codes.
Instructions
Purpose: Reliable background shell channel backed by a real OS process (stdin/stdout/stderr + exit code). Use this for installs, scripts, file ops, and any command that must actually finish — not the visible-terminal terminal tool.
Details: Actions: start (spawn hidden shell), write (stdin + optional wait/read), read (drain ring buffer), exec (one-shot run-to-completion with exit code), list, stop. Never reports ok:true on write unless stdin accepted AND process still tracked; exec only returns ok:true when exitCode===0. Non-zero exits return ok:false code:ShellSessionNonZeroExit with stdout/stderr. Default shell: powershell on Windows, bash elsewhere. Independent of GUI focus, IME, clipboard, and SoM terminal pollution.
Prefer: Prefer shell_session({action:'exec', input:'...'}) for one-shot commands. Prefer start+write+read for interactive multi-step shells. Keep terminal for when you must drive a visible console window the user is watching.
Caveats: This does NOT open a visible window — do not use it when the user needs to see the console UI. Ring buffer is capped (default 1MB). Max 16 concurrent sessions. On Windows, powershell/cmd are windowsHide; do not send Ctrl+C via keyboard tools into these sessions (use action:'stop').
Examples:
shell_session({action:'exec', input:'whoami'}) → {ok:true, exitCode:0, stdout:'...'}
shell_session({action:'start', id:'ops', shell:'powershell'}) → {ok:true, session:{pid,...}}
shell_session({action:'write', id:'ops', input:'Get-ChildItem', waitMs:500}) → stdout/stderr
shell_session({action:'read', id:'ops', clear:true})
shell_session({action:'stop', id:'ops'})
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||