Skip to content

README.md

Latest commit

 

History

History
188 lines (124 loc) · 4.57 KB

README.md

File metadata and controls

188 lines (124 loc) · 4.57 KB

banner

pi-processes

Manage background processes from Pi without blocking the conversation.

This extension lets Pi keep long-running commands alive while the conversation continues. It is useful for dev servers, test watchers, local APIs, builds, and log tails.

Let Pi keep working while processes run

When a task needs a long-running command, Pi can start it in the background by itself and keep helping with the rest of the work.

That means Pi can, for example:

  • start a dev server and keep coding
  • keep a test watcher running while it fixes failures
  • run a local API while it inspects logs
  • watch build output without blocking the conversation

You can then inspect, pin, or stop those processes from the UI.

Installation

From npm:

pi install npm:@aliou/pi-processes

From git:

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

Open the process panel

Use /ps to open the main process panel.

From there you can:

  • see running and finished processes
  • inspect recent output
  • pin a process to the dock
  • kill a running process
  • clear finished entries

Keys:

  • j/k or arrow keys: move selection
  • J/K: scroll preview
  • enter: pin selected process to the dock
  • x: kill selected process
  • c: clear finished processes
  • q or esc: close

Inspect logs

Use /ps:logs [id|name] to open the log overlay for one process.

This is useful when Pi started a server, watcher, or local API and you want to follow what it is doing in more detail.

Keys:

  • tab / shift+tab: switch process tabs
  • g/G: jump to top or bottom
  • j/k or arrow keys: scroll
  • s: switch between combined, stdout, and stderr
  • f: toggle follow mode
  • /: search
  • n/N: move between search matches
  • q or esc: close

Pin one process

Use /ps:pin [id|name] to keep the dock focused on one process.

This is useful when one process matters more than the others, such as a dev server or a test watcher.

Without arguments, Pi shows a picker.

Control the dock

Use /ps:dock [show|hide|toggle] to control dock visibility.

The dock gives you a compact live view without leaving the conversation.

Adjust settings

Use /ps:settings to configure the extension.

Available settings include:

  • process list size
  • output limits
  • shell path override
  • dock defaults
  • follow mode behavior
  • optional background command interception

Platform support

  • macOS: supported
  • Linux: supported
  • Windows: not supported

Runtime log watch alerts

Use process tool start with logWatches to trigger immediate alerts while the process is still running.

  • default behavior: each watch fires once (repeat: false)
  • set repeat: true to trigger on every match
  • scope by stream (stdout, stderr, both) to reduce noise

Example: server ready marker (one-time default)

{
  "action": "start",
  "name": "dev-server",
  "command": "pnpm dev",
  "logWatches": [
    { "pattern": "ready on http://localhost:3000" }
  ]
}

Example: error marker from stderr

{
  "action": "start",
  "name": "builder",
  "command": "pnpm build --watch",
  "logWatches": [
    { "pattern": "TypeError|ReferenceError", "stream": "stderr" }
  ]
}

Example: repeatable watch on stdout only

{
  "action": "start",
  "name": "worker",
  "command": "pnpm worker",
  "logWatches": [
    { "pattern": "job completed", "stream": "stdout", "repeat": true }
  ]
}

Invalid regex patterns fail fast at process start with a clear error.

Troubleshooting

Pi started something and I want to see more output

Open /ps for a quick overview, or use /ps:logs for full logs.

I want one process to stay visible

Use /ps:pin to focus the dock on that process.

I want Pi to avoid shell background tricks

Enable background command interception in /ps:settings. When enabled, Pi avoids normal shell background patterns and uses the process workflow instead.

Contributing

For development, testing, docs generation, and extension internals, see CONTRIBUTING.md.

License

MIT