background-bash
/background-bash
WHAT: Decide when to run a shell command off-turn with the `bg_bash` tool instead of blocking the turn on the built-in `bash` tool, and how to poll / steer / collect it across turns. WHEN: A command is long-running (dev server, build, watch, test suite, training run, log tail) or you want the turn free while it runs. DO-NOT: Background a quick command whose output you need immediately, spawn a job you never poll, or use it for pure computation - that is `compute`.
- Author
- weikinhuang ↗
- Repository
- dotfiles ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
WHAT: Decide when to run a shell command off-turn with the `bg_bash` tool instead of blocking the turn on the built-in `bash` tool, and how to poll / steer / collect it across turns. WHEN: A command is long-running (dev server, build, watch, test suite, training run, log tail) or you want the turn free while it runs. DO-NOT: Background a quick command whose output you need immediately, spawn a job you never poll, or use it for pure computation - that is `compute`.
Original author description
WHAT: Decide when to run a shell command off-turn with the `bg_bash` tool instead of blocking the turn on the built-in `bash` tool, and how to poll / steer / collect it across turns. WHEN: A command is long-running (dev server, build, watch, test suite, training run, log tail) or you want the turn free while it runs. DO-NOT: Background a quick command whose output you need immediately, spawn a job you never poll, or use it for pure computation - that is `compute`.
How it works
- When to use this skill
- Workflow
- Steering interactive jobs
- Do not orphan jobs
- Common pitfalls
- Related docs
SKILL.md preview
--- name: background-bash description: 'WHAT: Decide when to run a shell command off-turn with the `bg_bash` tool instead of blocking the turn on the built-in `bash` tool, and how to poll / steer / collect it across turns. WHEN: A command is long-running (dev server, build, watch, test suite, training run, log tail) or you want the turn free while it runs. DO-NOT: Background a quick command whose output you need immediately, spawn a job you never poll, or use it for pure computation - that is `compute`.' --- # Background bash The built-in `bash` tool blocks the assistant turn until the command exits. `bg_bash` spawns the command off-turn, returns a job id immediately, and exposes one multi-action tool (`start`, `list`, `status`, `logs`, `wait`, `signal`, `stdin`, `remove`) you drive across later turns to poll, steer, and collect output. Reach for it when a command outlives the moment you launch it - or when you would rather keep working than sit on a blocking call. ## When to use this skill Use `bg_bash` `start` when at least one of these is true: - **The command does not terminate on its own.** Dev servers, file watchers, `tail -f`, `npm run dev`, queue workers. These would hang a blocking `bash` call forever. - **The command is slow and you have other work.** A full build, a long test suite, a training run, a large download. Background it, make progress inline, then `wait` for it. - **You want to watch progress over several turns.** `logs` with a `sinceCursor` lets you resume the stream without re-reading from the top. - **The command may need steering.** A REPL or installer that reads stdin - pass `interactiveStdin: true` and feed it with the `stdin` action. Stay on the built-in `bash` tool when: - The command is quick (a `git status`, a one-shot test file, an `ls`) and you need its output to decide the next step. Backgrounding it just adds a poll round-trip. - You cannot proceed without the result. If the very next thing you do consumes the output, block on `bash`. - The work is pure calculation or data shaping. That is the `compute` tool, not a shell at all - see [`compute-over-bash`](../compute-over-bash/SKILL.md). ## Workflow 1. **Start the job.** `bg_bash` `start` with `command` (and `cwd` / `label` / `env` if needed). It returns a job id and the job begins running detached. Record the id - you need it for every later action. 2. **Do inline work.** The turn is yours again. Draft code, read files, start other jobs. 3. **Check cheaply when you want a pulse.** `bg_bash` `status` with the id is a single-line snapshot (running / exited, duration, bytes). Do not tight-poll - one `status` between substantial inline work, not one per line of reasoning. 4. **Read output incrementally.** `bg_bash` `logs` with the id. Use `tail: N` for the last N lines, `grep` to filter, and `sinceCursor` (the opaque cursor from a prior `logs` call) to resume without re-reading. If the response sets `droppedBefore: true`, the ring buffer evicted that range - fall back to the on-disk `logFile` it names. 5. **Block when you actually need the result.** `bg_bash` `wait` with a generous `timeoutMs` (default 15000). It returns when the job exits, or `timedOut: true` if still running - then loop or keep working. 6. **Stop or clean up.** `bg_bash` `signal` (default `SIGTERM`) kills a live job and its process group. `bg_bash` `remove` drops a terminal job from the registry - it refuses live jobs, so signal first. ## Steering interactive jobs A job started with `interactiveStdin: true` gets a writable stdin. Feed it with `bg_bash` `stdin` (`text`, optional `eof` to close the stream after writing). Without `interactiveStdin`, stdin is `/dev/null` and any `stdin` action errors - this is the default so non-interactive commands that incidentally read stdin see EOF instead of hanging. ## Do not orphan jobs Every job id you start is a commitment. Jobs live for the pi session and survive turn boundaries; a forgotten dev server keeps running and burning resources. Before ending a turn, for each live job: `wait` on it (if you need it), note in `scratchpad` that you will check it next turn, or `signal` it (if obsolete). On `session_shutdown` pi sends every live job `SIGTERM`, waits `PI_BG_BASH_KILL_GRACE_MS` (default 3000), then `SIGKILL` - but that is a backstop, not your exit plan. ## Common pitfalls - **Backgrounding a quick command, then immediately `wait`ing.** That is a blocking `bash` call with extra steps. If you will wait right away, use `bash`. - **Tight `status` polling.** Each call burns a tool slot. Prefer one `wait` with a real `timeoutMs` over a stream of `status` checks. - **Forgetting the job id across a compaction.** Stash `id -> what it runs` in `scratchpad` so you can re-attach. - **Expecting state to persist across pi restarts.** Jobs are session-scoped. A restart leaves only `exited` / `error` history; live jobs from a dead runtime are pruned. - **Reaching for `bg_bash` to compute.** No filesystem-free sandbox here - it is a real shell. Pure math / JSON reshape belongs in `compute`. ## Related docs - [`bg-bash.md`](../../extensions/bg-bash.md) - full tool reference: every action, log buffering, signals, env vars. - [`compute-over-bash`](../compute-over-bash/SKILL.md) - route pure computation to `compute` instead of any shell. - [`subagent-background`](../subagent-background/SKILL.md) - the analogous lifecycle for background subagents.
Versions
The database has no other skills named background-bash.
Database snapshot: 13.11.2026 · package version 10843aabab60 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 96running-long-commands
Runs a command that takes over a minute as a background command with its own log and exit code, plus the watch_run tool, so the session wakes once. Use when starting or planning a build, test suite, benchmark or any run expected to pass a minute. - 100test-output-to-logfile
When running test scripts or long-running commands that produce verbose output, redirect output to a log file under logs/ to avoid truncation in the Bash tool. Claude should use this skill when running test scripts, end-to-end tests, or any command likely to produce large… - 100long-command-check
Audit how an agent harness runs long shell commands, covering foreground wait limits, moving to background without re-running, timeouts, completion notification, polling, output size, cleanup and behaviour after compaction. Use when building or reviewing an agent's shell or… - 100review-shell-scripts
Review all shell scripts against the Bash Script Convention. Use when you need to check script compliance or before committing changes. - 90doom-runner
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. - 95bash-linux
Bash and Linux/macOS shell patterns - operators, files, processes, text tools, scripts. Use for shell work on Unix.