pi-pwsh-native

Native PowerShell 7 tooling for the Pi coding agent on Windows.

pi-pwsh-native replaces Pi's model-callable bash tool with a tool named pwsh and routes interactive !/!! commands through the same verified PowerShell executable. It does not translate Bash syntax and does not silently fall back to another shell.

How this differs from @4fu/pi-pwsh

This package derives from @4fu/pi-pwsh, but it is a deliberately leaner shell replacement rather than a drop-in feature superset. The comparison below is against the audited upstream baseline, @4fu/pi-pwsh@0.6.2.

Area	pi-pwsh-native	@4fu/pi-pwsh@0.6.2
Primary focus	Predictable, dependency-free foreground PowerShell execution	Feature-rich PowerShell execution with persistent jobs and interactive sessions
Model shell tool	Replaces bash with pwsh	Replaces bash with pwsh
Pi discovery tools	Preserves ls, find, and grep by default	Disables ls, find, and grep in favor of PowerShell
Interactive ! / !!	Routes both through the verified PowerShell runtime	Does not replace Pi's user_bash handling
PowerShell executable	Resolves, verifies, and retains an absolute PowerShell 7 path	Probes PowerShell 7, while foreground execution invokes pwsh by name
Execution policy	No override by default; Bypass must be explicitly configured	Passes -ExecutionPolicy Bypass
Command transport	UTF-8 base64 source over stdin, avoiding Windows command-line limits	Injected source passed through -Command
.cmd fallback	No retry through cmd.exe	Can retry failed direct command-shim execution through cmd /c
Background jobs and PTYs	Intentionally omitted from the lean core	Includes detached jobs, ConPTY sessions, and user-request helpers
Runtime dependencies	None	Uses node-pty and @xterm/headless
Configuration	Strict JSON configuration plus environment overrides	Primarily opinionated built-in behavior
Missing/invalid PowerShell	Fails visibly without silently restoring Bash	Leaves the built-in Bash tool active when PowerShell is unavailable

Choose pi-pwsh-native when you want a small, auditable PowerShell 7 replacement with dedicated Pi file/search tools left intact. Choose @4fu/pi-pwsh when persistent background jobs, PTYs, and its interactive helper layer are more important. Do not enable competing shell-adapter extensions simultaneously.

Design

• Registers a real pwsh tool so models are prompted to write PowerShell, not POSIX shell syntax.
• Reuses Pi's built-in shell tool definition for streaming previews, the standard renderer, non-zero exit handling, tail truncation (2,000 lines / 50 KB), and full-output temporary files.
• Keeps Pi's dedicated read, write, edit, ls, find, and grep tools active by default. Dedicated tools avoid unnecessary PowerShell startup and usually produce more focused output.
• Routes user-entered !command and !!command through PowerShell by default while preserving Pi's context-inclusion semantics.
• Requires PowerShell 7 or newer. Windows PowerShell 5.1 and Bash are not fallbacks.
• Resolves and uses an absolute pwsh.exe path for every command.
• Uses an ASCII bootstrap plus base64-over-stdin source transport. This preserves Unicode and multiline source without Windows command-line length limitations.
• Forces plain UTF-8 output without a BOM and preserves native executable exit codes.
• Kills the full process tree on timeout or cancellation.
• Has no runtime dependencies, native install scripts, telemetry, or network calls.

Requirements

• Windows
• PowerShell 7+
• Node.js 22.19 or newer
• Pi 0.83.0 or newer (before 1.0)

The current release is tested against:

• Pi 0.83.0 and 0.84.2
• PowerShell 7.6.5

Installation

Install the pinned npm release:

pi install npm:pi-pwsh-native@0.1.4

Alternatively, install the public GitHub package directly:

pi install git:github.com/takomine/pi-pwsh-native

Try from source

Set-Location D:\pi\pi-pwsh-native
npm install --ignore-scripts
pi -e .\src\index.ts

For global development use, add the source path to ~/.pi/agent/settings.json:

{
  "extensions": [
    "D:/pi/pi-pwsh-native/src/index.ts"
  ]
}

Restart Pi or run /reload after changing extension code or configuration.

The npm package name is pi-pwsh-native. Releases are validated by Windows CI and published from version tags after the initial package bootstrap.

Tool behavior

With the default configuration:

• bash is inactive.
• pwsh is active.
• ls, find, and grep remain active.
• Existing tools from other extensions remain active.
• ! and !! execute through the selected PowerShell 7 runtime.

Example model commands:

Get-ChildItem
$env:NODE_ENV = 'test'; npm test
rg --glob '*.ts' 'createFileRoute' src
fd --extension ts . src

