@marcfargas/pi-powershell

PowerShell tools for pi agents on Windows — background processes, system operations, and remote management.

Problem

Windows Git Bash hangs when running background processes (npm run dev &), freezing the entire agent session. There's no reliable way to start a dev server, run tests, or manage processes in the background from a pi agent on Windows.

Solution

A pi package bundling an extension (8 tools) and a skill (teaches agents when and how to use them).

| Tool | Purpose | |------|---------| | powershell | Execute PowerShell commands (stateless, like bash) | | pwsh-start-job | Start background processes as real OS processes | | pwsh-get-job | Check job status (by name or list all) | | pwsh-stop-job | Stop a running job | | pwsh-remove-job | Remove job and clean up log files | | pwsh-get-job-output | Read captured stdout/stderr from a job | | pwsh-create-session | Create PSSession to a remote machine | | pwsh-close-session | Close a remote PSSession |

Installation

pi install npm:@marcfargas/pi-powershell

The package registers both the extension (tools) and skill (agent documentation).

Background Processes

The main reason this extension exists. Jobs are real OS processes (via Start-Process -WindowStyle Hidden), not PowerShell jobs — they persist across tool calls.

await tools['pwsh-start-job']({
  name: 'dev-server',
  command: 'npm run dev',
  workingDirectory: 'C:/dev/myapp'
});

await tools['pwsh-get-job']({ name: 'dev-server' });
await tools['pwsh-get-job-output']({ name: 'dev-server' });

await tools['pwsh-stop-job']({ name: 'dev-server' });
await tools['pwsh-remove-job']({ name: 'dev-server' });

Output Capture

By default, all PowerShell streams are merged into one temp log file (*>). Control with stdout and stderr params:

// Separate files
await tools['pwsh-start-job']({ name: 's', command: 'npm run dev', stdout: 'C:/logs/out.log', stderr: 'C:/logs/err.log' });

// Discard stderr
await tools['pwsh-start-job']({ name: 's', command: 'npm run dev', stderr: 'null' });

// Fire and forget
await tools['pwsh-start-job']({ name: 's', command: 'npm run dev', stdout: 'null', stderr: 'null' });

PowerShell Commands

Each powershell call spawns a fresh pwsh process that dies after execution — stateless, like bash.

• UTF-8 output — non-ASCII characters render correctly on any locale
• Batch file auto-retry — .cmd/.bat failures automatically retry with cmd /c
• Output streaming — partial output streams to the TUI as it arrives

PSSessions (Remote Management)

PSSessions are persistent connections to remote Windows machines. They maintain state (variables, imported modules) across commands on the remote machine.

await tools['pwsh-create-session']({
  name: 'prod', computerName: 'server.company.com',
  credential: 'domain\\admin', authentication: 'Kerberos'
});
await tools.powershell({ command: 'Get-Service IIS', session: 'prod' });
await tools['pwsh-close-session']({ name: 'prod' });

Never use PSSessions as a local persistent shell — breaks pi's /tree and /fork behavior.

Design Decisions

• OS processes, not PS jobs: Start-Job dies when the pwsh process exits. Start-Process -WindowStyle Hidden creates real detached processes tracked by PID in extension memory.
• *> redirection: Merges all PowerShell streams into one file by default. See about_Redirection.
• Extension + Skill: Tools provide the capability; the bundled skill teaches agents when and how to use them (including advanced topics like PSSessions via progressive disclosure).
• UTF-8 forced: Every command prefixed with [Console]::OutputEncoding = [System.Text.Encoding]::UTF8.
• Cross-instance safe: Each pi instance gets a unique suffix on temp log files.

Development

Part of pi-mf-extensions.

npm test        # 50 tests
npm run typecheck

License

MIT