diff --git a/README.md b/README.md index d5b65d7..a1b49cd 100644 --- a/README.md +++ b/README.md @@ -35,12 +35,20 @@ From git: pi install git:github.com/aliou/pi-processes ``` +## How Pi stays in the loop + +Pi does not wait around for a background process. After it starts one, it keeps helping with the rest of the work and gets brought back automatically when something happens: + +- a readiness marker appears in the logs (a server prints "ready") +- an error appears in the logs (a build prints a type error) +- the process exits, whether it succeeded, failed, or was killed + +That is how Pi can start a dev server and then keep coding, or run a test watcher and react when a test fails, without sleeping or polling. If a watch fires too often, Pi can quiet it without restarting the process. + ## Open the process panel Use `/ps` to open the main process panel. It shows running and finished processes, with the most recent output preview. The preview opens on the newest page so you can see live activity without scrolling. -[![Browse and manage processes from the panel](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/process-panel.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/process-panel.mp4) - From there you can: - see running and finished processes @@ -49,58 +57,30 @@ From there you can: - 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. The viewer is cached per process, so switching tabs preserves scroll position and follow mode. -[![Open the log overlay and inspect output](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/inspect-logs.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/inspect-logs.mp4) - 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: +## Control the dock + +Use `/ps:dock [expand|collapse|close]` to control dock visibility. -- `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 +The dock gives you a compact live view without leaving the conversation. ## Pin one process Use `/ps:pin [id|name]` to keep the dock focused on one process. -[![Pin the dock to one process](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/pin-process.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/pin-process.mp4) - 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 [expand|collapse|close]` to control dock visibility. - -[![Show, hide, and use the dock](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/dock-control.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/dock-control.mp4) - -The dock gives you a compact live view without leaving the conversation. - ## Stop and clear processes Use `/ps:kill [id|name]` to stop a running process, and `/ps:clear` to remove finished entries from the panel and free their log storage. -[![Stop and clear processes](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/stop-and-clear.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/stop-and-clear.mp4) - `/ps:kill` waits for the process to actually exit (or time out), so the result it reports reflects what happened. Without arguments, Pi shows a picker. `/ps:clear` never touches live processes. @@ -109,24 +89,18 @@ Use `/ps:kill [id|name]` to stop a running process, and `/ps:clear` to remove fi Enable the status widget in `/ps:settings` to show a compact line of running processes below the editor. Each process shows a status dot, its name, and its state, with `+N more` overflow when the line does not fit. -[![Status widget below the editor](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/status-widget.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/status-widget.mp4) - It is disabled by default. The widget reflows on resize and clears itself when the process list is empty. ## Send input to a process Use the `process` tool with `action: "write"` to send bytes to a running process's stdin. This is how you drive interactive servers, REPLs, and CLIs that expect input after they start. -[![Send input to a running process](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/send-input.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/send-input.mp4) - Pass `input` for the bytes to write, and set `end: true` to close stdin (for example to signal EOF to a waiting process). ## Adjust settings Use `/ps:settings` to configure the extension. -[![Adjust process extension settings](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/settings.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/settings.mp4) - Available settings include: - process list size @@ -143,79 +117,53 @@ Available settings include: - Linux: supported - Windows: not supported -## Runtime log watch alerts +## Troubleshooting + +### Pi started something and I want to see more output -Use the `process` tool `start` action with `notify.logMatches` to trigger immediate alerts while the process is still running. +Open `/ps` for a quick overview, or use `/ps:logs` for full logs. -- 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 +### I want one process to stay visible -Example: server ready marker (one-time default) +Use `/ps:pin` to focus the dock on that process. -```json -{ - "action": "start", - "name": "dev-server", - "command": "pnpm dev", - "cwd": "/path/to/project", - "notify": { - "logMatches": [ - { "pattern": "ready on http://localhost:3000" } - ] - } -} -``` +### I want Pi to avoid shell background tricks -Example: error marker from stderr - -```json -{ - "action": "start", - "name": "builder", - "command": "pnpm build --watch", - "notify": { - "logMatches": [ - { - "pattern": "TypeError|ReferenceError", - "mode": "regex", - "stream": "stderr" - } - ] - } -} -``` +Enable background command interception in `/ps:settings`. When enabled, Pi avoids normal shell background patterns and uses the process workflow instead. -Example: repeatable watch on stdout only - -```json -{ - "action": "start", - "name": "worker", - "command": "pnpm worker", - "notify": { - "logMatches": [ - { "pattern": "job completed", "stream": "stdout", "repeat": true } - ] - } -} -``` +## Feature demos -Empty patterns (literal or regex) are rejected at start and update time. Invalid regex patterns fail fast with a clear error. +**Browse and manage processes from the panel** -## Troubleshooting +[![Browse and manage processes from the panel](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/process-panel.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/process-panel.mp4) -### Pi started something and I want to see more output +**Open the log overlay and inspect output** -Open `/ps` for a quick overview, or use `/ps:logs` for full logs. +[![Open the log overlay and inspect output](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/inspect-logs.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/inspect-logs.mp4) -### I want one process to stay visible +**Show, hide, and use the dock** -Use `/ps:pin` to focus the dock on that process. +[![Show, hide, and use the dock](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/dock-control.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/dock-control.mp4) -### I want Pi to avoid shell background tricks +**Pin the dock to one process** -Enable background command interception in `/ps:settings`. When enabled, Pi avoids normal shell background patterns and uses the process workflow instead. +[![Pin the dock to one process](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/pin-process.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/pin-process.mp4) + +**Stop and clear processes** + +[![Stop and clear processes](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/stop-and-clear.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/stop-and-clear.mp4) + +**Status widget below the editor** + +[![Status widget below the editor](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/status-widget.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/status-widget.mp4) + +**Send input to a running process** + +[![Send input to a running process](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/send-input.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/send-input.mp4) + +**Adjust process extension settings** + +[![Adjust process extension settings](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/settings.gif)](https://assets.aliou.me/pi-extensions/demos/processes/v0.10.0/settings.mp4) ## Contributing