gob

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.

View on asciinema

Features

• Interactive TUI - Full-screen terminal interface with real-time job status and log streaming
• 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

Installation

Using Homebrew

Install gob via Homebrew:

brew tap juanibiapina/taps
brew install gob

Using Go Install

If you have Go installed, you can install gob with a single command:

go install github.com/juanibiapina/gob@latest

Requirements:

• Go 1.25.4 or later

The binary will be installed to $GOPATH/bin (or $GOBIN if set). Make sure this directory is in your PATH.

Pre-built Binaries

Download the latest release for your platform from the Releases page.

Available platforms: Linux, macOS (both amd64 and arm64)

# 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

Build from Source

For build instructions, see CONTRIBUTING.md.

Shell Completion

gob supports shell completion for Bash, Zsh, Fish, and PowerShell. Completions include dynamic job ID suggestions with command descriptions.

Bash

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

Zsh

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

If you get "command not found: compdef", add this before the source line:

autoload -Uz compinit && compinit

Fish

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

PowerShell

# Add to your PowerShell profile
gob completion powershell | Out-String | Invoke-Expression

Quick Start

# Usage overview
gob

# Run a command and wait for it to complete
gob run make test
gob run pnpm --filter web typecheck

# Add a background job (for long-running processes)
gob add python -m http.server 8000

# List all jobs
gob list

# View stdout output
gob stdout abc

# Stop a job
gob stop abc

# Clean up all stopped jobs
gob cleanup

Using with AI Coding Agents

To make gob available to AI coding agents, add the following instructions to your agent's configuration file (CLAUDE.md, AGENTS.md, etc).

General instructions for AI agents

## Background Jobs with `gob`

Use `gob` to manage background processes.

### Running Commands

- `gob add -- <cmd>` - Starts command, returns job ID immediately
  - IMPORTANT: Always use `--` before the command
- `gob await <job_id>` - Wait for job to finish, stream output, return exit code

### Sequential Execution

For commands that must complete before proceeding:

```
gob add -- make build
```

Then immediately:

```
gob await <job_id>
```

Use for: builds, installs, any command where you need the result.

### Parallel Execution

For independent commands, start all jobs first:

```
gob add -- npm run lint
gob add -- npm run typecheck
gob add -- npm test
```

Then collect results using either:

- `gob await <job_id>` - Wait for a specific job by ID
- `gob await-any` - Wait for whichever job finishes first

Example with await-any:

```
gob await-any   # Returns when first job finishes
gob await-any   # Returns when second job finishes
gob await-any   # Returns when third job finishes
```

Use for: linting + typechecking, running tests across packages, independent build steps.

### Job Monitoring

**Status:**
- `gob list` - List jobs with IDs and status

**Output:**
- `gob await <job_id>` - Wait for completion, stream output (preferred)

**Control:**
- `gob stop <job_id>` - Graceful stop
- `gob stop --force <job_id>` - Force kill
- `gob restart <job_id>` - Stop + start
- `gob cleanup` - Remove stopped jobs

### Examples

Good:
  gob add -- make test
  gob await <job_id>
  gob add -- npm run dev

Bad:
  make test                 # Missing gob prefix
  npm run dev &             # Never use & - use gob add
  gob add npm run --flag    # Missing -- before flags

Instructions for Crush (AI assistant)

<shell_commands>
ALWAYS use `gob add` to run shell commands through the Bash tool.

- `gob add -- <cmd>` - Starts command, returns job ID immediately
  - IMPORTANT: Always use `--` before the command
- `gob await <job_id>` - Wait for job to finish, stream output, return exit code
</shell_commands>

<sequential_execution>
For commands that must complete before proceeding:

gob add -- make build

Then immediately:

gob await <job_id>

Use for: builds, installs, any command where you need the result.
</sequential_execution>

<parallel_execution>
For independent commands, start all jobs first:

gob add -- npm run lint
gob add -- npm run typecheck
gob add -- npm test

Then collect results using either:

- `gob await <job_id>` - Wait for a specific job by ID
- `gob await-any` - Wait for whichever job finishes first

Example with await-any:

gob await-any   # Returns when first job finishes
gob await-any   # Returns when second job finishes
gob await-any   # Returns when third job finishes

Use for: linting + typechecking, running tests across packages, independent build steps.
</parallel_execution>

<job_monitoring>
**Status:**
- `gob list` - List jobs with IDs and status

**Output:**
- `gob await <job_id>` - Wait for completion, stream output (preferred)

**Control:**
- `gob stop <job_id>` - Graceful stop
- `gob stop --force <job_id>` - Force kill
- `gob restart <job_id>` - Stop + start
- `gob cleanup` - Remove stopped jobs
</job_monitoring>

<auto_background_handling>
The Bash tool automatically backgrounds commands that exceed 1 minute.

When this happens, IGNORE the shell ID returned by the Bash tool. Instead:

1. Use `gob await <job_id>` to wait for completion again
2. Do NOT use Crush's job_output or job_kill tools
</auto_background_handling>

<examples>
Good:
  gob add -- make test
  gob await V3x
  gob add -- npm run dev
  gob add -- timeout 30 make build

Bad:
  make test                 # Missing gob prefix
  gob run make test         # Don't use run, use add + await
  npm run dev &             # Never use & - use gob add
  gob add npm run --flag    # Missing -- before flags
</examples>

Interactive TUI

Launch a full-screen terminal interface for managing jobs:

gob tui

Layout

The TUI has three panels:

• Panel 1 (Jobs): List of all jobs with status (● running, ○ stopped)
• Panel 2 (stdout): Standard output of selected job (80% height)
• Panel 3 (stderr): Standard error of selected job (20% height)

Key Bindings

Press ? in the TUI to see all keyboard shortcuts.

CLI Reference

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

Command	Description
run <cmd>	Run command, wait for completion (reuses stopped jobs)
add <cmd>	Start background job (use -- before flags: add -- cmd --flag)
await <id>	Wait for job, stream output, show summary
await-any	Wait for any job to complete (--timeout)
await-all	Wait for all jobs to complete (--timeout)
list	List jobs (--all for all directories)
stdout <id>	View stdout (--follow for real-time)
stderr <id>	View stderr (--follow for real-time)
logs	Follow all output for current directory
stop <id>	Stop job (--force for SIGKILL)
start <id>	Start stopped job
restart <id>	Stop + start job
signal <id> <sig>	Send signal (HUP, USR1, etc.)
remove <id>	Remove stopped job
cleanup	Remove all stopped jobs
nuke	Stop all, remove all, shutdown daemon
tui	Launch interactive TUI

Contributing

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

Star History