Background Tasks

Overview

Long-running commands (tests, builds, pushes) should run in background and be awaited efficiently.

The Iron Law: Use TaskOutput(block: true) to wait. NEVER poll with sleep && cat.

When to Use Background Execution

Command Type	Duration	Use Background?
E2E tests	2-10 min	YES
Full test suite	1-5 min	YES
Git push with hooks	30s-2 min	YES
Build/compile	30s-5 min	YES
Single unit test	< 30s	NO
Quick commands	< 10s	NO

Rule of thumb: If it might take > 30 seconds, run in background.

The Efficient Pattern

✅ CORRECT - Two tool calls, efficient:

1. Bash(command, run_in_background: true)
   → Returns: task_id (e.g., "abc123")

2. TaskOutput(task_id: "abc123", block: true, timeout: 300000)
   → Waits up to 5 min
   → Returns full output when complete

That's it. Two calls total.

The Anti-Pattern (NEVER DO THIS)

❌ WRONG - Wastes tokens polling empty output:

1. Bash(command, run_in_background: true) → task_id
2. Bash(sleep 60 && tail output)  ← empty, wasted tokens
3. Bash(cat output)               ← still empty, wasted
4. Bash(ps aux | grep process)    ← wasted
5. Bash(sleep 90 && cat output)   ← wasted again
6. TaskOutput(block: false)       ← still not done
7. Bash(tail -f output)           ← more waste
... repeat until done

Result: 6+ tool calls instead of 2

TaskOutput Parameters

TaskOutput(
  task_id: string,      // Required: ID from background Bash
  block: boolean,       // true = wait for completion (DEFAULT)
  timeout: number       // Max wait in ms (default: 30000)
)

Key insight: block: true is the DEFAULT. It waits efficiently without repeated calls.

Timeout Guidelines

Task Type	Timeout	Rationale
Single unit test file	60000 (1 min)	Fast feedback
Integration tests	120000 (2 min)	DB/API calls
E2E single spec	300000 (5 min)	Browser startup + test
E2E full suite	600000 (10 min)	Multiple specs
Git push with hooks	180000 (3 min)	Pre-push tests
Full build	300000 (5 min)	Compilation

Parallel Background Tasks

Start multiple, then wait for all:

// Start all in parallel (single message, multiple Bash calls)
Bash("pnpm test:unit", run_in_background: true)     // → task_a
Bash("pnpm test:e2e", run_in_background: true)      // → task_b
Bash("pnpm lint", run_in_background: true)          // → task_c

// Wait for each (can be in same message)
TaskOutput(task_id: "task_a", block: true, timeout: 120000)
TaskOutput(task_id: "task_b", block: true, timeout: 300000)
TaskOutput(task_id: "task_c", block: true, timeout: 60000)

When to Use Non-Blocking Check

Use block: false ONLY for quick status checks when you need to do other work:

// Check if still running (doesn't wait)
TaskOutput(task_id: "abc123", block: false, timeout: 1000)

// Returns immediately with:
// - Current output if still running
// - Full output if complete

Typical use case: You started a long task, need to inform the user, then want to check progress.

Common Scenarios

Running E2E Tests

// Start in background
Bash("pnpm test:e2e -- checkout.spec.ts", run_in_background: true)
// → task_id: "e2e_123"

// Wait for completion
TaskOutput(task_id: "e2e_123", block: true, timeout: 300000)
// → Returns test results when done

Git Push with Pre-Push Hooks

// Push (may run tests via hooks)
Bash("git push -u origin feature/my-branch", run_in_background: true)
// → task_id: "push_456"

// Wait for push + hooks to complete
TaskOutput(task_id: "push_456", block: true, timeout: 180000)
// → Returns push result

Full Test Suite

// Start full suite
Bash("pnpm test", run_in_background: true)
// → task_id: "test_789"

// Wait with appropriate timeout
TaskOutput(task_id: "test_789", block: true, timeout: 300000)
// → Returns all test results

Red Flags - STOP

You're doing it wrong if:

• Using sleep before checking output
• Using tail -f to monitor progress
• Using cat repeatedly on output file
• Using ps aux | grep to check if running
• Calling TaskOutput with block: false repeatedly
• More than 2 tool calls for a single background task

Integration

Reference this skill from:

• submit-pr - For git push with hooks
• testing-patterns - For E2E test execution
• verification - For running verification commands
• tdd - For test execution phases

Pairs with:

• dispatching-parallel-agents - For parallel task coordination
• testing-patterns - For test execution guidance