pi-pwsh

A PowerShell-native shell tool for pi, with persistent tasks, interactive terminal sessions, and user requests.

Why pi-pwsh

Windows shell work is more reliable when the tool name, syntax, process model, and paths all agree. pi-pwsh gives the model a real pwsh tool instead of asking it to translate bash assumptions at runtime.

• PowerShell-native — commands use PowerShell 7 syntax and Windows paths from the start.
• Waits for short work, then notifies automatically — every command becomes a persistent task; quick work returns directly, while longer work continues in the background without polling.
• Durable across sessions — tasks survive later tool calls, /reload, pi restarts, wait timeouts, and tool aborts.
• Progressive helper loading — PTY and user-request helpers are loaded only when their PowerShell functions are referenced; detailed help remains available through Get-PtyHelp and Get-PiRequestHelp.
• Real interactive sessions — persistent terminal sessions support REPLs, prompts, and full-screen applications.
• Correct Windows behavior — UTF-8 source and output, final-command exit codes, .cmd fallback, process-tree cleanup, and streaming output are handled for you.
• Strict, optional configuration — select the PowerShell executable and control profiles, execution policy, !/!!, stop-on-error, and Python UTF-8 defaults without expanding the base prompt.
• Optional elevation guidance — an available Windows Sudo installation is surfaced to the model automatically.

This lets pi use PowerShell without blocking on long-running work: task persistence, notifications, terminal sessions, and UI requests stay behind the extension.

Compared with pi's built-in PowerShell tool

Pi 0.84.3 added an optional built-in powershell tool for Windows. It is a lightweight foreground command executor built on pi's existing shell-tool infrastructure. pi-pwsh adds a persistent task and interaction layer for work that must continue independently of one tool call.

| Area | Pi built-in powershell | pi-pwsh | Better fit | | --- | --- | --- | --- | | Basic command execution | Built into pi with no extension dependencies | Separate extension with task, PTY, and coordination dependencies | Built-in for simple commands | | Shared baseline | Runs in the current directory, captures stdout/stderr, bounds returned output, and can terminate a process tree | Same | Equivalent | | Foreground experience | Waits for completion and streams live output into the current tool card | Waits up to 60 seconds by default and returns a task snapshot; longer work continues in the background | Built-in for live streaming; pi-pwsh for bounded waiting with persistence | | Background work | No managed background-task API or task ID | Every command is a persistent task with inspect, wait, and stop operations | pi-pwsh | | Abort and timeout | Aborting the tool call or reaching its timeout terminates the process tree | Aborting or timing out a wait leaves the task running; only stop=true terminates it | Depends on whether work should stop or continue | | Readiness and completion | No readiness detection or deferred notification | Reports readiness from notifyOn, then completion, failure, or cancellation without polling | pi-pwsh | | Durability and output | Returns the last 2,000 lines or 50 KiB and writes truncated full output to a temporary file | Persists task metadata and full logs across later calls, /reload, and pi restarts; snapshots return the latest 50 KiB and terminal records are retained for 24 hours | pi-pwsh | | Interactive programs | Non-interactive process with no stdin or terminal session | Persistent ConPTY sessions with input, screen snapshots, transcript reads, waiting, resizing, and process control | pi-pwsh | | User interaction | No command-to-UI request API | Commands can request text, confirmation, selection, masked input, or secret input sent directly to a PTY | pi-pwsh | | PowerShell runtime | Prefers pwsh.exe but falls back to Windows PowerShell; fixed -NoProfile -NonInteractive -ExecutionPolicy Bypass | Requires and verifies PowerShell 7+; executable, profile loading, execution policy, and stop-on-error behavior are configurable | Built-in for broad availability; pi-pwsh for consistent behavior | | Encoding and source transport | Sets console output to UTF-8 and passes the command as a process argument | Sends UTF-8 source through stdin, configures PowerShell and native-command encodings, strips styling for task output, and can default Python to unbuffered UTF-8 | pi-pwsh | | Exit status | Reports the outer PowerShell process exit code | Preserves the final native command's exact exit code and maps final PowerShell command failures consistently | pi-pwsh | | ! and !! shortcuts | Continue to use Bash | Use the configured PowerShell runtime by default; this replacement is optional | pi-pwsh for a consistent shell | | Pi integration | Core tool, available through defaultTools and the SDK, with current PI_* session/model environment variables | Custom task UI, coordinated notifications, and the shared /tasks catalog | Depends on the integration needed |

Choose the built-in tool when commands are short-lived and native pi integration matters most. Choose pi-pwsh for builds, tests, servers, watchers, interactive applications, durable output, or commands that need to ask the user for input. The tools have different names and can coexist, but enabling both gives the model two PowerShell tools with different lifecycle semantics; most setups should select one.

Features

Background tasks and coordinated notifications

Every pwsh command starts a persistent task. When wait is omitted, the tool waits up to defaultWaitSeconds (60 by default): work that finishes in that window returns its result in the same call, while longer work returns a running task and continues in the background. Pass wait: 0 to return immediately. There is no separate job mode and no need to wrap the command in another background layer.

Deferred completion, failure, and cancellation are reported automatically. Long-running services can also announce readiness as soon as a chosen literal appears in their output, without ending the task. Inspecting an existing task without wait uses the same configured default; a timeout or cancelled wait leaves it running.

Each task remains available through its ID for later status and output snapshots or explicit process-tree termination. Snapshots are bounded and repeatable rather than consumable. Task state and notification markers survive /reload and pi restarts, and terminal records are retained for 24 hours.