PowerShell syntax is not translated. A Bash-only command fails visibly so the model can correct it.

Configuration

The global configuration file is:

~/.pi/agent/pwsh-native.json

Example:

{
  "executable": "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
  "loadProfile": false,
  "executionPolicy": null,
  "replaceUserBash": true,
  "preserveDiscoveryTools": true,
  "strictMode": false,
  "pythonUtf8": true,
  "pythonUnbuffered": true,
  "elevationGuidance": false
}

All fields are optional. Unknown fields and malformed values are rejected rather than ignored.

Field	Default	Meaning
executable	"auto"	"auto" or an absolute path to PowerShell 7 pwsh.exe
loadProfile	false	Load the user's PowerShell profile instead of passing -NoProfile
executionPolicy	null	Optional explicit process execution policy; no override is passed by default
replaceUserBash	true	Route Pi's ! and !! commands through PowerShell
preserveDiscoveryTools	true	Keep Pi's ls, find, and grep tools active
strictMode	false	Set $ErrorActionPreference = 'Stop' for each command
pythonUtf8	true	Default PYTHONIOENCODING=utf-8 and PYTHONUTF8=1 when unset
pythonUnbuffered	true	Default PYTHONUNBUFFERED=1 when unset
elevationGuidance	false	Allow elevation-related prompt guidance; never auto-elevates

Supported explicit execution policies are AllSigned, Bypass, Default, RemoteSigned, Restricted, Undefined, and Unrestricted. Bypass is accepted only as an explicit user choice.

Environment overrides

Environment variables override file values:

• PI_PWSH_NATIVE_CONFIG — alternate configuration file path
• PI_PWSH_NATIVE_EXECUTABLE
• PI_PWSH_NATIVE_LOAD_PROFILE
• PI_PWSH_NATIVE_EXECUTION_POLICY
• PI_PWSH_NATIVE_REPLACE_USER_BASH
• PI_PWSH_NATIVE_PRESERVE_DISCOVERY_TOOLS
• PI_PWSH_NATIVE_STRICT
• PI_PWSH_NATIVE_PYTHON_UTF8
• PI_PWSH_NATIVE_PYTHON_UNBUFFERED
• PI_PWSH_NATIVE_ELEVATION_GUIDANCE

Boolean environment values accept true/false, 1/0, yes/no, or on/off.

Runtime resolution

When executable is "auto", resolution checks:

1. pwsh.exe found by where.exe.
2. C:\Program Files\PowerShell\7\pwsh.exe.

Each candidate is started and its version is verified. The selected absolute path is retained for all model and user commands.

If an explicit executable is invalid, the extension reports that exact failure and does not try another shell. If setup fails, the model's Bash tool is disabled and manual shell commands return an actionable error.

Environment and exit codes

Model tool calls retain Pi's session environment, including:

• PI_SESSION_ID
• PI_SESSION_FILE
• PI_PROVIDER
• PI_MODEL
• PI_REASONING_LEVEL

Manual !/!! commands follow Pi's documented user-command environment behavior.

The command epilogue preserves $LASTEXITCODE when a native program ran. Commands that only use PowerShell map $? to exit code 0 or 1.

Timeouts and cancellation

There is no default timeout. The model can supply a timeout in seconds for a pwsh call. Timeout and Pi cancellation both invoke taskkill.exe /T /F for the spawned process, preventing common child-process leaks from tools such as npm and development servers.

Persistent background jobs and interactive PTYs are intentionally outside the core package. Use an external terminal for long-running interactive processes until separately reviewed companion functionality is available.

Development

npm install --ignore-scripts
npm run typecheck
npm test
npm run test:windows
npm run smoke
npm run check

Test coverage includes configuration, runtime selection, tool activation, Unicode, multiline/long source transport, native exit codes, .cmd execution, timeout, cancellation, inherited stdio handles, and process-tree cleanup.

Security

Pi extensions execute with the user's full permissions. Review source before installation.

This package:

• does not make network requests;
• does not collect telemetry;
• does not auto-elevate;
• does not override execution policy by default;
• does not silently retry through cmd.exe, Bash, or PowerShell 5.1;
• does not have runtime dependencies or install scripts;
• does not accumulate unbounded shell output outside Pi's standard bounded output pipeline.

Limitations

• Windows-only in the initial release.
• Each command starts a fresh PowerShell process for isolation and predictable state.
• PowerShell profiles are disabled by default.
• Background-job emulation and PTY helpers from the upstream project are not included in the lean core.
• Competing shell-adapter extensions should not be enabled simultaneously.

Attribution

This project derives from @4fu/pi-pwsh, licensed under MIT. See THIRD_PARTY_NOTICES.md and LICENSE.