pi-process-native

Deterministic background process supervision for the Pi coding agent on Windows.

pi-process-native starts, inspects, waits for, and stops non-interactive background processes while Pi continues working. It is designed for development servers, watchers, continuous tests, emulators, and other long-running commands.

Design

• One compact process model tool with start, list, status, logs, wait, and stop actions.
• Supports verified PowerShell 7 command execution and direct executable-plus-arguments execution.
• Keeps logs in bounded in-memory buffers and tail-truncates model results to Pi's limits.
• Detects readiness from literal output, including text split across output chunks.
• Owns processes for the current Pi session and stops them during session shutdown by default.
• Uses Windows process-tree termination with graceful and forced phases.
• Preserves Pi session environment metadata for model-started commands.
• Has no runtime dependencies, telemetry, elevation, or network calls.

Requirements

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

Direct executable mode does not require PowerShell.

Installation

Install the latest npm release:

pi install npm:pi-process-native

From GitHub:

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

From source:

npm install --ignore-scripts
pi -e .\src\index.ts

Examples

Start a development server and wait until it is ready:

{
  "action": "start",
  "name": "dev-server",
  "command": "npm run dev",
  "cwd": "C:\\project",
  "readyText": "Local:",
  "readyTimeout": 30
}

Read recent logs:

{
  "action": "logs",
  "id": "dev-server",
  "lines": 100
}

Wait for tests:

{
  "action": "wait",
  "id": "tests",
  "readyTimeout": 120
}

Stop a process:

{
  "action": "stop",
  "id": "dev-server"
}

Direct executable mode avoids shell interpretation:

{
  "action": "start",
  "name": "node-server",
  "executable": "C:\\Program Files\\nodejs\\node.exe",
  "args": ["server.js", "--port", "3000"]
}

Provide exactly one of command or executable when starting a process.

User command

/processes
/processes logs dev-server
/processes stop dev-server
/processes stop-all

Configuration

Global configuration:

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

Example:

{
  "powerShellExecutable": "auto",
  "loadPowerShellProfile": false,
  "maxProcesses": 8,
  "maxBufferBytesPerProcess": 1048576,
  "defaultReadyTimeoutSeconds": 30,
  "defaultStopTimeoutSeconds": 5
}

Unknown fields and malformed values are rejected.

Environment overrides:

• PI_PROCESS_NATIVE_CONFIG
• PI_PROCESS_NATIVE_PWSH_EXECUTABLE
• PI_PROCESS_NATIVE_LOAD_PROFILE
• PI_PROCESS_NATIVE_MAX_PROCESSES
• PI_PROCESS_NATIVE_MAX_BUFFER_BYTES

Lifecycle

Processes continue across model turns but are owned by the active Pi session. They are always stopped on quit, reload, new session, resume, or fork. Cancelling a readiness wait stops the process being started. Cancelling a normal wait does not stop an already-running process.

Completed process records and their bounded logs remain available during the session. The oldest completed records are pruned after 32 entries.

Security

Processes run with the user's permissions. This package is a process supervisor, not a sandbox.

• Shell commands can execute arbitrary code.
• Environment variables and process logs may contain secrets.
• No process is elevated automatically.
• Output memory and active process counts are bounded.
• Project commands should only be run in trusted repositories.

Limitations

• Windows-only in the initial release.
• Non-interactive processes only; there is no PTY or stdin interaction.
• Processes do not survive Pi shutdown or extension reload by default.
• Readiness detection is literal text matching; port probes and regular expressions are not included yet.
• Windows cleanup uses taskkill /T. A child deliberately detached before its parent exits may escape later tree discovery; this package does not claim Job Object containment.
• Log buffers are in memory and older output is discarded when their configured limit is reached.

Development

npm install --ignore-scripts
npm run check

Tests cover configuration, bounded UTF-8 logs, readiness across output chunks, native exit codes, timeouts, active-process limits, PowerShell Unicode transport, and process-tree stopping.

License

MIT