Interactive terminals

Persistent terminal sessions support REPLs, prompts, and full-screen terminal applications:

Start-Pty -Command 'python' -Name py
Get-PtyScreen -Name py
Send-PtyInput -Name py -Text 'print(6 * 7)' -Enter
Wait-Pty -Name py | Receive-Pty
Stop-Pty -Name py | Remove-Pty

Get-PtyHelp

PTYs live for the current pi session. Aborting an ordinary pwsh task wait does not stop an existing PTY.

Shell shortcuts

Pi's ! and !! shell shortcuts use the same PowerShell runtime and execution behavior as the pwsh tool. Set replaceUserBash to false if those shortcuts should retain pi's default shell behavior.

User requests

PowerShell commands can ask through pi's UI for text, confirmation, selection, or masked input:

Request-PiInput -Title 'Setup' -Prompt 'Display name'
$ok = Request-PiConfirmation -Title 'Deploy' -Message 'Continue?'
$region = Request-PiSelection -Title 'Region' -Options @('cn', 'us', 'eu')

Get-PiRequestHelp

For terminal logins, Request-PiPtyInput -Secret sends input directly from the UI to a PTY without returning the secret to PowerShell or the model.

Task notifications and TUI

Readiness, completion, failure, and cancellation are reported automatically. Notifications cooperate and aggregate with installed @4fu background-task plugins. Successfully retrieving a ready or terminal result explicitly cancels its pending notification, avoiding repeated status and output.

The shared Tasks widget combines active work and retained terminal records from participating plugins. Run /tasks for the complete bounded catalog. Pwsh tool calls keep their compact TUI and expose task details and bounded output when expanded. Upgrade all participating @4fu task plugins together so they use the same shared task-presentation generation.

Configuration

Configuration is optional. Create ~/.pi/agent/pwsh.json and run /reload after changing it:

{
  "executable": "auto",
  "loadProfile": false,
  "executionPolicy": "Bypass",
  "replaceUserBash": true,
  "stopOnError": false,
  "pythonUtf8": true,
  "pythonUnbuffered": true,
  "defaultWaitSeconds": 60
}

| Setting | Default | Effect | | --- | --- | --- | | executable | "auto" | Probes PowerShell 7 and pins its executable path for the session. Set an absolute Windows path to select a specific pwsh.exe. | | loadProfile | false | Loads the user's PowerShell profile for task commands and PTYs. | | executionPolicy | "Bypass" | Execution policy passed to user PowerShell processes. Use null to omit the argument. | | replaceUserBash | true | Routes pi's ! and !! shortcuts through the same PowerShell operations. | | stopOnError | false | Sets $ErrorActionPreference = 'Stop' before user commands. | | pythonUtf8 | true | Defaults PYTHONIOENCODING=utf-8 and PYTHONUTF8=1 unless already set. | | pythonUnbuffered | true | Defaults PYTHONUNBUFFERED=1 unless already set. | | defaultWaitSeconds | 60 | Wait used when wait is omitted for new commands and existing task queries. Accepts an integer from 0 to 300; 0 returns immediately. |

Environment variables override the JSON file:

| Environment variable | Setting | | --- | --- | | PI_PWSH_CONFIG | Alternate configuration file path | | PI_PWSH_EXECUTABLE | executable | | PI_PWSH_LOAD_PROFILE | loadProfile | | PI_PWSH_EXECUTION_POLICY | executionPolicy | | PI_PWSH_REPLACE_USER_BASH | replaceUserBash | | PI_PWSH_STOP_ON_ERROR | stopOnError | | PI_PWSH_PYTHON_UTF8 | pythonUtf8 | | PI_PWSH_PYTHON_UNBUFFERED | pythonUnbuffered | | PI_PWSH_DEFAULT_WAIT_SECONDS | defaultWaitSeconds |

Boolean environment values accept true/false, 1/0, yes/no, and on/off. PI_PWSH_DEFAULT_WAIT_SECONDS accepts a decimal integer from 0 to 300. Configuration is strict: unknown fields, invalid values, or an unavailable configured executable produce an error instead of silently changing shell behavior.

Recommended Windows setup

Pair this extension with pi-bin-hints. It detects which commonly used modern command-line programs are installed and tells pi through one small, stable prompt line.

A useful Windows baseline is:

• PowerShell 7
• Git for Windows
• rg (ripgrep), fd, jq, fzf, and bat as useful optional additions

winget or Scoop can install most of these tools. pi-bin-hints detects them at the next pi session start, so the model can prefer them without probing PATH on every turn.

Requirements

• Node.js 22.19 or newer.
• PowerShell 7+, discoverable through PATH, the standard installation location, or an absolute executable path in pwsh.json.
• Windows 10 version 1809 or newer for ConPTY sessions on Windows.
• Permission for the trusted node-pty native install script when your package manager restricts dependency scripts.

Installation

pi install npm:@4fu/pi-pwsh

Try it for one run without installing:

pi -e npm:@4fu/pi-pwsh

From source

Run npm install, then add the repository path to ~/.pi/agent/settings.json:

{
  "extensions": ["C:/path/to/pi-pwsh"]
}

Run /reload in pi after changing the extension.

Development

npm install
npm test
npm pack --dry-run

The test suite covers configuration and runtime resolution, UTF-8 source transport, exit codes, persistent tasks, notifications, timeouts, process-tree cleanup, PTYs, and UI requests.

License

MIT