pi-pwsh-notify

Your agent starts the dev server and keeps working.The moment it's up, the agent knows.

Background jobs with automatic notifications for pi on Windows. No polling.

English · 简体中文

pi install npm:pi-pwsh-notify

No configuration. Your next session gets a PowerShell 7 shell with managed background jobs.

How it feels

you    start the dev server, run the tests, and fix whatever fails

agent  pwsh  npm run dev  →  bg-1 (vite) started
       pwsh  npm test     →  bg-2 (tests) started
       Both are running. Back to the login form.

● bg job bg-1 (vite) · ready · 2s
● bg job bg-2 (tests) · exited 1 · 41s

agent  The tests failed, so I'll read the output.
       pwsh_job  output bg-2
       auth.test.ts expects a 401. Fixing the handler now.

Nobody had to ask "is it done yet?" The job told the agent.

Why

A dev server never exits, so an ordinary shell call never returns and the agent's turn stops there. Long test suites tie it up the same way. Checking in a loop just burns tokens.

Features

• 🔔 Notifies on its own. A finished job wakes an idle agent, or slips into its current run before the next model call.
• ⚡ Knows when a server is ready. notify_on: "Local:.*http" fires on the first match, for processes that never exit.
• ⏳ Waits when it has to. pwsh_job wait blocks on a regex, an exit, or a timeout instead of looping.
• 📍 cd that sticks. The working directory carries across calls.
• 📺 Live job panel. Browse jobs under the editor, open live output, and kill one with two keystrokes.
• 🧹 No orphans. Jobs and their process trees are cleaned up on exit, reload, session switch, and closing the terminal.
• 📜 Complete logs. Every background job keeps a full log, and huge output never floods the context.
• 🌏 UTF-8 throughout. 中文, 日本語, and emoji come through intact.
• 🔒 Output stays out until asked for. Notifications carry the status, so a process can't talk to your agent just by printing.
• 🪶 Zero dependencies. Nothing to install except the extension.

Usage

Just ask for what you want. The agent calls these tools on its own:

pwsh { command: "npm run dev", run_in_background: true, name: "vite", notify_on: "Local:.*http" }

pwsh_job { action: "wait", id: "bg-1", pattern: "ready|listening", timeout: 120 }

Job panel: at an empty prompt, press → or Tab to focus, ↑ ↓ to move, Enter for live output, x twice to kill, and Esc to go back.

How it compares

Use Pi's built-in tool for simple foreground commands. Use this when foreground work is still the default but you want managed background jobs alongside it. Use @4fu/pi-pwsh for long-lived or interactive workloads.

Don't install two PowerShell extensions at once: both register a tool named pwsh, with different lifecycle rules.

FAQ

Yes, as long as PowerShell 7 is available, and ! / !! commands use it too. If it isn't, the extension steps aside and Pi's built-in bash stays active.

The agent reads output with pwsh_job when the result matters. That saves tokens and keeps secrets and untrusted text out of the conversation until something actually needs them.

In a pi-pwsh-notify-* folder in your system temp directory. Old folders are removed on later startups.

Set PI_PWSH_NOTIFY_EXECUTABLE to the absolute path of pwsh.exe.

No, jobs belong to the session. If you need them to outlive it, use @4fu/pi-pwsh.

Requirements

Windows · Node.js 22.19+ · PowerShell 7+ · Pi 0.84+

Contributing

Issues and pull requests are welcome.

npm ci
npm run check

Acknowledgments

Thanks to radioflyer28, whose issues and pi-pwsh-notify-secure fork shaped this release.

License

MIT