Background jobs: run dev servers and watch builds without blocking the agent

The blocking problem#

Some commands are supposed to never finish. npm run dev, vite, tail -f, a test runner in watch mode — start one in the foreground and the agent sits there, blocked, until you kill it. The workaround was always hacky: background the process with & and lose its output, or redirect to a file and poll it by hand.

run_in_background → bash_output → kill_shell#

The bash tool now takes run_in_background: true. Instead of blocking, it returns a shell id (bash_1, bash_2, …) right away, and the agent moves on. Two companion tools manage the job from there:

• bash_output— cursor-based incremental reads, so each call returns only what's new since the last one. An optional regex filter narrows the output to the lines that matter.
• kill_shell — stops a background job by id.

# start it — returns immediately with a shell id
bash(run_in_background: true)  →  "started bash_1: npm run dev"

# read only what's new, optionally filtered
bash_output(bash_1, filter: "Local:|error")  →  "  ➜  Local:  http://localhost:3000/"

# stop it when you're done
kill_shell(bash_1)  →  "bash_1 terminated"

Where the output goes#

Each job's output is buffered in memory andtee'd to a per-job log file at ~/.harnext/projects/<hash>/bg-shells/<id>.log, so nothing is lost between reads. Background shells are SIGTERM'd when the session exits — no orphaned dev servers hanging around. Prefer the old always-blocking behavior? Set HARNEXT_DISABLE_BACKGROUND_TASKS=1 and run_in_background is ignored.

Watch them live in the CLI#

Interactively, a ⚙ N Background Jobs chip sits in the footer next to the git branch. Press ↓ on an empty prompt to focus it and ⏎ to open a live, auto-refreshing viewer (or just run /bashes). Inside, k kills the selected job and ←/esc goes back. Completion notices print above the prompt as jobs finish.

Read the docs#

← All posts