Claude Code Async Agents: Revolutionary Background Processing for Parallel AI Development

Discover Claude Code's async agents feature enabling true parallel development workflows. Learn how background agents transform coding efficiency with fire-and-forget task execution, automatic PR creation, and seamless multi-repo orchestration.

ClaudeCode Guide Team
async agentsbackground processingparallel developmentautonomous codingweb versionClaude Agent SDKworkflow automation

TL;DR

Claude Code's async agents feature (December 2025 update) revolutionizes AI-assisted development with true parallel execution:

  • Background Agents: Press Ctrl+B to background running agents, continue with other tasks while they complete
  • Fire-and-Forget Execution: Delegate tasks that run autonomously on cloud infrastructure and file PRs when complete
  • Web Version: Spin up multiple coding tasks across different repos, all running in parallel from one interface
  • Task Monitoring: Use /tasks command to view all running background processes with their IDs and status
  • Automatic Wake-up: Completed background agents automatically wake your main agent with results
  • Claude Agent SDK: Build custom async agents with Python/TypeScript using async/await patterns

Perfect for: Long-running refactorings, multi-repo projects, parallel feature development, and overnight automation tasks.

The Evolution from Turn-Based to Parallel Development

Traditional AI Coding: The Sequential Bottleneck

Without Async Agents (Sequential):

9:00 AM - You: "Refactor authentication system"
         Claude: [30 minutes working...]
9:30 AM - Claude: Done! Review the changes.

9:35 AM - You: "Now update the API documentation"
         Claude: [20 minutes working...]
9:55 AM - Claude: Done! Review the changes.

10:00 AM - You: "Now migrate the database schema"
          Claude: [40 minutes working...]
10:40 AM - Claude: Done!

Total: 1 hour 40 minutes of sequential work
You're blocked during each task, can't multitask

With Async Agents (Parallel):

With Async Agents (Parallel):

9:00 AM - You: "Refactor authentication system"
         Claude: [starts working...]
         [30 seconds later]
         You: Ctrl+B (background the agent)

9:01 AM - You: "Update API documentation" (new task)
         Claude: [starts working on docs...]
         [20 seconds later]
         You: Ctrl+B (background again)

9:02 AM - You: "Migrate database schema" (another task)
         Claude: [starts working on migration...]
         You: Keep working on other things

9:30 AM - [Background Agent 1] ✓ Auth refactoring complete!
          Main agent wakes up with results
9:55 AM - [Background Agent 2] ✓ Docs updated!
          Main agent receives documentation
10:40 AM - [Background Agent 3] ✓ Migration done!
          Main agent gets migration files

Total: 3 tasks running in parallel
You delegated everything in 2 minutes, free to do other work
All tasks complete on their own timeline

Understanding Async Agents

What Are Async Agents?

Async agents are autonomous AI instances that execute independently from your main Claude Code session:

Traditional Subagents (Claude Code 2.0):
  Main Agent spawns subagents → Run in parallel → Complete → Report back
  ⚠ You must wait for orchestration to complete
  ⚠ Main session is occupied during execution

Async Agents (Latest Update):
  Main Agent starts task → Background with Ctrl+B → Continue other work
  ✓ Task runs independently in background
  ✓ Main session immediately available for new tasks
  ✓ Agent wakes you when complete

The Fire-and-Forget Paradigm

The async agents model introduces a revolutionary workflow:

Traditional Model:
  You → Request → AI Works → You Wait → Review → Next Task

Fire-and-Forget Model:
  You → Request → Ctrl+B → You Continue Working
           ↓
    [Background Agent Works]
           ↓
    [Completes & Creates PR]
           ↓
    [Notifies You When Ready]

Real-World Example:

# Morning: Delegate three major tasks
claude "Migrate entire codebase from JavaScript to TypeScript"
# Ctrl+B to background

claude "Implement comprehensive test suite for payment module"
# Ctrl+B to background

claude "Refactor database layer to use TypeORM"
# Ctrl+B to background

# Work on other things, meetings, coffee...

# Afternoon: Check completed tasks
/tasks

