Background Tasks

A background task is a Claude session that keeps running without requiring your attention. You start it, move on to other work, and come back when it’s done — or when Claude needs you.

The key insight: most long-running development tasks don’t require your active involvement during execution. They require your judgment at the start (what to do) and at the end (review what was done). Background tasks match that reality.

Starting a Background Task

CLI flag

claude --background "Scan the entire codebase for security vulnerabilities.
Check for: SQL injection, hardcoded secrets, insecure dependencies,
missing auth checks. Create a report at security-audit.md."

The session starts, begins working, and returns your prompt immediately. Claude runs independently.

Desktop app

In the Desktop app, any running session can be sent to the background via the session controls. The session continues in the sidebar without occupying the main window.

Monitoring Background Tasks

Task list

/tasks

Shows all active and recent tasks with their current status:

● auth-migration        running   (12 min)   85 files processed
● security-audit        running   (3 min)    scanning src/api/
✓ dep-update            completed (8 min ago)
✗ schema-migration      blocked   waiting for input

Desktop sidebar

The Desktop app shows a persistent status indicator for each background session — spinning for active, checkmark for complete, warning for blocked. You can see at a glance which tasks need attention without switching focus.

CLI status bar

When running in a terminal, a status line at the bottom shows active background task count and overall progress.

Execution Flow

flowchart LR A([You: start task]) --> B[Claude begins work] B --> C{Needs\ninput?} C -->|No| D[Continues working] D --> E{Done?} E -->|No| D E -->|Yes| F[Sends notification] F --> G([You: review result]) C -->|Yes| H[Marks as blocked] H --> I[Sends notification] I --> J([You: provide guidance]) J --> B style A fill:#1e293b,color:#7dd3fc,stroke:#334155 style B fill:#1e293b,color:#7dd3fc,stroke:#334155 style C fill:#1e293b,color:#fcd34d,stroke:#334155 style D fill:#1e293b,color:#7dd3fc,stroke:#334155 style E fill:#1e293b,color:#fcd34d,stroke:#334155 style F fill:#1e293b,color:#7dd3fc,stroke:#334155 style G fill:#1e293b,color:#86efac,stroke:#334155 style H fill:#1e293b,color:#7dd3fc,stroke:#334155 style I fill:#1e293b,color:#7dd3fc,stroke:#334155 style J fill:#1e293b,color:#86efac,stroke:#334155

Notifications

When a background task completes or becomes blocked, Claude signals you.

Desktop notification — a system notification fires when the task finishes or needs input.

/notify configuration — you can configure notification behavior per-session or globally:

/notify on-complete        # notify when done (default)
/notify on-block           # notify when blocked waiting for input
/notify always             # both
/notify off                # run silently, check /tasks manually

For long tasks (> 30 minutes), always is usually the right setting so you’re interrupted immediately if Claude hits a decision point it can’t resolve alone.

Attaching to a Background Task

When a task completes or is blocked, you can bring it back to the foreground:

claude --resume <session-id>

Or use the Desktop app to click on the session in the sidebar. The full context is preserved — Claude knows exactly where it stopped and what it was doing.

If a task is blocked waiting for input, attaching and providing guidance resumes execution from that point.

When Background Tasks Make Sense

Background tasks shine when execution time is long but interactive guidance isn’t needed at each step.

Whole-codebase analysis

claude --background "Audit all API endpoints for missing authentication checks.
List every endpoint that could be called without a valid session token.
Output to auth-audit.md with severity ratings."

Scanning 500 files takes time. You don’t need to watch it happen.

Documentation generation

claude --background "Generate JSDoc comments for every exported function
in src/lib/ that is currently undocumented. Match the style in src/lib/auth.ts."

Running tests and interpreting results

claude --background "Run the full test suite. For any failures, diagnose the
root cause and create a GitHub issue for each distinct failure pattern."

Large refactors with clear scope

When the transformation is well-defined and touches many files, background execution lets Claude work through all of them while you review the plan or work on something else.

Dependency updates

claude --background "Update all dependencies to their latest minor versions.
Run tests after each update. Revert any update that causes test failures.
Create a PR with a summary of what changed."

The `waitUntil` / `after()` Pattern

Background work can be chained after a foreground response. Claude completes the main task synchronously, then continues non-blocking work in the background:

Implement the login form. After you're done, also:
- Write unit tests for the form validation logic
- Check if any existing tests need updating given the new implementation
- Update the auth section of README.md

Claude returns the implementation immediately (foreground), then handles the follow-up tasks in the background. You get the code you need now; the housekeeping happens automatically.

Background Tasks vs `/loop`

These look similar but serve different purposes:

	Background Task	`/loop`
Recurrence	Once — runs to completion	Recurring — executes on a schedule
Trigger	You start it manually	Time-based (cron) or event-based
Duration	As long as the task takes	Fixed per-iteration, repeats indefinitely
Use when	”Do this once, it’ll take a while"	"Do this every hour/day/week”

For a one-off security audit: background task. For a daily summary of new issues: /loop. See Loop for scheduled recurring execution.

Background Tasks vs Git Worktrees

These are complementary, not alternatives:

Background task = a session running without your attention. It operates on whatever branch state it started from.
Git worktree = isolated branch state so multiple sessions can write files without conflicting.

A background task can use a worktree (and should, if it’s writing files that another session or you might also touch). A background task without a worktree runs on the same branch you’re working on — safe only if it’s read-only or you’re not writing to the same files.

For write-heavy background tasks, launch with both:

claude -w --background --label "security-audit"

See Git Worktrees for the full parallel execution pattern.

Practical Example: Full Prompt

claude --background --label "sec-audit" \
  "Scan the entire codebase for security vulnerabilities.

   Check for:
   - SQL injection (raw string concatenation in queries)
   - Hardcoded secrets (API keys, passwords, tokens in source)
   - Insecure dependencies (run npm audit, flag high/critical)
   - Missing authentication checks on API routes
   - Unsafe deserialization

   For each finding:
   - File path and line number
   - Severity (critical / high / medium / low)
   - Description of the vulnerability
   - Recommended fix

   Write the report to security-audit.md.
   Notify me when done."

This is a task that could take 20-40 minutes on a large codebase. Starting it as a background task means you’re not blocked — and when it finishes, you have a prioritized audit report ready to action.

Loop — recurring scheduled execution
Git Worktrees — isolated branch state for parallel tasks
Session Management — resuming and managing sessions