Background jobs

Run shell commands that never return — dev servers, watch builds, long installs — without blocking the agent.

The bash tool can launch a command in the background, returning a shell id immediately instead of waiting for it to finish. Two companion tools — bash_output and kill_shell — read its output and stop it. This is the right tool for anything long-lived: a dev server, a file watcher, a test runner in watch mode, a slow install.

The three tools#

bash — run_in_background#

Pass run_in_background: true to bash. It starts the command and returns a shell id (bash_1, bash_2, …) right away; the agent continues without blocking.

bash(command: "npm run dev", run_in_background: true)
→ "started bash_1"

bash_output#

Read what a background job has produced. Reads are cursor-based — each call returns only the output appended since the previous read, so polling a chatty job stays cheap. An optional regex filter keeps only matching lines.

bash_output(shell_id: "bash_1")
→ new output since the last read

bash_output(shell_id: "bash_1", filter: "Local:|error|warning")
→ only lines matching the regex

kill_shell#

Terminate a background job by id.

kill_shell(shell_id: "bash_1")
→ "bash_1 terminated"

Output & lifecycle#

• Buffered everywhere.Output is held in memory and tee'd to a per-job log file at ~/.harnext/projects/<hash>/bg-shells/<id>.log, so nothing is lost between bash_output reads.
• Cleaned up on exit. Background shells are SIGTERM'd when the session ends — no orphaned processes.
• Toggle. Set HARNEXT_DISABLE_BACKGROUND_TASKS=1 to make every command block as before; run_in_background is then ignored.

The interactive viewer#

In the interactive CLI, a ⚙ N Background Jobs chip sits in the footer beside the git branch. To open the viewer:

• Press ↓ on an empty prompt to focus the chip, then ⏎ to open it — or run /bashes.
• The viewer auto-refreshes with live output. k kills the selected job; ← or esc goes back.
• Completion notices print above the prompt as jobs finish, so you don't have to watch the viewer to know a build is done.