bgo — Background Go

Lightweight, zero-dep background process manager inspired by pm2. Detach any binary or script from your shell with one command.

PyPI: https://pypi.org/project/bgo-cli/

Features

• Simple syntax — bgo <name> -- <command>
• Unix-style aliases — bgo open / kill / rm / ls
• Status monitoring — CPU, memory, uptime; plain / normal / fancy tables with auto-detection
• Log management — stdout / stderr / watcher logs with follow mode
• Lifecycle — start, stop, restart, restart-stopped, restart-last, resurrect
• Watch mode — auto-restart crashed processes with fast-crash backoff
• Desktop notifications on errored transitions
• Login autostart via systemd-user (Linux) or LaunchAgent (macOS)
• Per-proc autostart policy — always, unless-stopped (default), or never; controls what bgo resurrect brings back at login
• Tray icon (optional) — PySide6, gear+dot status indicator, KDE/Hyprland/GNOME/macOS
• Scriptable — --json output for any pipeline
• Zero runtime dependencies in the core; one optional extra for the tray

Quick start

uv tool install bgo-cli          # see docs/installation.md for alternatives

bgo myserver -- python3 -m http.server 8080
bgo ls
bgo logs myserver -f
bgo restart myserver
bgo stop myserver

# Control login autostart behavior
bgo autostart set myserver never
bgo autostart install            # run bgo resurrect at login

bgo with no args prints help. bgo <unknown> errors out rather than silently spawning something.

Documentation

Long-form docs live in docs/:

Sample status table

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ NAME         STATUS     PID      CPU    MEM    UPTIME    WATCH      COMMAND                    ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ web          ● online   12345    2.5    0.1    00:05     ✓ 0        python3 -m http.server 8080 ┃
┃ api          ● online   12346    0.0    0.0    01:23     ✓ 3        node server.js              ┃
┃ worker       ○ stopped  -        -      -      -         ⚠ errored  python3 worker.py           ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Total: 3 | ● online: 2 | ○ stopped: 1

⚠ 1 errored:
   worker — 4 consecutive fast-crashes
     bgo logs worker --watcher   |   bgo restart worker

Override the rendering with --plain / --fancy or BGO_TABLE=plain|normal|fancy.

Storage

• State: ~/.bgo/procs/<name>.json — one file per process, atomic writes.
• Logs: ~/.bgo/logs/<name>.{out,err,watcher}.log.

Full layout: docs/architecture.md.

Testing

uv run pytest tests/ -v

227 tests covering state I/O, atomic writes, command-shape detection, name derivation, liveness + zombie filtering, watch-config inheritance, watch loop behavior, table rendering, desktop notifications, login autostart, autostart policy, direct-mode parsing, core command handlers, and tray menu construction.

Requirements

• Python 3.10+
• Linux or macOS
• Optional [tray] extra: PySide6 (Qt for Python, LGPL)

License

MIT.