How to use the Background Job Control agent skill

What the skill makes the agent do

Without this skill, an agent either waits for a command to finish or loses track of it. With the skill installed, the agent starts long-running work as a background job, gets back a job ID, and keeps working while the job runs.

The skill covers three Hive tools: terminal_job_start launches a job, terminal_job_logs reads its output, and terminal_job_manage handles stopping it, sending stdin, and listing jobs.

• Builds, deploys and long test runs
• Dev servers and other processes you want to monitor
• Commands that terminal_exec moved to the background on its own

How to install the Background Job Control skill

Download the skill ZIP from this page. Then choose one of the two install routes below.

For Claude Code, unzip the file into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills

How to trigger the skill with natural requests

You do not need a special command. Ask for something that takes time, or that you want to keep watching, and the agent should pick up the skill. The skill's description says it applies when a command runs longer than a minute, streams logs, or should keep running while other work happens. It also applies when terminal_exec has already moved a command to the background and returned a job_id.

Plain requests that fit the skill include asking the agent to run the full test suite while it keeps reviewing code, or to start the dev server and tell you when it is ready.

• Run the full test suite in the background and keep working on the bug meanwhile.
• Start the dev server and watch its log for errors.
• Follow the log file build.log and tell me when the build fails.
• Stop the background build that is still running.

Read job output without losing or repeating lines

The agent reads output in pieces. Each call to terminal_job_logs returns a next_offset value, and the agent passes that value back as since_offset on the next call. This is how it avoids both replaying old lines and skipping new ones.

If the agent has fallen behind, the response includes truncated_bytes_dropped. A value above zero means the output buffer discarded bytes you had not read yet, so the job is producing output faster than it is being read. The fix is to poll more often, or to accept the gap and continue from next_offset.

To wait for a job to finish in one call, the agent can block on the server with wait_until_exit and a timeout.

• Output is held in a 4 MB ring buffer per stream.
• Use merge_stderr=True when the output should be read as one ordered stream, such as most servers and build tools.
• Use merge_stderr=False when stderr is only errors and stdout is data.

Stop a background job safely on Linux, macOS or Windows

Before sending any signal, the agent should ask the server which actions it supports. The capabilities action returns the platform, the supported actions, and the meaning of each signal.

On Linux and macOS, the escalation order is signal_int first, then signal_term if the job does not stop, and signal_kill only as a last resort. signal_term allows up to 2 seconds before forced cleanup. Whether the program cleans up depends on the program itself.

On Windows, signal_term and signal_kill both forcefully terminate the whole job process tree, with no application cleanup. signal_int and other POSIX signals return unsupported_action. If the program has a documented shutdown command read from stdin, the agent can write it first, then force termination.

• Check what is supported: terminal_job_manage(action="capabilities")
• Linux/macOS order: signal_int, then signal_term, then signal_kill
• Windows: signal_term or signal_kill only, both forceful
• After signaling, confirm the exit with wait_until_exit and wait_timeout_sec=2

Know the limits and safety notes

The most important rule is that background jobs end when the terminal-tools server restarts. The desktop runtime restarts terminal-tools when Hive restarts, and there is no way to reattach. Using nohup does not prevent this. Anything that must keep running across restarts needs a real service manager.

The server allows a maximum number of concurrent jobs, set by TERMINAL_TOOLS_MAX_JOBS with a default of 32. When that cap is reached, terminal_job_start returns an error until jobs exit or are stopped. Output is kept in memory only, so it is not available after a restart. The 50 most recent finished jobs remain listed, and older ones are dropped first in first-out order.

The skill runs scripts, but it does not use the network.

• Jobs end when terminal-tools restarts; no reattach.
• nohup does not change this.
• Default cap is 32 concurrent jobs (TERMINAL_TOOLS_MAX_JOBS).
• Finished jobs: the 50 most recent are kept for inspection.
• Output lives in memory only and is not kept across restarts.