Pi Processes

Manage long-running commands from Pi without blocking the conversation.

User Guide

Why Pi Processes

Coding agents often need to start dev servers, watch-mode tests, log tails, port forwards, and other commands that should keep running while the conversation continues. pi-processes gives Pi a safe, visible way to manage those commands.

Features

• Agent-facing process tool — the agent can start, inspect, kill, and clear managed processes.
• Event-driven completion — the agent is notified when a managed process exits, fails, or is externally killed.
• /ps overlay — users can monitor processes and logs without asking the agent to poll.
• Status line — a compact process status appears while managed processes exist.
• File-backed logs — recent process output is retained outside the agent context window.
• Background-command interception — optional guardrails steer long-running shell commands toward the process tool.

Install

Install from npm:

pi install npm:@mjakl/pi-processes

Install from git:

pi install git:github.com/mjakl/pi-processes

Or install from a local checkout:

pi install /path/to/pi-processes

Using Pi Processes

The process tool is for the agent, not for direct user input. Ask the agent to start or inspect long-running work, then use /ps to watch it.

Example user prompts:

Start the dev server with pnpm dev and call it backend-dev.
Run the test watcher as tests.
Show me the latest output from backend-dev.
Stop the backend-dev process.

The agent should start managed processes through the process tool instead of running shell backgrounding such as command &, nohup, disown, or setsid.

/ps overlay

Run:

/ps

Inside the overlay:

• up / down — move the highlighted process.
• left / right — scroll older/newer log output for the highlighted process.
• g / G — jump to the top or back to the live tail.
• x — terminate the highlighted process; press x again when it shows needs kill to force-kill it.
• c — clear finished processes.
• q or Esc — close the overlay.

The right side always shows logs for the currently highlighted process.

Configuration

Global config lives in:

~/.pi/agent/extensions/process.json

Example:

{
  "output": {
    "defaultTailLines": 100,
    "maxOutputLines": 200
  },
  "execution": {
    "shellPath": "/absolute/path/to/bash"
  },
  "interception": {
    "blockBackgroundCommands": true
  }
}

Options:

• output.defaultTailLines — default number of lines returned by process output (positive integer, capped by maxOutputLines).
• output.maxOutputLines — hard cap for process output (positive integer, at most 2,000).
• execution.shellPath — absolute shell path override used for process startup.
• interception.blockBackgroundCommands — block shell backgrounding and obvious long-running foreground commands such as pnpm dev, docker compose up, tail -f, or kubectl port-forward, and guide the agent to use the process tool instead.

---

Technical Reference

These sections document the agent-facing tool contract and runtime behavior.

Tool API

The tool is named process.

Actions:

• start — start a managed process.
• list — list managed processes.
• output — return a one-off tailed stdout/stderr snapshot.
• logs — return file paths for stdout, stderr, and combined logs.
• kill — terminate or force-kill a process.
• clear — remove finished processes from the manager.

Tool-call examples:

process start "pnpm dev" name="backend-dev"
process start "pnpm test --watch" name="tests"
process start "pnpm dev" name="backend-dev" continueAfterStart=true
process list
process output id="backend-dev"
process logs id="proc_1"
process kill id="backend-dev"
process kill id="proc_1" force=true
process clear

Field rules:

• start requires command and name.
• A started command must remain in the foreground. Do not include &, setsid, coproc, detached container flags, or daemon-mode options; the manager supervises the foreground process group.
• output, logs, and kill require id.
• kill accepts force=true to send SIGKILL instead of SIGTERM.
• start accepts continueAfterStart=true only when the agent has immediate, specific, non-polling work to do after startup.

Matching processes

For output, logs, and kill, id must be either:

• the exact process ID, such as proc_1
• the exact friendly process name, such as backend-dev

If multiple processes share the same name, use the process ID.

Event-driven start behavior

Do not poll after starting a process.

By default, process start ends the current agent turn. The intended pattern is:

1. Call process start.
2. Let the turn stop.
3. Resume when Pi sends the automatic notification for process exit, failure, or external kill.

Use continueAfterStart=true only when there is immediate, useful work to do that is not polling.

Repeated process list, process output, or process logs calls just to check whether a process is still running are an anti-pattern.

Logs and output

• process output is for one-off diagnostic snapshots in the conversation.
• process logs returns log file paths for deeper inspection and for the /ps overlay.
• Each stdout, stderr, and combined log file keeps the latest output, up to 5 MiB. On overflow it trims to roughly 4 MiB so runaway output cannot grow without bound.
• A session retains at most 16 live processes and 32 total process records. Stop live work or run process clear before starting more.
• Use output and logs when the user asks, when debugging, or when investigating a specific problem.

Killing processes

• process kill id="..." sends SIGTERM.
• process kill id="..." force=true sends SIGKILL.
• Tool-triggered kills never notify the agent.

Runtime notes

• Log files live in a temporary directory managed by the extension.
• Background processes are cleaned up when the session shuts down.
• The /ps overlay reads from file-backed logs, so process output remains available without stuffing the full log into the agent context.

Development

There are no Git hooks installed by this repository. Before committing or opening a PR, consider running:

pnpm typecheck
pnpm lint
pnpm test

After dependency changes, also verify the lockfile with:

pnpm install --frozen-lockfile --ignore-scripts

License

MIT