How to run Claude Code as a background agent — fire and forget workflows

Most developers use Claude Code interactively: type a prompt, watch it work, review the output. But there's a more powerful pattern that most people haven't tried: running Claude Code as a background agent that processes tasks while you focus on something else.

This is the "fire and forget" workflow — and once you've used it, you won't go back.

The problem with interactive-only Claude Code

Interactive sessions are great for exploration. But they have a cost:

• You're blocked while Claude works
• Long tasks interrupt your flow state
• Rate limits hit you mid-session when you need results
• Context gets bloated from back-and-forth conversation

For tasks like "refactor this entire module", "write tests for all these files", or "migrate this codebase to TypeScript", you don't need to watch every step. You need the result.

The background agent pattern

Here's the core idea: give Claude a well-defined task with clear success criteria, then let it run while you work on something else.

Step 1: Write a task file

Instead of typing prompts, write a TASK.md in your project root:

# Task: Add error handling to all API routes

## What to do
- Read every file in src/routes/
- Find all async route handlers that don't have try/catch
- Add proper error handling with next(err) pattern
- Preserve existing functionality exactly

## Success criteria
- Every route handler has try/catch
- Errors pass to next() for global handler
- No functional changes to happy path
- All existing tests still pass

## Do NOT
- Change route logic
- Modify response formats
- Touch test files

Step 2: Launch as background process

# Run Claude Code with the task file as context
nohup claude --print < TASK.md > claude-output.log 2>&1 &
echo $! > claude.pid
echo "Claude running as PID $(cat claude.pid)"

The --print flag runs Claude non-interactively. nohup keeps it running if your terminal closes. Output goes to a log file you can check anytime.

Step 3: Check progress without interrupting

# See what Claude has done so far
tail -f claude-output.log

# Check if it's still running
cat claude.pid | xargs ps -p

# See what files changed
git diff --stat

Step 4: Review and commit

# When done (process exits)
git diff --name-only  # see changed files
git diff src/routes/  # review changes
npm test             # verify tests pass
git add -p           # selective staging

A real workflow: test coverage sprint

Here's how I use this pattern to go from 40% to 80% test coverage without dedicating a full afternoon to it:

Morning (5 minutes):

# Generate coverage report
npm test -- --coverage > coverage-report.txt

# Write the task
cat > TASK.md << 'EOF'
# Task: Write tests for uncovered files

Read coverage-report.txt to find files under 50% coverage.
For each file, write a test file in the corresponding __tests__ directory.
Use Jest. Match existing test patterns from other test files.
Focus on the 5 files with lowest coverage first.
EOF

# Launch
nohup claude --print < TASK.md > test-gen.log 2>&1 &
echo "Running as $!"

Go to standup, do code reviews, etc.

2 hours later:

tail test-gen.log      # see what happened
npm test -- --coverage  # new coverage numbers
git diff --stat         # what changed

Typically: 8-12 new test files, coverage jumps 20-30 percentage points.

The multi-agent version

Once you're comfortable with one background agent, you can run several in parallel on different tasks:

# Terminal multiplexer approach
tmux new-session -d -s "agent1" "claude --print < tasks/task1.md > logs/agent1.log 2>&1"
tmux new-session -d -s "agent2" "claude --print < tasks/task2.md > logs/agent2.log 2>&1"
tmux new-session -d -s "agent3" "claude --print < tasks/task3.md > logs/agent3.log 2>&1"

# Monitor all three
watch -n 5 'echo "=Agent1==" && tail -3 logs/agent1.log && echo "=Agent2==" && tail -3 logs/agent2.log && echo "=Agent3==" && tail -3 logs/agent3.log'

Three agents = three branches = three features progressing while you do something else.

The catch: three parallel Claude Code sessions means 3x token consumption. Each agent burns through your rate limit independently. If you're on Claude.ai's $20/month subscription, you'll hit the limit fast.

This is where a token-efficient API proxy helps. I use SimplyLouie ($2/month) which proxies to Anthropic's API — no per-agent session limits, just API token costs. For multi-agent workflows, this setup is dramatically more cost-effective than multiple subscriptions.

Task file patterns that work well

The "find and fix" pattern:

# Find all TODO comments and implement them
- Read every .ts file
- Find lines with TODO:
- Implement the TODO if it's < 20 lines of work
- Skip complex TODOs (mark with SKIPPED:)
- Run tests after each change to verify nothing breaks

The "documentation sprint" pattern:

# Add JSDoc to all exported functions
- Find all functions with 'export' keyword
- Add JSDoc comments matching TypeDoc format
- Include @param, @returns, @example
- Preserve all existing comments

The "type safety" pattern:

# Fix TypeScript errors
- Run tsc --noEmit, save output to errors.txt
- Fix errors starting with most frequent error type
- Don't use 'any' as a fix
- Run tsc after each file to verify

When NOT to use background agents

• Exploratory tasks where you need to guide the direction
• Anything touching production databases
• Tasks that need judgment calls you can't pre-specify
• Small tasks under 10 minutes (overhead not worth it)

Background agents shine for well-defined, large-scope, low-risk tasks — exactly the kind of work that's tedious to do interactively.

The setup that makes this sustainable

For background agents to be worth it, you need:

1. A solid CLAUDE.md so Claude knows your codebase conventions
2. Good test coverage so you can verify output automatically
3. An API proxy that doesn't throttle background sessions

The CLAUDE.md is the most important. A background agent without context will produce generic code. A background agent with your CLAUDE.md will produce code that matches your patterns exactly.

---

Try this with a low-stakes task first — adding documentation or writing tests for existing functionality. Once you see it work, you'll find a dozen places to apply the pattern.