pi-windows-shell — Pi Extension

Windows PowerShell and process-management extension for Pi Agent. Gives Pi explicit tools for PowerShell execution and long-running process management on Windows, while keeping the built-in bash tool fully functional for Git and Unix-like workflows.

Features

• Foreground PowerShell — Windows paths, $env variables, .exe/.cmd/.bat/.ps1, system inspection
• Background process lifecycle — start, monitor, read output, stop, and list detached processes
• Port management — find and kill processes by TCP port
• Command discovery — locate Windows commands with Get-Command
• Persistent process registry — survives Pi restarts (%LOCALAPPDATA%\pi-windows-shell\)
• Automatic shell policy — injected into every system prompt, guides Pi on Bash vs PowerShell usage
• Status bar — shows discovered PowerShell version

Install

pi install npm:@gogomi/pi-windows-shell

Reload Pi after install: /reload

Usage

Slash Commands (you)

/win-shell-info    → discovered PowerShell, registry path, logs path
/win-processes     → tracked background processes
/win-cleanup       → remove stale registry entries

Agent Tools (called automatically by the agent)

Tool	Description
powershell	Run a foreground PowerShell command (120s timeout, 50KB/2000 lines)
win_start_process	Start a background process, output logged to file
win_process_status	Check if a process is alive by ID or PID
win_read_output	Read tail of a background process log
win_stop_process	Stop a process tree by ID or PID
win_kill_port	Find and kill processes listening on a TCP port
win_which	Discover command paths with Get-Command
win_list_processes	List tracked background processes
win_cleanup_processes	Remove stale registry entries and old logs

Shell policy

The extension injects a minimal Windows-awareness policy into the system prompt:

• Path handling → don't pass C:\ paths to Bash, don't assume WSL
• Long-running → use win_start_process instead of npm run dev &

Each tool also has its own promptGuidelines telling the agent when to use it. The extension does NOT dictate how to use Bash, git, grep, find, or other Pi-native tools.

Structure

index.ts                  ← Pi extension (9 tools + 3 commands + policy injection)
shell.ts                  ← PowerShell discovery and foreground/background execution
process-registry.ts       ← Persistent JSON registry for managed processes
output.ts                 ← Output truncation and tail reading
paths.ts                  ← Registry and log path helpers
types.ts                  ← Shared TypeScript interfaces

Requirements

• Node.js ≥ 18
• Windows with PowerShell 5+ (PowerShell 7 recommended)