# pi-procs

Background process manager for Pi. Start dev servers, watch builds, tail logs — without blocking the agent.

## Install

```bash
pi install npm:@artale/pi-procs
```

## Commands

```
/procs list                        — show all running processes
/procs start <cmd> [--name <n>]    — start a background process
/procs logs <name> [--lines N]     — tail output from a process
/procs kill <name>                 — stop a process
/procs killall                     — stop all processes
/procs mprocs                     — hand off to mprocs TUI (if installed)
/procs export                     — export mprocs.yaml for current processes
```

## Tools

- `procs_start` — start a background process
- `procs_list` — list all processes with PID, uptime, command
- `procs_logs` — get recent output from a process
- `procs_kill` — kill a process by name
- `procs_export` — export as mprocs.yaml
- `procs_mprocs` — hand off to mprocs TUI

## Examples

```
/procs start npm run dev --name frontend
/procs start python manage.py runserver --name backend
/procs list
/procs logs frontend --lines 50
/procs kill backend
/procs killall
```

## mprocs integration

If [mprocs](https://github.com/pvolok/mprocs) is installed, pi-procs can hand off running processes to a full TUI:

```
/procs start npm run dev --name frontend
/procs start npm test -- --watch --name tests
/procs mprocs    ← opens mprocs with both processes in split panes
```

This gives you the best of both worlds:
- **Agent-side**: the LLM starts/stops/tails processes via tools
- **Human-side**: you get a visual TUI with split panes when you want to watch

You can also export without launching:
```
/procs export    ← writes mprocs.yaml to cwd
```

Install mprocs: `npm i -g mprocs` or `brew install mprocs` or `cargo install mprocs`

## How it works

- Spawns child processes with detached stdio
- Captures stdout/stderr in a rolling buffer (500 lines)
- Auto-names processes from the command if no name given
- Auto-detects mprocs installation
- Cleans up all processes on Pi exit
- Works on Windows, macOS, and Linux
- Zero dependencies beyond Node.js built-ins

## License

MIT