How to run background agents with Claude Code — fire and forget long tasks

One of the most underused patterns in Claude Code is running background agents for long-running tasks. Instead of blocking your session waiting for a 200-file scan or a full test suite, you can fire the task and keep working.

This is the pattern I use daily. Here's exactly how it works.

The problem: blocking sessions

Typical Claude Code session looks like this:

You: Scan all 347 files for deprecated API calls
Claude: [working...]
[you wait 8 minutes]
[Claude returns results]
You: Now fix the ones in /src/api/*
Claude: [working...]
[you wait 12 minutes]

You're blocked. You can't do anything else. If the session dies halfway through, you restart from zero.

The solution: background agents

The fire-and-forget pattern lets you spawn a task, detach from it, and work on something else while it runs.

# In your CLAUDE.md, define the background task pattern
cat >> CLAUDE.md << 'EOF'
## Background Task Pattern
For long-running scans, refactors, or analysis:
1. Write the task to tasks/pending/task-{timestamp}.md
2. Start the task with a clear success criterion
3. Write results to tasks/completed/task-{timestamp}.md
4. Alert when done via: echo "DONE: {task}" >> tasks/log.txt
EOF

Now you can do this:

You: Start a background scan of all files for deprecated fetch() calls. 
     Write results to tasks/completed/deprecated-fetch-scan.md.
     When done, write SCAN_COMPLETE to tasks/log.txt.
     I'll check back in 10 minutes.

Then you go work in a different Claude Code session while the first one runs.

Real-world use case: parallel feature development

Here's what this looks like for a real feature:

Session 1 (background):

Scan the entire codebase for all places that call UserService.getById(). 
Document each call site with: file, line, context, whether it handles null.
Write to tasks/completed/user-service-audit.md.

Session 2 (you, working on something else):

I'm implementing the new UserProfile component. Start with the UI shell.

10 minutes later:

The audit in tasks/completed/user-service-audit.md is done. 
I'm now switching to implement null-safety for the top 10 call sites.

You've parallelized work that used to be serial.

The task queue pattern

For projects with many pending improvements, a task queue keeps things organized:

mkdir -p tasks/pending tasks/in-progress tasks/completed

# Add tasks
echo "Audit: Find all N+1 queries in /src/db/*.js" > tasks/pending/db-audit.md
echo "Refactor: Split UserController into smaller controllers" > tasks/pending/controller-split.md
echo "Test: Write missing tests for PaymentService" > tasks/pending/payment-tests.md

In your Claude Code session:

Look at tasks/pending/. Pick the first task, move it to in-progress/, 
complete it, then move to completed/. Then pick the next pending task.

This is fully autonomous background processing.

Rate limits kill background agents

Here's the hard reality: long background tasks burn tokens fast. A full codebase scan across 500 files can easily hit Claude's rate limits mid-task.

When that happens:

• Your background agent stops
• Results are partial or missing
• You have to restart and re-read all the context

The fix most developers use: route Claude Code through a proxy endpoint that gives you a clean rate limit separate from your interactive sessions.

The approach:

# Set in your shell profile
export ANTHROPIC_BASE_URL=https://simplylouie.com/api

# Background agents use this endpoint
# Interactive sessions use the same endpoint
# Rate limits are pooled across your whole setup

At SimplyLouie the API endpoint is $2/month. I've been running background agents for months without hitting mid-task rate limits.

The checkpoint pattern for long tasks

For tasks that might run for 30+ minutes, add checkpoints:

Scan /src/api/*.js for security issues.

After every 20 files, write a checkpoint to tasks/checkpoints/security-scan-{n}.md
with: files processed so far, issues found so far, current status.

This way if the session ends, we can resume from the last checkpoint.

The checkpoint file contains everything needed to resume:

# Security Scan Checkpoint 3
Files processed: 60/180
Issues found: 12
- auth.js:45 - SQL injection risk
- user.js:123 - missing input validation
[... etc ...]
Next: Start from /src/api/payment.js

Multi-agent coordination

For large codebases, you can run multiple agents on different subsystems:

Agent 1: Scan /src/frontend/* for accessibility issues
Agent 2: Scan /src/api/* for missing error handling

Agent 3: Scan /src/db/* for slow queries

All three run in parallel. Each writes to a different results file. You review all three when you're ready.

This is 3x the speed — but also 3x the token burn. With a $20/month subscription this will eat your rate limit in a day. With the API proxy approach at $2/month, it's sustainable.

Summary

Background agents unlock a fundamentally different way to use Claude Code:

• Fire tasks and keep working on something else
• Task queues for systematic codebase improvement
• Checkpoints for resilience against session limits
• Parallel agents for large codebases

The bottleneck is rate limits. Once you solve that (API proxy, $2/month), the patterns above become your daily workflow.

All these examples work today with Claude Code + a CLAUDE.md file that defines the task patterns.

---

Using Claude Code for background tasks? I'd love to hear what patterns you're using in the comments.