GitHub - juanibiapina/gob: Process manager for AI agents (and humans)

Process manager for AI agents (and humans).

gob (pronounced job, of course) is a CLI for managing background processes with a shared interface for you and your AI coding agent.

Start a dev server with Claude Code, check its logs yourself. Or vice-versa. The agent can monitor what you started. Everyone has the same view.

No more "can you check if that's still running?" No more copy-pasting logs through chat. Just direct access to your processes, for everyone.

Features

• Interactive TUI - Full-screen terminal interface with real-time job status
• Real-time log streaming - Follow stdout/stderr from CLI, TUI, or AI agents without copying output
• AI agent friendly - Shared view of all processes for you and your coding agent
• Real-time sync - Changes from CLI instantly appear in TUI, and vice-versa
• Per-directory jobs - Jobs are scoped to directories, keeping projects organized
• Process lifecycle control - Start, stop, restart, send signals to any job
• Port monitoring - Inspect listening ports across a job's entire process tree
• Reliable shutdowns - Stop, restart, and shutdown verify every child process 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 - Automatically detects jobs that may be stuck and returns early, while the job continues running
• Blocked jobs - Prevent AI coding agents from accidentally running dangerous commands

Installation

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

# 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

For AI agents, add the following instructions to your agent's configuration file (CLAUDE.md, AGENTS.md, etc).

## Background Jobs with `gob`

Use `gob` for servers, long-running commands, and builds.

### When to Use gob

Use `gob` for:
- **Servers**: `gob add npm run dev`
- **Long-running processes**: `gob add npm run watch`
- **Builds**: `gob run make build`
- **Parallel build steps**: Run multiple builds concurrently

Do NOT use `gob` for:
- Quick commands: `git status`, `ls`, `cat`
- CLI tools: `jira`, `kubectl`, `todoist`
- File operations: `mv`, `cp`, `rm`

### gob Commands

- `gob add <cmd>` - Start command in background, returns job ID
- `gob add --description "context" <cmd>` - Start with description for context
- `gob run <cmd>` - Run and wait for completion (output on failure only)
- `gob run --description "context" <cmd>` - Run with description for context
- `gob await <job_id>` - Wait for job to finish, stream output in real-time
- `gob list` - List jobs with IDs, status, and descriptions
- `gob logs <job_id>` - View stdout and stderr (stdout→stdout, stderr→stderr)
- `gob stdout <job_id>` - View current stdout (useful if job may be stuck)
- `gob stop <job_id>` - Graceful stop
- `gob restart <job_id>` - Stop + start

### Stuck Detection

`gob run` and `gob await` automatically detect potentially stuck jobs:
- Timeout: avg duration + 1 min (or 5 min if no history), triggers if no output for 1 min
- Job continues running in background
- Use `gob logs <id>` or `gob stdout <id>` to check output, `gob await <id>` to continue waiting

### Examples

Servers and long-running:
```
gob add npm run dev                              # Start dev server
gob add --description "File watcher" npm run watch  # With description
```

Builds:
```
gob run make build                           # Run build, wait for completion
gob run npm run test                         # Run tests, wait for completion
gob run --description "Type check" npm run typecheck  # With description
```

Regular commands (no gob):
```
git status
kubectl get pods
jira issue list
```

Interactive TUI

Launch a full-screen terminal interface for managing jobs:

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

Create a .config/gobfile.toml in your project directory to automatically start jobs when the TUI launches:

[[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 supports shell completion for Bash, Zsh, and Fish. Completions include dynamic job ID suggestions with command descriptions.

# Add to ~/.bashrc
source <(gob completion bash)

# Add to ~/.zshrc
source <(gob completion zsh)

autoload -Uz compinit && compinit

# Add to ~/.config/fish/config.fish
gob completion fish | source

Telemetry

gob collects anonymous usage telemetry to help inform development priorities. Only usage metadata is collected; command arguments and output are never recorded.

You can opt out by setting GOB_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 in your environment.

See docs/telemetry.md for details on what's collected.

Contributing

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

Star History