# Hive.terminal Tools Job Control

Use when launching anything that runs longer than a minute, anything that streams logs...

- Repository: https://github.com/aden-hive/hive (11131 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aden-hive/hive --skill hive.terminal-tools-job-control -g -a claude-code -y`
Codex: `npx skills add aden-hive/hive --skill hive.terminal-tools-job-control -g -a codex -y`
Cursor: `npx skills add aden-hive/hive --skill hive.terminal-tools-job-control -g -a cursor -y`
Gemini CLI: `npx skills add aden-hive/hive --skill hive.terminal-tools-job-control -g -a gemini-cli -y`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Background job control

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`.

## When to use a job

- Builds, deploys, long tests
- Processes you want to monitor (streaming a log file, a dev server)
- Anything that auto-backgrounded from `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.

## Lifecycle

```
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 block once with wait_until_exit=True:
terminal_job_logs(job_id, since_offset=N, wait_until_exit=True, wait_timeout_sec=30)
  → blocks server-side until exit or timeout
```

After exit, the job is retained for inspection (`terminal_job_manage(action="list")`) until evicted by FIFO (50 most recent exits kept).

## Offset bookkeeping, the only rule that matters

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_offset`
- `next_offset`, pass this as `since_offset` on your next call
- `truncated_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.

The rest: https://github.com/aden-hive/hive/blob/HEAD/core/framework/skills/_preset_skills/terminal-tools-job-control/SKILL.md