⚙️ pi-processes

Agent-facing process manager for Pi and pi-web automation workflows.

pi-processes lets the agent start, inspect, restart, and stop long-running commands through a managed process tool instead of fragile shell backgrounding.

Designed for use with jmfederico/pi-web.

Why

Agents often waste time or break sessions by running:

• npm run dev &
• nohup pnpm dev ...
• pkill -f vite
• repeated timeout 10 npm run dev

This package gives the agent a stable process lifecycle instead:

• process start
• process list
• process output
• process restart
• process kill

Table of Contents

• Features
• Install
• Usage
• Configuration
• Tool API
• Killing processes
• Limitations
• Development
• Acknowledgements
• Changelog
• License

Features

• Agent-facing process tool — start, list, kill, get output, get log paths, and clear managed processes.
• File-backed logs — process output is preserved in temp files outside the agent context window.
• Background-command interception — optional guardrails steer the agent away from shell backgrounding, nohup, and obvious long-running foreground commands, and toward the process tool.
• Session cleanup — managed processes are terminated when the session shuts down.
• Duplicate name protection — refuses to spawn if a live process with the same name already exists.
• Dedicated restart action — safely awaits kill before starting a new process.

Install

Install from npm:

pi install npm:@haemmid/pi-processes

Install from git:

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

Or install from a local checkout:

pi install /path/to/pi-processes

Usage

The process tool is for the agent, not for direct user input. Ask the agent to start or inspect long-running work.

Example user prompts:

Start the dev server with pnpm dev and call it backend-dev.
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.

Astro / Vite workflow

For Astro/Vite dev servers, ask the agent:

Use the process tool for the Astro dev server.
Ensure `npm run dev -- --host 0.0.0.0` is running as `my-site:astro`.
Use `process output` when you need logs.
Do not restart after ordinary .astro, .ts, or .css edits.
Restart only after package/config/env changes or if the server exits.

Typical tool flow:

process list
process ensure "npm run dev -- --host 0.0.0.0" name="my-site:astro"
process output name="my-site:astro"
process wait url="http://localhost:4321" name="my-site:astro"
process restart "npm run dev -- --host 0.0.0.0" name="my-site:astro"
process kill name="my-site:astro"

Demo

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.
• output.maxOutputLines — hard cap for process output.
• 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.

Tool API

The tool is named process.

Actions

Action	Description
start	Start a managed process (refuses if a live process with the same name exists).
ensure	Idempotent start: reuse existing process if name+command+cwd match, start new otherwise.
restart	Kill existing process and start a new one (safe: await kill → start).
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.
wait / wait_for	Poll until a URL responds or a log pattern appears in process output.

Tool-call examples

process start "pnpm dev" name="backend-dev"
process start "pnpm test --watch" name="tests"
process start "pnpm dev" name="backend-dev" cwd="/path/to/project"
process ensure "pnpm dev" name="backend-dev"
process ensure "pnpm dev" name="backend-dev" cwd="/path/to/project"
process restart "pnpm dev" name="backend-dev"
process restart "pnpm dev" name="backend-dev" force=true
process list
process output id="proc_1"
process output name="backend-dev"
process logs id="proc_1"
process logs name="backend-dev"
process kill id="backend-dev"
process kill name="backend-dev" force=true
process clear
process wait url="http://localhost:4321" name="my-site:astro"
process wait log="Local" name="my-site:astro" timeout_ms=15000

Field rules

• start/ensure/restart require command and name.
• output, logs, kill, and wait accept either id (exact process ID) or name (process name).
• kill accepts force=true to send SIGKILL instead of SIGTERM.
• wait requires exactly one of url or log; timeout_ms defaults to 10000, interval_ms to 500.
• start refuses if a live process with the same name is already running.
• ensure reuses existing process when name+command+cwd match; returns conflict error otherwise.
• restart safely kills the existing process (awaited) before starting a new one.
• restart accepts force=true to send SIGKILL instead of SIGTERM.
• restart waits for the old process to exit; if it does not exit within the timeout, the replacement is not started. Use force=true or inspect logs.
• start/ensure/restart accept cwd to override the working directory (defaults to session cwd).
• output, logs, and kill return an error if both id and name are provided.

Killing processes

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

Limitations

• Linux/macOS only. The extension disables itself on Windows.
• Session-scoped. Processes are cleaned up on session shutdown.
• Not a system service manager. Does not persist process registry across sessions.
• Manages only tool-started processes. Does not track externally started processes.
• No TUI widgets. Does not provide /ps overlays or status widgets.
• Node.js 18+ required. Native fetch is used by process wait URL checks.

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

Acknowledgements

This package started as a fork of mjakl/pi-processes, which was based on aliou/pi-processes. This fork focuses specifically on plain-text, pi-web-friendly, agent-facing process management without TUI widgets or overlays.

Changelog

See CHANGELOG.md.

License

MIT