Background Jobs Skill

Run and manage background jobs from the terminal, with friendly names, live runtime details, wait support, and persisted exit metadata.

Installation Check

bg --help

If not installed:

uv tool install "git+https://github.com/lirrensi/agent-sommelier"

Command name: bg vs bgj

The CLI installs two entry points for the same command: bg and bgj.

• bg collides with the shell builtin of the same name (POSIX job control — "move jobs to the background"). Builtins always win over PATH lookup, so on bash/zsh/fish bg --help shows the shell's builtin, not this tool.
• Use bgj on bash/zsh/fish — it is collision-free. On PowerShell/cmd (no bg builtin) plain bg works.
• If you prefer bg everywhere, alias it in your shell profile: alias bg='env bg' (bash/zsh). (command bg does NOT work — it resolves to the builtin too.)

All examples below use bg; substitute bgj on POSIX shells.

Usage

bg runs commands in your platform shell. bg run returns immediately after creating the handle; a detached worker finishes the launch in the background and jobs appear running unless failure is proven. A short best-effort PID probe updates the record a few seconds later when it can. On Windows it prefers PowerShell 7, then Windows PowerShell, then cmd.exe, launches jobs without a visible console window when PowerShell is available, and expects shell syntax that matches the shell you expect.

Run a Background Job

bg run "python long_script.py"
# Returns: sleepy-pytest (friendly name)

Run from a specific directory (the process actually runs there, and the directory is recorded):

bg run --cwd /path/to/repo "pytest tests/ -v"

bg run "python --version"

List Jobs

bg list            # running jobs only (running / launching / starting)
bg list --all      # everything: Running section + dim Settled section
bg list --all --page 2   # page through long lists (20 rows per page)
bg list --json     # running jobs as JSON (same default filter)
bg list --all --json     # full JSON dump (never paginated)

bg list shows live job details including name, UID, record state, process state, status, PID, start time, elapsed runtime, the recorded working directory (Dir column), and command. Tables longer than 20 rows print a Showing X-Y of Z (page N/N) footer plus a use --page N hint.

Check Job Status

bg status sleepy-pytest

bg status <ref> refreshes the job before printing JSON. Use either the friendly name or UID. Running jobs may include elapsedseconds, memorybytes, and cpupercent. Finished jobs can also include finishedat and exit_code.

Wait for Completion

bg wait sleepy-pytest

Wait for Output

bg wait sleepy-pytest --match "needle"

Wait for All Jobs

bg wait-all

Timeouts & Agent Safety

bg wait and bg wait-all apply an agent-protection timeout by default: 120 seconds in non-TTY (agent/script) mode, infinite in TTY (interactive) mode. Detection: if either stdin or stdout is not a TTY, the cap fires.

Override the cap with --timeout N (float seconds, N >= 0):

• --timeout 0 disables the cap and waits until the job ends.
• --timeout 300 waits up to 5 minutes.

When the cap fires:

• A clear message is written to stderr (not stdout) explaining the wait loop — not the job — was terminated, naming the still-running job(s) and elapsed times, and listing the re-poll commands.
• Exit code is 0. The stderr message is the contract: agents should detect a timed-out wait by reading stderr, not by the exit code.

Recommended re-poll pattern:

# Wait hit the 120s cap. The job is still running. Decide next step:
bg status sleepy-pytest           # check current state
bg wait sleepy-pytest --timeout 300   # wait up to 5 more minutes
bg wait sleepy-pytest --timeout 0     # wait until the job ends (no cap)
bg logs sleepy-pytest             # read partial output

In an interactive TTY terminal, the default behavior is unchanged (wait forever; ctrl+c to abort). The 120s cap only activates when the CLI is invoked as a subprocess, which is the common case for LLM agents.

Read Job Output

bg read sleepy-pytest            # full stdout
bg read sleepy-pytest --tail     # only output since the last tail read
bg logs sleepy-pytest            # stdout + stderr

bg read <ref> --tail prints only new output and remembers the read position per job, so repeated calls never re-print old content — ideal for watching a running job without re-reading the whole file. bg read / bg logs print a cwd: <path> header when the job records a working directory.

Remove Job

bg rm sleepy-pytest

Prune Non-Running Jobs

bg prune

Deletes every job that is not currently running, including stale or broken records.

Restart Job

bg restart sleepy-pytest

bg restart <ref> kills the process if alive and starts a new one with the same command and the same recorded working directory. Output appends to existing stdout/stderr files (like ctrl+c + run again). The job keeps the same UID and name.

Workflow Pattern

# Bash / zsh
JOB_NAME=$(bg run "python train_model.py")
bg status $JOB_NAME
bg read $JOB_NAME

# PowerShell
$jobName = bg run "python train_model.py"
bg status $jobName
bg read $jobName

Job Storage

Jobs keep runtime state in your OS temp directory under agentcli_bgjobs/:

• index.json - Friendly-name and UID lookup index
• records/<uid>/meta.json - Canonical job metadata (uid, name, cmd, cwd, pid, status, startedat, optional finishedat, optional exitcode, optional recordissue, lastreadoffset, and live runtime fields)
• records/<uid>/meta.json - Canonical job metadata (uid, name, cmd, pid, status, startedat, optional finishedat, optional exitcode, optional recordissue, and lightweight event fields such as lasteventtype, lasteventat, matchedpattern, and matchedstream)
• records/<uid>/stdout.txt - Standard output
• records/<uid>/stderr.txt - Standard error
• records/<uid>/exit_code.txt - Persisted exit code

Terminal jobs are automatically pruned: keep them for at least 1 hour, cap history at 32 jobs, and evict the oldest terminal jobs first. Running jobs are never evicted automatically.

Windows note:

• PowerShell syntax works by default when pwsh or powershell is available
• Windows background jobs are started hidden, so there is no extra console window to close
• Use explicit cmd.exe /d /c "..." if you need cmd-specific syntax

Status Values

• running - Process is still active
• launching - Internal-only launch state; user-facing status is shown as running until failure is proven
• completed - Process finished
• failed - Process exited with error
• stale - Record is healthy but PID is gone and no exit code was found
• missing / corrupt / orphaned - Record problem surfaced by bg list / bg status

Launch failures keep the handle and mark the record failed instead of deleting it.

bg list also shows a short update marker when a job has a notable event such as completion, failure, or matched output.

Examples

# Download large file
bg run "curl -O https://example.com/large_file.zip"

# Run tests in background
bg run "pytest tests/ -v"

# Run from a specific repo directory
bg run --cwd /path/to/repo "pytest tests/ -v"

# Start a server
bg run "python -m http.server 8000"

# Check one job as JSON
bg status sleepy-pytest

# Check all running jobs
bg list

# See everything, including finished jobs
bg list --all

# Page through a long history
bg list --all --page 2

# Watch live output without re-printing old lines
bg read sleepy-pytest --tail

# Wait for a job to finish
bg wait sleepy-pytest

# Wait for a log line to appear
bg wait sleepy-pytest --match "ready"

# Wait for all known jobs
bg wait-all

# Read merged logs
bg logs sleepy-pytest

# Restart a job
bg restart sleepy-pytest

# Native PowerShell command
bg run "Get-Process | Sort-Object CPU -Descending | Select-Object -First 5"

# Force cmd syntax when needed
bg run "cmd.exe /d /c dir"