Background Tasks in Claude Code: Run Claude While You Work
Use 'claude --headless --print' with nohup or tmux to run Claude Code tasks in the background. Pipe output to a log file, use --output-format json for machine-readable results, and combine with git worktrees to avoid conflicts with your foreground session.
Claude Code's headless mode makes it a scriptable background worker. With '--headless' and '--print', Claude executes a task, writes the result to stdout, and exits — no interactive session, no UI. Wrap this in a shell script and you can queue up work while you focus on something else.
The most common pattern is running a background Claude task in a separate git worktree so it has its own working directory and does not touch your checked-out files. Create a worktree with 'git worktree add ../myproject-bg feature/bg-task', then run Claude in that directory. Your main session is unaffected.
For longer tasks (writing a large feature, running a full test suite with fixes, or processing many files), use tmux or a named pipe to keep the process running after you disconnect. The '--output-format json' flag gives you structured output you can parse with jq to extract specific fields.
Claude Code also supports the '--resume' flag to continue a previous session by ID. List sessions with 'claude sessions list', then resume any one with 'claude --resume <session-id>'. This lets you pause a long background task and pick it up later without losing context.
Examples
# Run Claude in background, log output
nohup claude --headless --print \
"Audit all TypeScript files in src/ for unused imports and fix them. Commit the changes." \
> ~/.claude/bg-task-$(date +%Y%m%d-%H%M%S).log 2>&1 &
echo "Background task PID: $!"
# Check progress:
tail -f ~/.claude/bg-task-*.log#!/bin/bash
# bg-task.sh — run a Claude task in an isolated worktree
REPO_ROOT=$(git rev-parse --show-toplevel)
BRANCH="claude/bg-$(date +%Y%m%d-%H%M%S)"
WORKTREE="${REPO_ROOT}/../$(basename $REPO_ROOT)-bg"
TASK="$1"
# Create a fresh branch and worktree
git worktree add "$WORKTREE" -b "$BRANCH"
# Run Claude in the worktree
cd "$WORKTREE" && claude --headless --print "$TASK" \
> ~/.claude/worktree-task.log 2>&1
echo "Done. Branch: $BRANCH | Worktree: $WORKTREE"
echo "Review with: git -C $WORKTREE log --oneline -5"# Get structured output from a background task
RESULT=$(claude --headless --print --output-format json \
"List all TODO comments in src/ with file name and line number. Return as JSON array.")
# Parse with jq
echo "$RESULT" | jq '.result' > todos.json
echo "Found $(jq length todos.json) TODOs"Tips
- →Always use git worktrees for background tasks that make file changes — prevents conflicts with your interactive session.
- →Use tmux new-session -d -s claude-bg to keep background tasks alive after terminal close.
- →Set ANTHROPIC_API_KEY in your shell profile so background scripts don't need it hardcoded.
- →The '--max-turns 50' flag caps how many back-and-forth steps Claude takes — useful to prevent runaway tasks.
- →Use 'ps aux | grep claude' to see running background Claude processes; 'kill <PID>' to stop one.
FAQ
Can background Claude tasks access MCP servers?+
Yes. Headless Claude Code loads your settings.json and connects to all configured MCP servers just like an interactive session. Ensure required environment variables are set in the script or shell profile.
How do I prevent a background task from making dangerous changes?+
Use '--permission-prompt-mode none' combined with a restrictive permissions config that disallows deletions and force pushes. Or run in a git worktree on a feature branch — all changes are isolated and you can review them with 'git diff main' before merging.
Is there a way to run multiple background tasks in parallel?+
Yes — see the parallel-agents guide. Each parallel agent runs in its own worktree and process. You can launch multiple 'nohup claude ...' commands pointing to different worktrees simultaneously.