Setting Up Background Tasks in Claude Code: Complete Configuration Guide

Claude Code runs long-running operations asynchronously through its built-in background task subsystem, allowing you to execute tests, builds, and deployments without blocking your interactive chat session.

Claude Code supports background tasks that let you run lengthy operations like test suites, Docker builds, or deployment pipelines while continuing your conversation. According to the luongnv89/claude-howto repository, this feature is implemented through an asynchronous task subsystem that assigns unique identifiers and manages execution via slash commands.

Understanding Asynchronous Execution

When you request a long-running operation, Claude Code spawns a background task, assigns a unique ID (e.g., bg-1234), and returns control to you immediately. The task runs in a separate worker process, enabling the conversation to continue while the operation executes. This architecture is documented in 09-advanced-features/README.md#background-tasks and claude_concepts_guide.md#background-tasks.

Managing the Task Lifecycle

The task subsystem provides slash commands for monitoring and controlling background work, as detailed in 09-advanced-features/README.md#managing-background-tasks.

Listing and Inspecting Tasks

Use /task list to view all active operations with their completion percentages and time estimates:

/task list
Active background tasks:
1. [bg-1234] Running tests (50% complete, 2 min remaining)
2. [bg-1235] Building Docker image (25% complete, 8 min remaining)

Check specific task status with /task status:

/task status bg-1234
Task bg-1234: Running tests
Status: In progress
Progress: 120/245 tests (49%)
Started: 2025-11-08 10:30:15
Estimated completion: 2025-11-08 10:34:22

Viewing Output and Cancelling Tasks

Stream live output using /task show:

/task show bg-1234
[Shows live output from the test run]

Terminate operations with /task cancel:

/task cancel bg-1234
Cancelled background task bg-1234

Configuring Background Task Settings

Behavior is controlled via the backgroundTasks JSON block in Claude's settings, as defined in 09-advanced-features/README.md#configuration.

{
  "backgroundTasks": {
    "enabled": true,
    "maxConcurrentTasks": 5,
    "notifyOnCompletion": true,
    "autoCleanup": true,
    "logOutput": true
  }
}

Key configuration options:

• enabled: Toggle the feature on or off
• maxConcurrentTasks: Limit simultaneous operations (default behavior allows multiple)
• notifyOnCompletion: Receive alerts when tasks finish
• autoCleanup: Automatically remove completed task metadata
• logOutput: Persist task output to logs

Auto Mode Safety Integration

When Auto Mode is active, the background safety classifier reviews each action before dispatching it as a background task. This ensures potentially risky operations are vetted before asynchronous execution, as documented in CLAUDE_CONCEPTS_GUIDE.md#background-tasks and implemented with reference to resources/README.md design guidelines.

Summary

• Claude Code executes long-running operations as background tasks with unique IDs (e.g., bg-1234) to prevent chat blocking
• Manage tasks via slash commands: /task list, /task status, /task show, and /task cancel
• Configure behavior through the backgroundTasks JSON object in settings, controlling concurrency limits, notifications, and cleanup
• Auto Mode integration includes a safety classifier that reviews actions before background dispatch
• Source documentation resides in 09-advanced-features/README.md and claude_concepts_guide.md

Frequently Asked Questions

How do I start a background task in Claude Code?

Issue a natural language prompt requesting background execution, such as "Run the full test suite in the background". Claude spawns the task, returns a unique ID (e.g., bg-1234), and immediately returns control to continue your conversation while the operation runs in a separate worker process.

How can I check the status of running background tasks?

Use the /task list command to see all active tasks with completion percentages and estimated remaining time. For detailed progress on a specific task, run /task status <task-id> to view granular metrics like individual test counts or build stages.

What configuration options are available for background tasks?

The backgroundTasks configuration block supports enabling/disabling the feature, setting maxConcurrentTasks limits, toggling notifyOnCompletion alerts, enabling autoCleanup for finished tasks, and activating logOutput for persistent logs. These settings are documented in 09-advanced-features/README.md#configuration.

How does Auto Mode affect background task execution?

When Auto Mode is enabled, the background safety classifier intercepts each potential background task for risk assessment before dispatch. This safety layer ensures that automated operations meet security criteria before executing asynchronously, as described in CLAUDE_CONCEPTS_GUIDE.md#background-tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}