Use when launching anything that runs longer than a minute, anything that streams logs, anything you want to keep running while doing other work — or when terminal_exec auto-backgrounded on you and returned a job_id. Teaches the start→poll→wait pattern with terminal_job_logs offset bookkeeping, bounded blocking polls, platform-specific process control via terminal_job_manage capabilities, and the hard rule that jobs die when the terminal-tools server restarts. Read before calling terminal_job_start, or right after terminal_exec auto-backgrounded.
Background jobs are how you do things that take time without blocking your conversation. Three tools cover the surface: terminal_job_start, terminal_job_logs, terminal_job_manage.
terminal_exec (you have a job_id; pivot to this skill's idioms)For one-shot work expected to finish quickly, terminal_exec is simpler. The auto-promotion mechanic in terminal_exec is your safety net — start with terminal_exec, take over with this skill if needed.
terminal_job_start(command, ...)
→ { job_id, pid, started_at }
terminal_job_logs(job_id, since_offset=0, max_bytes=64000)
→ { data, offset, next_offset, status: "running"|"exited", exit_code, ... }
# Repeat with since_offset = previous next_offset until status == "exited"
# Or, better when you have nothing else to do, wait once with wait_until_exit=True:
terminal_job_logs(job_id, since_offset=N, wait_until_exit=True)
→ waits until exit, a new message for you, or wait_timeout_sec (at most 600, the default)After exit, the job is retained for inspection (terminal_job_manage(action="list")) until evicted by FIFO (50 most recent exits kept).
The job's output lives in a 4 MB ring buffer per stream. Each call to terminal_job_logs returns:
data — bytes between since_offset and next_offsetnext_offset — pass this as since_offset on your next calltruncated_bytes_dropped — non-zero when your since_offset was older than the ring's floor (you fell behind)Always carry next_offset forward. Don't replay from 0 — that's an offset reset, you'll see the same data twice and miss the part that fell off.
When truncated_bytes_dropped > 0, the buffer evicted N bytes between your last call and now. Treat it as a signal that the job is producing output faster than you're consuming. Either poll more often or accept the gap and read from next_offset going forward.
merge_stderr=False → two streams, request "stdout" or "stderr" by name
merge_stderr=True → one stream ("merged"), order preservedPick merge_stderr=True when:
Pick merge_stderr=False when:
First query the actions implemented on the server's platform:
terminal_job_manage(action="capabilities")
# Returns platform, supported_actions, signals (action → semantics), note.On POSIX, request signal_int, wait and inspect the job, then use signal_term if needed. signal_term gives the process group up to 2 seconds before forced cleanup; signal_kill forces termination immediately. Cleanup in response to SIGINT/SIGTERM depends on the application.
On Windows, signal_term and signal_kill both forcefully terminate the job process tree. Neither invokes application cleanup handlers. signal_int / Ctrl-C and the other POSIX signals are unsupported and return unsupported_action with the supported actions. If a program has a documented shutdown command on stdin, that can be used before forced termination.
After signaling, check exit with terminal_job_logs(job_id, wait_until_exit=True, wait_timeout_sec=2).
terminal_job_manage(action="stdin", job_id=..., data="some input\n")
terminal_job_manage(action="close_stdin", job_id=...)For tools that read stdin to EOF, close_stdin after writing flushes them. For interactive tools that read line-by-line, just write each line.
When terminal_exec returned auto_backgrounded: true, job_id: <X>, the process is already in the JobManager with its output flowing into the ring buffer. Your transition is seamless:
# Already saw the start of output in terminal_exec's stdout/stderr.
# Pick up reading where the env left off — use the byte count of the
# initial stdout as your since_offset, OR just request tail output:
terminal_job_logs(job_id="job_xxx", tail=True, max_bytes=64000)Or block until exit and grab everything:
terminal_job_logs(job_id="job_xxx", since_offset=0, wait_until_exit=True)nohup does not escape managed process-tree cleanup; durable services need a separate service manager.TERMINAL_TOOLS_MAX_JOBS, default 32). Past the cap, terminal_job_start returns an error. Wait for jobs to exit or kill old ones.See references/signals.md for the full signal catalog.
aden-hive/hive
c6c2cdc
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.