doom-runner

name	doom-runner
description	Manage long-running commands started by bash: dev servers, watchers, builds, tails, and anything that prompts for input. Trigger when a command needs to outlive the current turn, when bash output was truncated, or when a background process needs to be inspected, followed, given input, or stopped.

doom-runner

bash supervises what it starts. A command that outlives the background threshold keeps running instead of blocking the turn. Use the doom-runner CLI to manage it without adding another model tool.

Backgrounding

• A command still running after 60 seconds (DOOM_RUNNER_BG_THRESHOLD_MS) is moved to the background automatically. You get its unique ID and streaming log path.
• Pass background: true for commands you already know will not finish: dev servers, watchers, tail -f. Waiting out the threshold first wastes a turn.
• Pass interactive: true when the command will prompt for confirmation or input. It runs under a terminal and backgrounds immediately. Answer it with doom-runner input <id> --text <text> --enter, or use Runner Space.
• Pass timeout (seconds) when you want a command killed rather than supervised. A timeout above the threshold has no effect: the command is promoted first.
• Pass name to choose the runner name. A name already in use gets a numbered suffix.

CLI

Run the CLI directly, without starting it through another supervised runner. It inherits PI_SESSION_ID from the active Pi session and only accesses that session's runners. A manual shell without PI_SESSION_ID fails closed.

Use the unique runner ID returned by bash:

Command	Purpose
doom-runner list [--all]	List active runners, or include completed ones
doom-runner status <id>	Show command, state, backend, and log path
doom-runner logs <id> [--lines N] [--follow]	Read or stream the saved log
doom-runner stop <id> [--reason <text>]	Stop one runner and keep its log
doom-runner stop-all [--reason <text>]	Stop active runners owned by this Pi session
doom-runner input <id> [--text <text>] [--enter]	Send input to an interactive RMUX runner

Rules

• Read the log, do not re-run the command. When output is truncated, the full text is already on disk. Use doom-runner logs <id> or standard file search tools against the reported path.
• Read the truncation notice before reading the file. It states the real file size and line count, so you do not read past the end.
• CLI access is session-scoped. list, direct ID commands, and stop-all only access runners owned by the inherited Pi session.
• input needs interactive: true. A normal runner does not expose stdin.
• Stop what you no longer need. Everything still running is stopped when the session ends, but a forgotten dev server holds a port until then.
• Do not poll. Check a runner when you have a reason to, not on a loop.

Where things live

Run metadata and logs sit under $PI_CODING_AGENT_DIR/doom-runner/<session-id>/{runs,logs}. Without an override, $PI_CODING_AGENT_DIR defaults to ~/.pi/agent. Completed metadata and complete raw logs remain readable for seven days.

RMUX is bundled for supported macOS and Linux platforms. Non-interactive runs fall back to a supervised subprocess when RMUX is unavailable; interactive runs require RMUX. Eligible simple commands use a command-specific RTK stdin filter after completion. Compound shell commands and unsupported formats keep bounded raw output.

SPC r l opens Runner Space. Escape returns from logs or an attached terminal.