--- name: gob-background-jobs description: Use when user requests "parallel" commands, running multiple builds/tests simultaneously, or long-running tasks. Use `gob add` instead of parallel Bash tool calls - gob provides job management, output capture, and proper process control. --- # 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": ```bash # ✅ 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` ```bash # ❌ 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` ```bash # ✅ 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 ```bash # 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 ` → returns job ID immediately 2. **Await**: `gob await ` → 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: ```bash # 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: ```bash # 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 ```bash # 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 ```bash # 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 ```bash gob list ``` ### Get Job Output ```bash # Wait for job and stream output gob await # Returns exit code (0 = success, non-zero = failure) ``` ### Stop a Job ```bash # Graceful stop (allows cleanup) gob stop # Force kill (immediate termination) gob stop --force ``` ### Restart a Job ```bash # Stop and restart a specific job gob restart ``` ### Remove a Job ```bash # Remove a stopped job from list gob remove ``` ### Real-Time Monitoring ```bash # 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 ```bash # 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 ```