gob

Process manager for AI agents (and humans).

gob lets your AI coding agent start background processes and inspect them later. The agent starts a dev server or a build, then reads its logs, status, and ports on a later turn. (Pronounced job, of course.) You can also start and inspect backgroud jobs yourself.

Why gob

gob replaces ad-hoc backgrounding (&, nohup, stray tmux panes, scrollback) with a managed job store that you and your agent both read and control. That single idea buys:

• Shared view - You and your coding agent see the same processes, logs, and status.
• Real-time log streaming - Follow stdout/stderr from CLI, TUI, or agent without copying output.
• Real-time sync - Changes from the CLI appear instantly in the TUI, and vice-versa.
• Interactive TUI - Full-screen terminal interface with live job status.
• Per-directory jobs - Jobs are scoped to directories, keeping projects organized.
• Process lifecycle control - Start, stop, restart, and signal any job.
• Port monitoring - Inspect listening ports across a job's entire process tree.
• Reliable shutdowns - Stop, restart, and shutdown verify every child in the tree is gone.
• Job persistence - Jobs survive daemon restarts with SQLite-backed state.
• Run history - Track execution history, statistics, and progress estimates for repeated commands.
• Stuck detection - Detects jobs that may be stuck and returns early, while the job keeps running.
• Blocked jobs - Prevent agents from accidentally running dangerous commands.

Installation

Install gob with Homebrew, go install, or a pre-built binary.

brew tap juanibiapina/taps
brew install gob

go install github.com/juanibiapina/gob@latest

# Download the appropriate binary for your platform
# For example, macOS Apple Silicon (arm64):
curl -LO https://github.com/juanibiapina/gob/releases/latest/download/gob_VERSION_darwin_arm64.tar.gz

# Extract the archive
tar -xzf gob_VERSION_darwin_arm64.tar.gz

# Move to your PATH
sudo mv gob /usr/local/bin/

# Verify installation
gob --version

Quick Start

The everyday flow is one of two shapes: run and wait, or add and come back later.

# Usage overview
gob

# Run a command and wait for completion
gob run make test

# Add a background job (returns immediately)
gob add -- make test
gob add -- pnpm --filter web typecheck

# Wait for a job to complete
gob await abc

# List all jobs
gob list

# View stdout and stderr
gob logs abc

# Stop a job
gob stop abc

# Remove a stopped job
gob remove abc

Using with AI Coding Agents

gob ships an agent skill with instructions for AI coding agents. Install it with the skills CLI:

npx skills add juanibiapina/gob

This makes the gob instructions available to your agent (Claude Code, Cursor, Codex, and others). The skill lives at skills/gob/SKILL.md; you can also copy its contents into your agent's configuration file (CLAUDE.md, AGENTS.md, etc.).

Interactive TUI

When you want to watch and control jobs directly, launch the full-screen terminal interface:

gob tui

Layout

The TUI has an info bar and five panels:

• Info bar: Shows working directory and version
• Panel 1 (Jobs): List of all jobs with status (◉ running, ✓ success, ✗ failed)
• Description: Shows job description (only visible when selected job has one)
• Panel 2 (Ports): Listening ports for the selected job
• Panel 3 (Runs): Run history for the selected job
• Panel 4 (stdout): Standard output of selected run
• Panel 5 (stderr): Standard error of selected run

Key Bindings

Process-control keys (s/S/r/d) act on the selected job from any panel. The only exception is d in the Runs panel, where it deletes the selected run.

Auto-Start with Gobfile

To start a project's usual jobs automatically when the TUI launches, create a .config/gobfile.toml in the project directory:

[[job]]
command = "npm run dev"
description = "Frontend on http://localhost:3000. Check here for UI errors."

[[job]]
command = "npm run api"
description = "API server on http://localhost:4000. Check logs for request debugging."

[[job]]
command = "npm run storybook"
description = "Component library on http://localhost:6006"
autostart = false  # Add but don't start automatically

[[job]]
command = "npm run db:reset"
description = "DANGER: Drops and recreates the database"
blocked = true  # Prevent accidental execution

Fields:

• command (required): The command to run
• description (optional): Context for AI agents (ports, URLs, what to check for)
• autostart (optional): Whether to start the job when TUI opens (default: true)
• blocked (optional): If true, the job cannot be started; CLI shows description when attempted (default: false)

Behavior:

• Jobs are started asynchronously when TUI opens (if autostart = true)
• Jobs are stopped when TUI exits (including when terminal is killed)
• Already-running jobs have their descriptions updated if different
• Stopped jobs with matching commands are restarted
• Jobs with autostart = false are added but not started

Tip: Add .config/gobfile.toml to .gitignore if you don't want to share it.

CLI Reference

Run gob <command> --help for detailed usage, examples, and flags.

Shell Completion

gob provides live job-ID suggestions with command descriptions as you type.

Homebrew installs completions automatically for Bash, Zsh, and Fish — no setup needed. Just start a new shell.

For manual installs, write the completion script once to a file on your shell's completion path. Don't source <(gob completion ...) from your shell rc: that spawns gob on every new shell and slows startup. Generate the file instead, and regenerate it only when you upgrade gob.

gob completion bash > "$(brew --prefix 2>/dev/null || echo /usr/local)/etc/bash_completion.d/gob"

# Write to a directory on your fpath (must be listed in fpath before compinit runs)
mkdir -p ~/.zsh/completions
gob completion zsh > ~/.zsh/completions/_gob
# In ~/.zshrc, before `compinit`:
#   fpath=(~/.zsh/completions $fpath)

gob completion fish > ~/.config/fish/completions/gob.fish

Contributing

Interested in contributing? Check out CONTRIBUTING.md for development setup, build instructions, testing instructions, and contribution guidelines.

Star History