background-tasks

erikpr1994 的头像作者 erikpr1994

Efficient handling of long-running commands. Use when running tests, builds, or any command that takes more than a few seconds. Prevents token waste from polling.

📖 中文导读:Efficient handling of long-running commands. Use when running tests, builds, or any command that takes more than a few seconds. Prevents token waste from polling. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: background-tasks description: "Efficient handling of long-running commands. Use when running tests, builds, or any command that takes more than a few seconds. Prevents token waste from polling."

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