# Setting Up Background Tasks in Claude Code: Complete Configuration Guide

> Master background tasks in Claude Code with this configuration guide. Run tests, builds, and deployments asynchronously without blocking your chat.

- Repository: [Luong NGUYEN/claude-howto](https://github.com/luongnv89/claude-howto)
- Tags: how-to-guide
- Published: 2026-03-30

---

**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:

```text
/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`:

```text
/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`:

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

```

Terminate operations with `/task cancel`:

```text
/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`.

```json
{
  "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`](https://github.com/luongnv89/claude-howto/blob/main/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`](https://github.com/luongnv89/claude-howto/blob/main/09-advanced-features/README.md) and [`claude_concepts_guide.md`](https://github.com/luongnv89/claude-howto/blob/main/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`.