pi-pwsh-notify

PowerShell 7 shell for pi on Windows, with Claude Code-style background jobs that auto-notify the agent on completion — no polling.

pi install npm:pi-pwsh-notify

Why

Two problems with running pi on Windows:

1. The built-in bash tool runs through Git Bash (MSYS), which mangles Windows paths, garbles non-ASCII output, and hangs the whole session on background processes (npm run dev &).
2. Even with a PowerShell extension, existing packages make the agent poll for background job status. There is no way for a finished job to wake the agent up.

This extension fixes both. The agent starts a build or dev server in the background, keeps chatting with you, and when the process exits, a notification with the exit code and output tail is automatically injected into the conversation — the agent wakes up and reacts, exactly like background tasks in Claude Code. Implemented with pi.sendMessage(..., { deliverAs: "followUp", triggerTurn: true }) on process exit: it never interrupts a streaming response, and triggers a new turn when the agent is idle. Because it is a custom message rather than a fake user message, the TUI shows a compact one-line status row instead of a wall of text in a User box — while the LLM still receives the full tagged notification.

Tools

| Tool | Purpose | | --- | --- | | pwsh | Foreground command execution (replaces built-in bash) | | pwsh_bg | Start a background job; auto-notifies on completion | | pwsh_bg_output | Peek at a running job's captured output | | pwsh_bg_list | List jobs and their status | | pwsh_bg_kill | Kill a job and its child processes (taskkill /T /F) |

Foreground pwsh

• Fresh pwsh -NoProfile -NonInteractive process per call, started in the project directory
• UTF-8 forced on both PowerShell and Python child processes — non-ASCII output renders correctly
• Default 120s timeout (overridable per call); the whole process tree is killed on timeout or abort
• Native exit codes survive the pwsh -Command flattening (exit $LASTEXITCODE re-raise)
• Live output streaming while the command runs

Background pwsh_bg

• Returns immediately with a job id; output captured in memory (last 400 KB)
• On exit, a <background-job-finished> notification (status, runtime, last 60 output lines) is injected into the session
• Rendered in the TUI as a single tool-result-like row — ● bg job bg-1 (pytest) · exited 0 · 7s plus the last few output lines; expand the message to see the full tail
• Optional timeout_sec to kill runaway jobs; jobs killed via pwsh_bg_kill do not notify
• Surviving jobs are reaped when pi exits — no invisible orphan dev servers

Built-in tool handling

• Built-in bash is removed from the active tool list (pwsh replaces it).
• Built-in grep/find are removed only when pi-fff's ffgrep/fffind are present to take over searching. Without pi-fff, nothing else is touched.
• Removal re-runs on every session/agent start, so it also covers renderer extensions (e.g. pi-claude-style-tools) that re-register the default-hidden built-ins as a side effect.

Comparison

| | pi-pwsh-notify | @4fu/pi-pwsh | pi-powershell | @marcfargas/pi-powershell | | --- | --- | --- | --- | --- | | Foreground PowerShell | ✅ | ✅ | translation layer over bash | ✅ (adds tool) | | Background jobs | ✅ | via Start-Job | user commands only | ✅ | | Agent auto-notified on completion | ✅ | ❌ (agent must poll) | ❌ | ❌ (agent must poll) |

Requirements

• Windows. PowerShell 7 (pwsh) recommended — install with winget install Microsoft.PowerShell. Falls back to Windows PowerShell 5.1 if pwsh is not found.

Notes

• Each pwsh call is a fresh process: cd, variables, and functions do not persist between calls (by design — keeps /fork and session replay sane).
• Provided as-is; issues and PRs welcome but response times are not guaranteed.

License

MIT