# 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:

```bash
pi install npm:@mjakl/pi-processes
```

For development builds, install from git:

```bash
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:

```text
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`.

```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:

```bash
pnpm typecheck
pnpm lint
pnpm test
```

After dependency changes, also verify the lockfile with:

```bash
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.