Managing Background Jobs with gob

Overview

gob (Background Job Manager) runs tasks asynchronously while keeping context free. Essential for builds, tests, dev servers, and any long-running commands.

When to use:

• User explicitly asks for "parallel" or "simultaneous" commands → use gob add for each
• Long-running command that would block context → use gob add
• Multiple independent commands to run at once → use gob add for each

Why gob over parallel Bash tool calls: gob provides job IDs, output capture, status monitoring, and proper process control. Parallel Bash calls just fire and forget.

CRITICAL: Parallel Command Requests

When user says "run X and Y in parallel" or "run two parallel builds":

# ✅ CORRECT: Use gob add for each command
gob add pnpm build
gob add pnpm build

# Then await results
gob await-any
gob await-any

# ❌ WRONG: Do NOT use parallel Bash tool calls
# Bash(pnpm build) + Bash(pnpm build) in same message

Why this matters: Parallel Bash tool calls work but provide no job management. gob gives you job IDs, status checks, output streaming, and the ability to stop/restart jobs.

Core Concepts

The Problem Without gob

# ❌ BLOCKS: Claude Code waits for this to finish
npm run build
npm test
npm run lint

# Total time: Sequential, slow, context locked

The Solution With gob

# ✅ DISPATCHES: Returns immediately with job IDs
gob add npm run build    # Job #1
gob add npm test         # Job #2
gob add npm run lint     # Job #3

# Continue working while jobs run...
# Then collect results when ready

Key insight: gob add starts a job and returns immediately. You never wait. You work. You collect results later.

Sequential Execution

Use sequential execution when:

• A command must complete before the next one starts
• Result of one command needed for the next
• Order matters
• Examples: build → test, compile → verify, database migrations → seed data

Pattern: Sequential with Await

# Dispatch first command
JOB_ID=$(gob add make build)

# Wait for it (blocks here, but only here)
gob await $JOB_ID

# If it passed, dispatch next
JOB_ID_2=$(gob add npm test)
gob await $JOB_ID_2

# Result known, proceed

Process

1. Dispatch: gob add <command> → returns job ID immediately
2. Await: gob await <job_id> → streams output, returns exit code
3. Check result: If exit code is 0, continue. If non-zero, handle error
4. Next command: Only run next command if previous succeeded

Key Points

• One await per command: Always explicitly wait for sequential commands
• Check exit codes: Know if a command succeeded or failed
• Error handling: Stop on first failure or continue gracefully
• Clear naming: Use descriptive job names in comments

Parallel Execution

Use parallel execution when:

• Commands are independent (don't depend on each other's output)
• Running them together is faster than sequential
• Examples: lint + typecheck, test suite 1 + test suite 2, API build + UI build

Pattern 1: Start All, Await All

Good when you have a few known parallel tasks:

# Dispatch all jobs
gob add npm run lint
gob add npm run typecheck
gob add npm test

# Collect results (order doesn't matter)
gob await-any
gob await-any
gob await-any

How it works:

1. gob add three times → all three start in parallel
2. gob await-any → waits for whichever finishes first, returns result
3. Call await-any three times total to wait for all three jobs

Pattern 2: Specific Job Await

Good when you need specific jobs' results:

# Dispatch parallel jobs
LINT_JOB=$(gob add npm run lint)
TYPE_JOB=$(gob add npm run typecheck)
TEST_JOB=$(gob add npm test)

# Wait for specific jobs
gob await $LINT_JOB
gob await $TYPE_JOB
gob await $TEST_JOB

# Check all passed before proceeding

Pattern 3: Parallel Build Steps

# Dispatch parallel compilation tasks
gob add npm run build:frontend
gob add npm run build:backend
gob add npm run build:types

# Wait for all to complete
gob await-any
gob await-any
gob await-any

# All complete, package everything
gob add npm run package

Key Points

• Independence: Jobs truly don't depend on each other
• Dispatch first: Start all jobs before awaiting any
• await-any: Call once per job when using this pattern
• gob list: Check job status anytime with gob list
• Latency: Parallel jobs reduce total time significantly

Common Patterns

Pattern: Long Test Run

# Start expensive test suite
TEST_JOB=$(gob add npm run test:integration)

# Implement feature or write docs
# (Tests run in background)

# Check if done:
gob list   # See status

# Wait for completion:
gob await $TEST_JOB

Job Management

View Job Status

gob list

Get Job Output

# Wait for job and stream output
gob await <job_id>

# Returns exit code (0 = success, non-zero = failure)

Stop a Job

# Graceful stop (allows cleanup)
gob stop <job_id>

# Force kill (immediate termination)
gob stop --force <job_id>

Restart a Job

# Stop and restart a specific job
gob restart <job_id>

Remove a Job

# Remove a stopped job from list
gob remove <job_id>

Real-Time Monitoring

# Watch jobs as they run
watch gob list

# Or check once
gob list

Best Practices

✅ DO

• Use gob add for all long-running commands (builds, tests, servers)
• Dispatch all parallel jobs before awaiting any (maximizes concurrency)
• Check exit codes after sequential operations
• Use descriptive comments to explain job purpose
• Clean up stopped jobs periodically with gob remove
• Monitor with gob list if uncertain about job status
• Use --prompt-only with CLI tools (smaller output)

❌ DON'T

• Don't use npm run build & - Use gob add npm run build instead
• Don't use command & - gob handles backgrounding
• Don't forget to await sequential commands - Result matters
• Don't mix bash backgrounding with gob - Creates confusion
• Don't await the same job twice - Job completes once
• Don't ignore exit codes - Errors need handling
• Don't let job list grow unbounded - Remove completed jobs

Conditional Parallel Execution

# Phase 1: Build must complete first
gob add npm run build
gob await-any

# Phase 2: Run quality checks in parallel (only if build succeeded)
gob add npm run lint
gob add npm run typecheck
gob add npm test

# Phase 3: Wait for all quality checks
gob await-any
gob await-any
gob await-any

# Phase 4: Package only if all checks pass
gob add npm run package