Originally published at claudeguide.io/claude-code-background-tasks

Background Tasks in Claude Code: The Complete Playbook

Claude Code runs background tasks through 3 mechanisms: the --print flag for headless CLI execution, the Agent SDK's run_in_background parameter for non-blocking agent calls, and worktree isolation for parallel Claude instances working simultaneously in 2026. Understanding when to use each pattern eliminates the most common productivity bottleneck: waiting for one task to finish before starting the next.

---

The Problem: Sequential Work in an Async World

By default, Claude Code is interactive — you ask, it responds, you ask again. This works well for focused single-task sessions but creates a bottleneck when you need multiple independent things done:

# Sequential (slow)
1. Claude Code writes the API endpoint (5 min)
2. Wait for completion
3. Claude Code writes the tests (3 min)
4. Wait for completion
5. Claude Code writes the documentation (2 min)
Total: 10 min

# Parallel (fast)
1. Claude Code instance A writes API endpoint
   Claude Code instance B writes tests        } simultaneously
   Claude Code instance C writes docs
Total: ~5 min

---

Method 1: Headless CLI with --print

The simplest background task pattern: run Claude Code non-interactively with --print and & to background the process.

bash
# Run in background, capture output to file
claude --print --project /path/to/project \
  "Write comprehensive tests for the UserService class. Save to tests/user-service.test.ts" \


[→ Get the Agent SDK Cookbook — $49](https://shoutfirst.gumroad.com/l/ogxhmy?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-code-background-tasks)

*30-day money-back guarantee. Instant download.*