Big Jobs

Run heavy or long-running shell commands as detached background processes that survive agent restarts. Each job gets OOM protection (on systemd), captured stdout/stderr, an exit code, and metadata.

Usage

All commands go through the big-job dispatcher in scripts/. Set the path once:

J="<path-to-skill>/scripts/big-job"

Typical workflow

# Start and see output streaming (job survives if agent dies):
"$J" start -d /home/user/project make -j8

# Start without following (fire-and-forget):
"$J" start -n -d /home/user/project make -j8

# Check on a job later:
"$J" status <ID>
"$J" output <ID>

# List all jobs:
"$J" list

The start command prints big-job:<ID> immediately, then tails the log until the job finishes. The job is already detached — if the Bash call times out or is killed, the job keeps running. Use -n for fire-and-forget.

Exit codes

Jobs directory

~/.local/share/big-job/<ID>/ (override with $BIG_JOB_DIR):

• meta.json — id, command, timestamps, pid/unit
• command.sh — raw command text
• output.log — combined stdout+stderr (line-buffered)
• exit_code — written atomically on completion

Dependencies

None beyond standard POSIX utilities (sh, sed, od, find, tail, head). Optional: systemd-run for OOM protection on Linux.

Guidelines

• Always tell the user the job ID and what's running
• Default to background for anything > 30 seconds
• Check exit codes — don't assume success; read output on failure
• Use tail for output — logs can be huge; don't cat the entire file
• Working directory — always pass an absolute path with -d
• Reconnection — run "$J" list to find active jobs after restart