https://github.com/bethropolis/bgrun
yet another background process runner. daemon-managed, auto-shutdown, PTY attach, wait-for-pattern, memory guardrails
https://github.com/bethropolis/bgrun
ai-agents background-jobs cli daemon process-manager rust
Last synced: 5 days ago
JSON representation
yet another background process runner. daemon-managed, auto-shutdown, PTY attach, wait-for-pattern, memory guardrails
- Host: GitHub
- URL: https://github.com/bethropolis/bgrun
- Owner: bethropolis
- License: mit
- Created: 2026-05-31T16:46:21.000Z (18 days ago)
- Default Branch: main
- Last Pushed: 2026-06-13T00:47:20.000Z (5 days ago)
- Last Synced: 2026-06-13T01:10:08.577Z (5 days ago)
- Topics: ai-agents, background-jobs, cli, daemon, process-manager, rust
- Language: Rust
- Homepage: https://bethropolis.github.io/bgrun/
- Size: 184 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# bgrun
[](https://github.com/bethropolis/bgrun/actions/workflows/release.yml)
[](LICENSE)
A background process runner for AI agents and automation workflows. Start processes, check status, tail logs, and kill them over a Unix socket with JSON output. The daemon auto-starts on first CLI use.
## Install
### Quick install (Linux)
```bash
curl -fsSL https://bethropolis.github.io/bgrun/install.sh | sh
```
Downloads the latest prebuilt binary from GitHub releases.
### AUR (Arch Linux)
```
yay -S bgrun-bin
```
### Homebrew (Linux)
```bash
brew tap bethropolis/tap
brew install --cask bethropolis/tap/bgrun
```
### From source (Linux)
```bash
./install.sh
```
Requires the Rust toolchain (`cargo`). This builds from a local clone and installs
`bgrun` (CLI) and `bgrun-daemon` (auto-started by the CLI) to `~/.local/bin`.
Optional: install the OpenCode skill bundle from `docs/bgrun/`:
```bash
./install.sh --install-skill
```
## Quick start
```bash
bgrun run --name server --ready-when "listening on" cargo run
# → {"id":"abc123","name":"server","state":"running",...}
bgrun wait abc123 --timeout 30s
bgrun tail abc123 --digest
# → {"total_lines":82,"errors":0,"warnings":2,...}
bgrun kill abc123
```
## Commands
| Command | Purpose |
|---------|---------|
| `bgrun run [flags] ` | Start a background process |
| `bgrun run-group ...` | Start multiple named jobs in parallel |
| `bgrun list [--workspace ]` | List all jobs |
| `bgrun status ` | Get job state |
| `bgrun wait --timeout ` | Block until ready or timeout |
| `bgrun tail [--digest] [--level ]` | Show logs |
| `bgrun diff ` | Show new log lines since last call |
| `bgrun send ` | Write to stdin |
| `bgrun stats ` | Show CPU/RSS/uptime |
| `bgrun kill [--workspace ]` | Terminate job(s) |
| `bgrun attach ` | Attach to a PTY job interactively |
| `bgrun expect ` | Wait for a log line matching pattern |
| `bgrun stats ` | Show CPU/RSS/uptime |
| `bgrun schema ` | Print JSON Schema for a command's args |
| `bgrun skill install ` | Install embedded skill bundle |
| `bgrun` (no args) | Open interactive TUI menu |
## Docs
- [Command Reference](docs/commands.md) — flags, examples, output shapes
- [bgrun.toml](docs/bgrun-toml.md) — named job definitions and dependencies
- [Architecture](docs/architecture.md) — daemon, protocol, readiness system
## Crate layout
Workspace crates:
| Crate | Role |
|-------|------|
| `bgrun-proto` | Shared types, no I/O |
| `bgrun-core` | Job state machine, config parser, no I/O |
| `bgrun-daemon` | Spawns/monitors/kills processes, serves the CLI |
| `bgrun-cli` | User-facing CLI |
CLI and daemon communicate over a Unix socket with NDJSON. The daemon stores state in `~/.local/share/bgrun/`.
## License
MIT