bg-jobs

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)