Processes Extension

Note This is a stripped down fork of https://github.com/aliou/pi-processes. Most people should likely use the original project instead.

Manage background processes from Pi without blocking the conversation.

Installation

Install from npm:

pi install npm:@mjakl/pi-processes

For development builds, install from git:

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

What this fork keeps

• the process tool for starting, listing, inspecting, killing, and clearing managed processes
• a single /ps overlay for monitoring processes
• a tiny always-visible process status line while managed processes exist, showing active/finished counts
• process completion notifications in the conversation
• file-backed logs so process output is preserved outside agent context

What this fork removes

• all /ps:* subcommands
• the log dock
• the settings UI
• extra widget state and dock controls

Usage

Agent tool (LLM-facing)

The process tool is for the agent. Users should ask the agent to start or inspect long-running commands, then monitor them with /ps.

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

Matching processes

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

• the exact process ID (proc_1)
• the exact friendly process name (backend-dev)

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

Notifications for start

Do not poll after starting a process.

This tool is event-driven: the agent is notified automatically when a process exits, fails, or is externally killed. By default, process start ends the current agent turn so the agent actually waits for that notification instead of immediately polling. If the next step is waiting, call process start by itself rather than batching it with unrelated tools.

The intended pattern is:

1. process start
2. let the turn stop and wait for the automatic notification if the process ends
3. resume from that notification

Use continueAfterStart=true only when the agent has immediate, specific, non-polling work to do after starting the process.

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

Logs and output

• process output returns a one-off tailed stdout/stderr snapshot for agent consumption.
• process logs returns file paths for stdout, stderr, and a combined view for the /ps overlay.
• Use output/logs only when the user asks, when you need a diagnostic snapshot, or when investigating a problem - not as a polling loop.

Killing processes

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

/ps overlay

/ps opens the process overlay.

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.

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

• output.defaultTailLines - default number of lines returned by process output
• output.maxOutputLines - hard cap for process output
• execution.shellPath - absolute shell path override used for process startup
• interception.blockBackgroundCommands - block shell backgrounding (&, nohup, disown, setsid) 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

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

Notes

• Log files live in a temporary directory managed by the extension.
• Background processes are cleaned up when the session shuts down.