Output:
┌────────────────────────────────────────────────────────┐
│ Background Tasks                                       │
├────────────────────────────────────────────────────────┤
│ [1: TypeScript Migration]  ✓ Complete (3h 45m ago)   │
│    PR: github.com/yourrepo/pulls/123                  │
│                                                        │
│ [2: Test Suite]            ✓ Complete (1h 20m ago)   │
│    PR: github.com/yourrepo/pulls/124                  │
│                                                        │
│ [3: TypeORM Refactor]      ⏳ 85% (Est: 15 min)      │
│    Current: Updating repository patterns              │
└────────────────────────────────────────────────────────┘

Key Features of Async Agents

1. Background Processing with Ctrl+B

How It Works:

Step 1: Start a task
  claude "Large refactoring task that will take 30 minutes"

Step 2: Wait for agent to start actively processing
  [Agent is analyzing codebase...]
  [Agent started making changes...]

Step 3: Press Ctrl+B while agent is running
  ✓ Task immediately backgrounds
  ✓ Main Claude session freed
  ✓ Agent continues working independently

⚠ Important: Ctrl+B only works while agent is actively running
   Cannot background after agent has already completed

Example Workflow:

# Terminal Session 1
$ claude "Implement OAuth2 authentication for all microservices"

[Claude] Analyzing your microservices architecture...
[Claude] Found 8 services requiring OAuth2 integration
[Claude] Planning implementation strategy...
[Claude] Starting with auth-service...

# Press Ctrl+B now
[Backgrounded] Task ID: bg-auth-oauth-1234
[Main] Ready for new tasks

$ claude "Add comprehensive logging to frontend app"
# Continue working...

2. Web Version: Multi-Repo Parallel Execution

The web version of Claude Code (Pro/Max subscribers) enables unprecedented parallel development:

Claude Code on Web: Single Interface, Multiple Repos

Dashboard View:
┌──────────────────────────────────────────────────────┐
│ Active Projects                                      │
├──────────────────────────────────────────────────────┤
│ ▶ frontend-app (github.com/company/frontend)        │
│   Task: "Migrate to React 19 and new hooks"         │
│   Status: ████████████░░ 75% - 12 min remaining     │
│                                                       │
│ ▶ backend-api (github.com/company/backend)          │
│   Task: "Add GraphQL federation support"            │
│   Status: ██████░░░░░░░░ 40% - 28 min remaining     │
│                                                       │
│ ▶ mobile-app (github.com/company/mobile)            │
│   Task: "Implement offline-first architecture"      │
│   Status: ███████████░░░ 70% - 15 min remaining     │
│                                                       │
│ ▶ docs-site (github.com/company/docs)               │
│   Task: "Auto-generate API docs from OpenAPI"       │
│   Status: ████████████████ 100% ✓                   │
│   PR: github.com/company/docs/pulls/45               │
└──────────────────────────────────────────────────────┘

All running simultaneously on Anthropic's cloud infrastructure

Web Version Advantages:

  • No Local Resources: Tasks run on Anthropic's servers, not your machine
  • Persistent Sessions: Close browser, tasks continue running
  • Cross-Repo Coordination: Single interface manages multiple repositories
  • Automatic PR Creation: Each completed task files its own pull request
  • Progress Tracking: Visual dashboard shows all task statuses in real-time

3. Task Monitoring with /tasks Command

CLI Task Management:

# View all background tasks
$ /tasks

Output:
Active Background Tasks:
  bg-1234: TypeScript migration (Running, 45% complete)
  bg-5678: Test suite implementation (Running, 80% complete)
  bg-9012: Database refactoring (Queued, starts in 5 min)

Completed Tasks (Last 24h):
  bg-3456: API documentation update ✓ (2h ago)
  bg-7890: Security vulnerability fixes ✓ (5h ago)

# View specific task details
$ /tasks bg-1234

Task: TypeScript migration
Status: Running (45% complete)
Started: 2025-12-15 09:23:14
Estimated completion: 11:45:00
Files modified: 127/283
Current operation: Converting React components in src/features/

Recent activity:
  09:45 - Completed utils/ directory (23 files)
  10:12 - Completed components/ directory (45 files)
  10:38 - Processing features/ directory (in progress)

# Stop a background task
$ /tasks stop bg-1234
Task bg-1234 stopped. Files saved, partial progress preserved.

# Resume a stopped task
$ /tasks resume bg-1234
Task bg-1234 resumed from last checkpoint.

4. Automatic Agent Wake-Up

Smart Notifications:

Scenario: You're working on a new feature when background agent completes

[You're actively coding...]

[Background Agent: Auth Refactoring] ✓ Complete!

[Main Agent] 🔔 Background task completed: Auth Refactoring
             Would you like me to summarize the changes?

You: Yes

[Main Agent] Summary of background task bg-1234:
  - Refactored 23 authentication-related files
  - Migrated from JWT to OAuth2
  - Updated all 8 microservices
  - Added comprehensive tests (94% coverage)
  - Created PR: github.com/yourrepo/pulls/156

  Key changes:
    • src/auth/strategies/oauth2.ts (new)
    • src/auth/middleware/verify.ts (refactored)
    • config/auth.config.ts (updated)

  All tests passing ✓
  Ready for review and merge

Claude Agent SDK: Building Custom Async Agents

Python Async Patterns

The Claude Agent SDK uses native async/await for building custom agents:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def run_parallel_analysis():
    """
    Run multiple code analysis tasks in parallel
    """
    # Define multiple async tasks
    async def analyze_security():
        async for message in query(
            prompt="Analyze codebase for security vulnerabilities",
            options=ClaudeAgentOptions(
                allowed_tools=["Grep", "Read", "Bash"]
            )
        ):
            print(f"[Security] {message}")

    async def analyze_performance():
        async for message in query(
            prompt="Identify performance bottlenecks in hot paths",
            options=ClaudeAgentOptions(
                allowed_tools=["Grep", "Read", "Bash"]
            )
        ):
            print(f"[Performance] {message}")

    async def analyze_tests():
        async for message in query(
            prompt="Calculate test coverage and identify gaps",
            options=ClaudeAgentOptions(
                allowed_tools=["Bash", "Read"]
            )
        ):
            print(f"[Testing] {message}")

    # Run all three analyses in parallel
    await asyncio.gather(
        analyze_security(),
        analyze_performance(),
        analyze_tests()
    )

# Execute parallel analysis
asyncio.run(run_parallel_analysis())

TypeScript Async Patterns

import { query, ClaudeAgentOptions } from '@anthropic-ai/claude-agent-sdk';

async function parallelCodeReviews() {
  /**
   * Review multiple pull requests concurrently
   */
  const prReviews = [
    {
      pr: 123,
      prompt: "Review PR #123: Add authentication system"
    },
    {
      pr: 124,
      prompt: "Review PR #124: Implement caching layer"
    },
    {
      pr: 125,
      prompt: "Review PR #125: Refactor database queries"
    }
  ];

  // Create parallel review tasks
  const reviewPromises = prReviews.map(async ({ pr, prompt }) => {
    const messages = [];

    for await (const message of query(prompt, {
      allowed_tools: ["Read", "Bash", "Grep"]
    })) {
      messages.push(message);
    }

    return {
      pr,
      review: messages.join('\n')
    };
  });

  // Wait for all reviews to complete
  const results = await Promise.all(reviewPromises);

  // Post reviews to PRs
  results.forEach(({ pr, review }) => {
    console.log(`\n=== Review for PR #${pr} ===\n${review}\n`);
  });
}

await parallelCodeReviews();

Advanced: Hierarchical Async Agents

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def build_full_stack_feature():
    """
    Orchestrate complex feature development with hierarchical agents
    """

    # Main orchestrator agent
    async def main_agent():
        print("[Main] Orchestrating full-stack feature development...")

        # Spawn parallel development streams
        await asyncio.gather(
            backend_development(),
            frontend_development(),
            infrastructure_setup()
        )

        print("[Main] All development streams complete!")

    # Backend development stream (spawns its own sub-agents)
    async def backend_development():
        async def api_layer():
            async for msg in query(
                "Implement REST API endpoints with validation",
                options=ClaudeAgentOptions(allowed_tools=["Write", "Edit"])
            ):
                print(f"[Backend:API] {msg}")

        async def database_layer():
            async for msg in query(
                "Design database schema and migrations",
                options=ClaudeAgentOptions(allowed_tools=["Write", "Bash"])
            ):
                print(f"[Backend:DB] {msg}")

        async def tests():
            async for msg in query(
                "Write comprehensive backend tests",
                options=ClaudeAgentOptions(allowed_tools=["Write"])
            ):
                print(f"[Backend:Tests] {msg}")

        # Run backend sub-tasks in parallel
        await asyncio.gather(api_layer(), database_layer(), tests())

    # Frontend development stream
    async def frontend_development():
        async def components():
            async for msg in query(
                "Build React components with TypeScript",
                options=ClaudeAgentOptions(allowed_tools=["Write", "Edit"])
            ):
                print(f"[Frontend:Components] {msg}")

        async def state_management():
            async for msg in query(
                "Implement state management with Redux Toolkit",
                options=ClaudeAgentOptions(allowed_tools=["Write"])
            ):
                print(f"[Frontend:State] {msg}")

        await asyncio.gather(components(), state_management())

    # Infrastructure setup stream
    async def infrastructure_setup():
        async for msg in query(
            "Create Docker configs and CI/CD pipelines",
            options=ClaudeAgentOptions(allowed_tools=["Write", "Bash"])
        ):
            print(f"[Infrastructure] {msg}")

    # Run the main orchestrator
    await main_agent()

# Execute hierarchical async development
asyncio.run(build_full_stack_feature())

Real-World Use Cases

Use Case 1: Overnight Automation

End of Day Workflow:

4:45 PM - Before leaving office
  $ claude "Perform comprehensive security audit of entire codebase"
  [Ctrl+B to background]

  $ claude "Generate detailed API documentation from code comments"
  [Ctrl+B to background]

  $ claude "Analyze performance of all database queries and suggest optimizations"
  [Ctrl+B to background]

5:00 PM - Leave office, agents continue running on cloud

Next Morning, 9:00 AM - Check results
  $ /tasks

  All tasks complete! ✓

  [1] Security audit: Found 7 issues, created fixes, PR #234
  [2] API docs: Generated 450+ pages, PR #235
  [3] DB optimization: 23 slow queries optimized, PR #236

  Ready to review and merge

Use Case 2: Multi-Repo Synchronization

Scenario: Microservices architecture with shared API contract change

Main Repo: API Gateway
  Task: "Update API contract to version 2.0"
  [Background agent running...]

Dependent Repos (started simultaneously):
  ├─ User Service
  │  Task: "Update to API contract v2.0 when ready"
  │  Status: Waiting for contract definition...
  │
  ├─ Product Service
  │  Task: "Update to API contract v2.0 when ready"
  │  Status: Waiting for contract definition...
  │
  ├─ Order Service
  │  Task: "Update to API contract v2.0 when ready"
  │  Status: Waiting for contract definition...
  │
  └─ Notification Service
     Task: "Update to API contract v2.0 when ready"
     Status: Waiting for contract definition...

[API Gateway agent] ✓ Contract v2.0 defined and committed

[Automatic Cascade]
  All dependent service agents automatically detect new contract
  Begin updating their implementations in parallel

30 minutes later:
  ✓ All services updated to API contract v2.0
  ✓ 5 PRs created (1 gateway + 4 services)
  ✓ All integration tests passing
  ✓ Ready for synchronized deployment

Use Case 3: Long-Running Refactoring

Project: Migrate monolith to microservices

Phase 1: Extract User Service
  $ claude "Extract user management into standalone service:
    - Create new user-service repo
    - Move relevant code from monolith
    - Set up service infrastructure
    - Update monolith to call service via HTTP
    - Maintain backward compatibility
    - Comprehensive tests"

  [Ctrl+B - Expected duration: 2-3 hours]

Phase 2: Extract Product Service
  $ claude "Extract product catalog into standalone service:
    [similar detailed instructions]"

  [Ctrl+B - Expected duration: 2-3 hours]

Both extractions running in parallel
Monolith gradually decomposed without blocking your workflow

Use Case 4: Parallel Feature Development

Sprint Planning: 5 features to implement

Traditional Approach (Sequential):
  Feature 1: 1 day
  Feature 2: 1 day
  Feature 3: 1 day
  Feature 4: 1 day
  Feature 5: 1 day
  Total: 5 days

With Async Agents (Parallel):
  Monday 9 AM: Delegate all 5 features
    $ claude "Feature 1: User profile editing"
    [Ctrl+B]

    $ claude "Feature 2: Advanced search filters"
    [Ctrl+B]

    $ claude "Feature 3: Email notification system"
    [Ctrl+B]

    $ claude "Feature 4: Data export functionality"
    [Ctrl+B]

    $ claude "Feature 5: Admin analytics dashboard"
    [Ctrl+B]

  Tuesday 9 AM: All features complete
    5 PRs ready for review
    Total: 1 day (5x faster)

  Rest of sprint: Code review, refinement, testing, deployment

Best Practices for Async Agents

1. Clear Task Definition

✗ Poor Task Definition:
  "Fix the bugs and improve performance"
  → Too vague, agent might go in wrong direction

✓ Good Task Definition:
  "Identify and fix authentication timeout bugs in src/auth/
   Focus on JWT token expiration handling
   Ensure session persistence across page reloads
   Add error recovery for network failures
   Target: Reduce auth errors by 90%"
  → Specific, measurable, scoped

2. Appropriate Task Sizing

Too Small (Don't Background):
  ✗ "Add a console.log statement"
  ✗ "Fix typo in README"
  → Just do these immediately

Perfect for Backgrounding:
  ✓ "Refactor entire authentication system" (1-3 hours)
  ✓ "Implement comprehensive test suite" (2-4 hours)
  ✓ "Migrate database to new ORM" (3-5 hours)
  → Long-running, can proceed independently

Too Large (Break Down):
  ⚠ "Rebuild entire application from scratch"
  → Break into phases, background each phase

3. Dependency Management

✓ Independent Tasks (Perfect for Parallel):
  - Service A: "Add caching layer"
  - Service B: "Implement logging"
  - Service C: "Add metrics collection"
  → No dependencies, run all in parallel

✗ Sequential Dependencies (Coordinate):
  - Task 1: "Design database schema" [Run first]
  - Task 2: "Generate migrations from schema" [Wait for Task 1]
  - Task 3: "Seed database with test data" [Wait for Task 2]
  → Must run sequentially, don't background all at once

✓ Partial Dependencies (Hybrid):
  - Phase 1: "Design API contract" [Run first]
  - Phase 2 (parallel after Phase 1):
    • "Implement backend API"
    • "Generate frontend client"
    • "Create API documentation"
    • "Write integration tests"

4. Resource Management

Free Tier Limits:
  - 1 background agent at a time
  - Sequential processing of backgrounded tasks

Pro Plan Limits:
  - 3 concurrent background agents
  - Suitable for small team workflows

Max Plan Limits:
  - 8 concurrent background agents
  - Ideal for large projects and multi-repo work

Enterprise:
  - Custom limits (16-32+ concurrent agents)
  - Dedicated infrastructure for team usage

Monitor your usage:
  $ claude stats

  Async Agent Usage (Last 7 days):
    Total tasks backgrounded: 47
    Currently running: 3/8 slots used
    Average task duration: 1h 23m
    Completed successfully: 44 (94%)
    Failed: 3 (6%)

5. Error Handling and Recovery

Monitor for Failures:
  $ /tasks

  bg-1234: TypeScript migration ❌ Failed (2h ago)

  $ /tasks bg-1234 --logs

  Error: Type conflicts in src/utils/validators.ts
  Line 45: Cannot assign type 'string' to type 'number'
  Agent attempted fixes but could not resolve
  Requires manual intervention

Recovery Strategies:

  Option 1: Resume with guidance
    $ claude "Continue task bg-1234, for the type error:
      • Change parameter type from number to string
      • Update all call sites accordingly"

  Option 2: Partial use
    $ /tasks bg-1234 --extract-completed
    → Saves successfully migrated files
    → Creates partial PR for review
    → You manually fix remaining issues

  Option 3: Restart with refinement
    $ /tasks stop bg-1234
    $ claude "TypeScript migration with explicit type rules:
      [refined instructions based on failure]"

Comparing Async Agents with Other Features

Async Agents vs. Regular Subagents

Regular Subagents (Claude Code 2.0):
  Purpose: Parallel execution within single task
  Control: Main agent orchestrates and waits
  Duration: Minutes to hours
  Use Case: Full-stack feature with backend+frontend+tests
  Example: "Build checkout system" → spawns 4 subagents

  Timeline:
    [Main Agent] Orchestrating...
    ├─ [Subagent 1] Backend API (30 min)
    ├─ [Subagent 2] Frontend UI (40 min)
    ├─ [Subagent 3] Tests (25 min)
    └─ [Subagent 4] Docs (15 min)
    [Main Agent] Integration complete (40 min total)
    → You wait for orchestration to finish

Async Agents (Latest):
  Purpose: Independent background execution
  Control: Fire-and-forget, agent works autonomously
  Duration: Hours to overnight
  Use Case: Long refactoring you can review later
  Example: "Migrate to TypeScript" → Ctrl+B → forget

  Timeline:
    [You] Start task, Ctrl+B to background (10 seconds)
    [You] Continue other work, meetings, lunch, etc.
    [Background Agent] Working independently (3 hours)
    [Background Agent] ✓ Complete, creates PR
    [You] Review PR when convenient
    → Completely non-blocking

Async Agents vs. Traditional CI/CD

Traditional CI/CD:
  Trigger: Git push
  Purpose: Test, build, deploy
  Scope: Fixed pipeline steps
  Limitation: No intelligence, just scripted steps

Async Agents:
  Trigger: Natural language request
  Purpose: Intelligent code generation/refactoring
  Scope: Open-ended development tasks
  Advantage: AI decides implementation strategy

Complementary Usage:
  1. Async Agent: "Implement feature X"
  2. Agent creates PR
  3. CI/CD: Runs tests, builds, deploys
  4. Both working together: AI codes, pipeline validates

Advanced Techniques

Chained Async Agents

# Agent 1: Design phase
$ claude "Analyze requirements and design system architecture for
  real-time collaborative editing feature. Output detailed technical spec."

# Wait for completion, review spec

# Agent 2-5: Implementation phase (parallel)
$ claude "Implement WebSocket server based on spec from bg-1234"
[Ctrl+B]

$ claude "Implement frontend editor component based on spec from bg-1234"
[Ctrl+B]

$ claude "Implement CRDT conflict resolution based on spec from bg-1234"
[Ctrl+B]

$ claude "Implement persistence layer based on spec from bg-1234"
[Ctrl+B]

# All agents reference the design spec from first agent
# Implementation proceeds in parallel from shared specification

Multi-Stage Workflows

# Automated multi-stage development workflow
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def multi_stage_workflow():
    """
    Stage 1: Analysis
    Stage 2: Implementation (parallel)
    Stage 3: Testing & Validation
    """

    # Stage 1: Analysis (sequential)
    print("Stage 1: Analyzing codebase...")
    analysis_results = []
    async for msg in query(
        "Analyze codebase and identify areas needing refactoring",
        options=ClaudeAgentOptions(allowed_tools=["Grep", "Read"])
    ):
        analysis_results.append(msg)

    # Stage 2: Implementation (parallel based on analysis)
    print("Stage 2: Implementing refactorings in parallel...")

    refactoring_tasks = [
        query(
            f"Refactor {area} as identified in analysis",
            options=ClaudeAgentOptions(allowed_tools=["Edit", "Write"])
        )
        for area in ["auth", "database", "api", "frontend"]
    ]

    # Wait for all refactorings to complete
    await asyncio.gather(*[
        asyncio.create_task(consume_stream(task))
        for task in refactoring_tasks
    ])

    # Stage 3: Testing & Validation (sequential, depends on Stage 2)
    print("Stage 3: Running comprehensive tests...")
    async for msg in query(
        "Run all tests and validate refactoring success",
        options=ClaudeAgentOptions(allowed_tools=["Bash"])
    ):
        print(f"[Testing] {msg}")

async def consume_stream(stream):
    """Helper to consume async stream"""
    async for msg in stream:
        print(msg)

asyncio.run(multi_stage_workflow())

Notification Integration

# macOS notification when background task completes
$ claude config set notifications.enabled true
$ claude config set notifications.sound true

# Email notification for long tasks
$ claude config set notifications.email "dev@company.com"
$ claude config set notifications.email-threshold 60  # minutes

# Slack integration
$ claude config set notifications.slack-webhook "https://hooks.slack.com/..."
$ claude config set notifications.slack-channel "#dev-updates"

# Example: Long task with notifications
$ claude "Complete security audit and penetration testing"
[Ctrl+B]

# 3 hours later...
# Email arrives: "Claude Code: Security audit complete (bg-5678)"
# Slack message: "@you Security audit finished! Found 5 issues. PR #789"
# macOS notification: 🔔 "Background task complete"

Troubleshooting

Issue 1: Ctrl+B Not Working

Problem: Pressed Ctrl+B but task didn't background

Causes:
  ✗ Agent hasn't started active processing yet
  ✗ Agent already completed
  ✗ Task is too quick to background

Solution:
  ✓ Wait for agent to show "Working..." status
  ✓ Press Ctrl+B during active processing phase
  ✓ For very quick tasks, backgrounding isn't necessary

Issue 2: Background Agent Stalled

Problem: Background task stuck at same percentage for hours

Diagnosis:
  $ /tasks bg-1234 --logs

  [12:34] Processing file src/components/UserProfile.tsx
  [12:35] Analyzing dependencies...
  [12:36] [Loop detected] Same analysis repeating

Solution:
  $ /tasks stop bg-1234
  $ claude "Resume task bg-1234 with explicit instruction:
    Skip dependency analysis for UserProfile component
    Use direct implementation approach instead"

Issue 3: Merge Conflicts from Parallel Agents

Problem: Multiple background agents modified same file

Example:
  bg-1234: Refactoring auth system → modified src/config.ts
  bg-5678: Adding logging → modified src/config.ts

  Conflict in src/config.ts

Resolution:
  $ /tasks resolve-conflict bg-1234 bg-5678

  [Auto-merge attempt...]
  ✓ Successfully merged: Non-overlapping changes combined

  OR (if auto-merge fails):

  [Manual resolution required]
  $ git diff bg-1234.patch bg-5678.patch
  [Review conflicts manually]
  $ git apply bg-1234.patch
  $ git apply bg-5678.patch --3way
  [Resolve in editor]

Issue 4: Web Version Not Syncing

Problem: Web dashboard not showing latest status

Quick Fixes:
  1. Hard refresh browser: Cmd/Ctrl + Shift + R
  2. Check connection status in top-right indicator
  3. Verify repository permissions haven't changed
  4. Clear browser cache and re-authenticate

If persistent:
  1. Check Claude Code status page: status.anthropic.com
  2. Verify GitHub webhooks are active
  3. Re-authorize Claude Code in GitHub settings
  4. Contact support with session ID from /tasks --debug

Future Roadmap

Anthropic has announced upcoming async agent enhancements:

Q1 2026:
  - Agent collaboration: Background agents can spawn their own sub-agents
  - Smart scheduling: AI determines optimal backgrounding strategy
  - Team dashboards: Share background task views with team members

Q2 2026:
  - Cross-project agents: Single agent working across multiple repos
  - Persistent agents: Long-running agents that work over days/weeks
  - Agent marketplace: Share and reuse agent configurations

Q3 2026:
  - Voice control: "Hey Claude, background this task"
  - Mobile app: Monitor background tasks from phone
  - Advanced analytics: Productivity metrics and time savings reports

Conclusion

Claude Code's async agents feature represents a paradigm shift in AI-assisted development:

Key Benefits:

  • ✓ True Parallel Development: Multiple independent tasks simultaneously
  • ✓ Zero Blocking Time: Continue working while agents process in background
  • ✓ Overnight Automation: Delegate long tasks that complete while you sleep
  • ✓ Multi-Repo Orchestration: Manage changes across entire microservices ecosystem
  • ✓ Automatic PR Creation: Agents file pull requests when work is complete

When to Use Async Agents:

  • Long-running refactorings (>30 minutes)
  • Multi-repo synchronization tasks
  • Overnight automation workflows
  • Parallel feature development
  • Non-urgent but important tasks

Best Practices Recap:

  1. Define clear, specific task requirements
  2. Size tasks appropriately (1-4 hours ideal)
  3. Manage dependencies between parallel tasks
  4. Monitor with /tasks command
  5. Set up notifications for long-running agents

Getting Started:

# CLI Version
$ claude "Your long-running task here"
# When agent starts processing, press Ctrl+B

# Check status
$ /tasks

# Web Version (Pro/Max subscribers)
# Visit code.anthropic.com
# Start multiple tasks across different repos
# Monitor from unified dashboard

The async agents feature transforms Claude Code from a powerful assistant into a tireless development partner that works around the clock, enabling unprecedented productivity gains for modern software teams.

Keywords: claude code async agents, background processing, parallel AI development, fire-and-forget coding, autonomous agents, multi-repo development, overnight automation, Claude Agent SDK, async/await patterns, web version parallel execution, task orchestration, development productivity

Sources: