Blog · August 8, 2026 · 6 min read · by Vilva Athiban P B

Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

Every Claude Code user has lived this moment: Claude kicks off the test suite, or a production build, or npm run dev — and the session just sits there. The command scrolls, Claude waits for it to finish, and you wait for Claude. A tool built to work autonomously ends up blocked on a webpack progress bar.

Background tasks fix exactly this. They're one of Claude Code's most useful features and one of its least understood, because most of the interesting behavior — lifecycle rules, output limits, what happens when you quit — lives in the fine print. This guide covers how backgrounding actually works, what to background, and the cleanup rules that will surprise you if you don't know they exist.

How backgrounding works

When Claude Code runs a command in the background, it executes asynchronously and immediately returns a background task ID. Claude is free to keep working — reading files, editing code, answering your next prompt — while the command runs. The command's stdout and stderr are written to a file, and Claude can check on it at any point by reading that output.

There are two ways to get a command into the background:

  • Ask for it. Say "run the dev server in the background" and Claude uses the Bash tool's background mode on its own.
  • Press Ctrl+B while a command is running. This moves an already-running Bash command (or agent) to the background mid-flight. If you're inside tmux, press it twice — Ctrl+B is tmux's prefix key.

That second one is the underrated move. You don't have to predict which commands will be slow. When Claude launches something and you realize it's going to take four minutes, one keystroke unblocks the session and the work continues without you.

What belongs in the background

The pattern: anything long-running whose output you need later, not now.

  • Dev servers — the classic. Start Vite or Next in the background once, and Claude can check its logs after every change instead of ever blocking on it.
  • Builds and full test suites — kick them off, keep working, have Claude read the results when they land.
  • Watchers and log tails — a backgrounded tail -f on an error log gives Claude a live feed it can consult on demand.
  • Anything you'd otherwise stare at — long installs, migrations, data jobs.

Subagents run in the background too

Backgrounding isn't just for shell commands. Recent versions of Claude Code run subagents in the background by default, and you can force the behavior per agent by adding background: true to the agent's frontmatter. A background subagent works exactly like a backgrounded command from your point of view: it gets an ID, it runs while the main conversation stays responsive, and its results arrive when it finishes.

One detail worth knowing: background subagents get a reduced set of built-in tools compared to foreground ones — the essentials like Read, Grep, Bash, Edit, Write and web tools survive, but interactive tools (like asking you a question) don't. That's by design: a background agent shouldn't stop the world to talk to you. And if a fleet of background agents goes sideways, Ctrl+X Ctrl+K (pressed twice to confirm) stops all of them at once.

Keeping track: /tasks, not Ctrl+T

Once things run in the background, you need a view of what's alive. That's the /tasks command, which lists running shells and subagents. Don't confuse it with Ctrl+T, which toggles Claude's to-do checklist — a plan of record, not a process monitor. If you juggle several sessions on top of background tasks within each, our guide to running multiple Claude Code sessions covers the bigger-picture version of the same problem.

The lifecycle rules nobody reads

Background tasks are not immortal, and the rules governing when they die are worth two minutes of your attention:

  • Exit kills them. Background tasks are cleaned up when Claude Code exits. If you background the whole session instead of quitting, its tasks are handed off and keep running.
  • There's a 5GB output cap. A task whose output exceeds 5GB is automatically terminated, with a note in stderr explaining why. A chatty dev server left overnight can genuinely hit this.
  • Memory pressure reaps idle tasks. On macOS and Linux, if the OS signals memory pressure and your session has been idle for 30+ minutes, Claude Code terminates running background tasks. Set CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 to opt out.
  • Subagent-owned commands have a timer. Background commands started by a subagent are terminated after 60 minutes by default, configurable via CLAUDE_SUBAGENT_BG_SHELL_MAX_MS.
  • You can turn it all off. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 disables background task functionality entirely.

The practical takeaway: background tasks are for the lifetime of a working session, not for daemons. If something must survive your laptop's afternoon, run it under a real process manager and let Claude tail its logs instead.

Hygiene: kill what's dead

Every live background task is something the session keeps track of, and long-running shells you no longer need are pure overhead. When a backgrounded build has served its purpose, tell Claude to kill it — or check /tasks yourself and prune. This is the same discipline as context management: the session works best when it's only carrying what still matters.

Backgrounded is not the same as done

Here's the catch that motivates this whole workflow. Before background tasks, you knew when the test suite finished because you were watching it. Now the suite finishes silently in the background, Claude finishes its other work and waits for you — and nothing anywhere makes a sound. Backgrounding moves work out of sight, which is the point, but out of sight cuts both ways: the run that completed eight minutes ago is worth exactly nothing until you notice it.

The fix is the same one we describe in our post on not watching the terminal: make completion push to you instead of you polling for it.

A 60-second starter workflow

  1. Start your dev server in the background at the top of the session: "run the dev server in the background and check its logs after each change."
  2. When any command turns out to be slow, hit Ctrl+B and keep going.
  3. Use /tasks to see what's running; kill anything that's done its job.
  4. Set up a notification for when Claude finishes, so backgrounded work gets acted on the minute it lands — not whenever you remember to look.

Background tasks turn Claude Code from a tool that works while you watch into one that works while you don't. Learn the two keystrokes, respect the lifecycle rules, and close the loop with a notification — that's the whole trick.

Keep reading

Desk Exercises for Programmers: 15 Moves to Do While Your AI Agent Codes

7 min read

Exercise While Coding: Turn Claude Code Wait Time Into Micro-Workouts

7 min read

Claude Code Notch Notifications on Mac: See When Claude Is Done Without Watching the Terminal

7 min read

Claude Code Tips and Tricks: 12 Ways to Use Claude Code Effectively

8 min read

Claude Code Multiple Sessions: How to Run Agents in Parallel Without Losing Track

6 min read

A Claude Code Workflow That Doesn't Involve Watching the Terminal

5 min read

Claude Code Hooks: A Practical Guide to Automating Your Agent Workflow

7 min read

Claude Code Auto Mode: Fewer Permission Prompts Without Living Dangerously

7 min read

Claude Code Subagents: How to Delegate Work to Specialized Agents

7 min read

Claude Code Context Management: Treat the Context Window Like a Budget

6 min read

Per-Subagent Model Selection: Route the Grunt Work Down, Keep the Judgment Up Top

7 min read

Skills and Plugins: How to Teach Claude Code Your Way of Working

7 min read

Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

7 min read

Cursor Notification When Done: Every Way to Get Notified When Cursor Finishes

6 min read

Claude Code Notifications: How to Get Notified When Claude Code Finishes or Needs Your Input

6 min read

Want to Be Notified When Claude Responds? How Claude Notifications Work on Web, Desktop, and Mobile

5 min read

Claude Code Notification Scripts: Copy-Paste Recipes for Every Platform

6 min read

Get a Ding the Moment Codex Needs Your Response

6 min read

Get Notified the Moment Claude Code Is Waiting for Your Input

6 min read

“Notifications Are Turned Off for Claude” — Here Is the Fix

6 min read

Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

6 min read

terminal-notifier + Claude Code: Native macOS Alerts When Your Agent Finishes

6 min read

Gemini CLI Notifications: How to Get a Sound or Alert When Gemini Finishes

6 min read

Get Claude Code Notifications on Your Phone

6 min read

Claude Code Remote Control, Explained

7 min read

preferredNotifChannel: Claude Code's Built-In Notification Setting

6 min read

Claude Code Notifications in tmux and Over SSH

7 min read

Claude Code Effort Levels: Why Your Setting Keeps Getting Ignored

8 min read

Codex vs Claude Code Notifications: How Each One Tells You It Is Done

8 min read

Claude Code Notifications Not Working: A Diagnostic Checklist

10 min read

Claude Code Notifications Inside Your Editor's Terminal

7 min read

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Explained

7 min read

CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP Explained

8 min read

Cursor Alerts Explained: Every Alert Cursor Raises, and How to Control Them

7 min read

Claude Code Environment Variables: The Groups That Actually Matter

10 min read

Claude Code Notifications on WSL and Windows

9 min read

Claude Code Checkpoints and /rewind

8 min read

Claude Remote Control: How It Works, Turning It Off, and Auto Mode

7 min read

Claude Code /loop: Poll a Deploy, Babysit a PR, and Get Told When It's Done

8 min read

Setting Up NotchFit With OpenAI Codex CLI: Hooks, $notchfit-plan, and the Daily Flow

7 min read

Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

9 min read

NotchFit vs Mac Break Reminder Apps: A Clock or a Signal From Your Coding Agent?

8 min read

Claude Code Headless Mode: Running claude -p in Scripts and CI, and the Three Signals That It Finished

10 min read

Building a Movement Habit at a Desk: Use the Agent Run as the Cue, One Set as the Unit, and Streaks Carefully

8 min read

Claude Code MCP Servers Explained: Adding Servers, Choosing a Scope, Handling Secrets, and Why Long Tool Calls Go to the Background

10 min read

/notchfit:plan Explained: How Claude Code or Codex Writes a Weekly Workout Plan the Notch Can Actually Run

8 min read

Claude Code Spinner Verbs Explained: What “Pondering” and “Brewing” Mean, How to Change Them, and Why You Should Stop Watching the Spinner

7 min read

Why NotchFit's Done and Permission Alerts Wait Until Your Set Ends, When That Costs You, and How to Turn the Workout Off

7 min read

How to Resume a Claude Code Session: --continue vs --resume, Naming Sessions, the Session Picker, Branching, and What Comes Back

9 min read

NotchFit on a Mac Without a Notch: How Pill Mode Works on Mac mini, iMac, Mac Studio and a MacBook With the Lid Closed

6 min read

How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

9 min read

What a Notch App Can See: NotchFit's Local-First Design, What the Claude Code and Codex Hooks Send, and What Stays on Your Mac

7 min read

Why Codex CLI Asks for Permission Every Time, and How to Tune the Sandbox and Approval Policy Without Going Full Access

8 min read

What to Do While Claude Code or Codex Works: A Simple Protocol for the Two-to-Twenty-Minute Gap in Every Agent Run

7 min read

Is It Possible to Get a Notification When Claude Code or Codex Hits a Reset? Yes for Claude Code: the quota_auto_resume Hooks, Explained

8 min read

What a MacBook Notch App Can Actually Do: The Five Kinds of Notch Utility, Their Trade-offs, and Where NotchFit Fits

7 min read

How to Make MCP Servers Not Take Up as Much Context in Claude Code: Tool Search, alwaysLoad, Scopes and Output Caps

8 min read

The notchfit Command Line: Drive Your Workout, Read Status as JSON, Validate Plans and Test the Notch Without Leaving the Terminal

7 min read

How to Audit MCP Tool Calls Made by Claude Code: A Five-Minute Hook Audit Log, OpenTelemetry Tool Events, and the Transcript for Investigations

9 min read

Exercise Snacks: What the Research Actually Says About One-Minute Vigorous Breaks, What It Does Not, and How NotchFit's Agent-Run Sets Compare

8 min read

How Long Until a Claude Code MCP Tool Call Times Out? The Four Timers (Startup, Two-Minute Backgrounding, Idle, Wall-Clock), Their Defaults, and Which One to Change

8 min read

Sitting Too Long as a Developer: The Posture Problems Coding Agents Made Worse, What the Research Says About Breaking Up Sitting, and How NotchFit Turns an Agent Run Into the Break

8 min read

Claude Code .mcp.json Explained: Where Project-Scoped MCP Servers Are Read From, What Happens in Subfolders and Monorepos, and Why a Committed Server Shows Pending Approval

8 min read

Standing Desk Exercises for Developers: Why Standing Still Is Not the Goal, Eight Movements That Fit a Thirty-Second Agent Run, and How NotchFit Cues Them From the Notch

8 min read

The claude mcp Command Reference: add Syntax by Transport, What --scope local, project and user Actually Mean, add-json and add-from-claude-desktop, list, get, remove, login and serve

9 min read

Your First Week With NotchFit: Install and Simulate, Run Real Tasks, Write a Smaller Plan Than You Want, Tune the Alerts, Survive the First Skipped Day, and Decide What Stays

8 min read

How to Stop a Running Claude Code Task: Esc vs Ctrl+C, Background Tasks, Subagents, and Disconnecting Remote Control

8 min read

Pomodoro vs Agent-Driven Breaks: Timing Movement to Claude Code and Codex Runs Instead of a Timer

7 min read

Claude Desktop MCP Configuration: claude_desktop_config.json, Logs, Extensions, and the Difference From Claude Code

9 min read

The 20-20-20 Rule for Developers: Eye Strain, the Evidence, and Agent Runs as the Cue

8 min read

Claude Agent SDK + MCP Servers: mcpServers, allowedTools, Status Checks and Auth

9 min read

Discreet Desk Exercises for an Open-Plan Office While Claude Code Runs

7 min read

claude remote-control Server Mode: Run Claude Code as a Session Server

9 min read

Wrist and Forearm Stretches for Developers: A 60-Second Routine for Every Claude Code Run

7 min read

Claude Remote Control vs Claude Code on the Web: Which to Use and How They Differ

9 min read

Neck and Shoulder Stretches for Developers: A 90-Second Routine Between Agent Runs

7 min read

What Happens When You Step Away From a Claude Code Session: Prompt Cache Expiry, Idle Compaction, and When to Come Back

8 min read

Hip Flexor and Lower Back Stretches for Developers: A Two-Minute Standing Routine Between Agent Runs

7 min read

Claude Code's Monitor Tool: Watch Logs, CI Runs and PRs (Even a WebSocket) and Let Claude React While You Keep Working

7 min read

Hunched Over the Keyboard? Upper-Back (Thoracic) Stretches for Developers: A Two-Minute Seated Routine Between Agent Runs

6 min read

Claude Code Ultrareview: The 15–25 Minute Cloud Review, What to Do While It Runs, and How the Findings Come Back

8 min read

Why Your Legs Go Dead After a Long Claude Code Session: A Two-Minute Standing Calf, Glute and Hamstring Routine Between Agent Runs

7 min read

claude --teleport: Pull a Cloud Session Into Your Terminal, Start One With --cloud, Send Follow-Ups From the CLI, and the Requirements That Trip People Up

8 min read

Rounded Shoulders From Typing? A Two-Minute Chest Opener, Chair Twist and Wall Press Desk Routine for Developers Between Agent Runs

7 min read

Claude Code ultrathink Explained: It Now Runs the Turn at xhigh Effort, How It Differs From /effort, What It Costs in Time, and What to Do While It Runs

7 min read

Best Break Reminder Apps for Mac in 2026: Time Out, Stretchly, BreakTimer, LookAway and NotchFit Compared

7 min read

Claude Code 2.1.319: denyInsteadOfPrompting, MCP Background Tasks and What Changes for Unattended Runs and Notifications

8 min read

Drink Water and Stand Up Cues for Developers: Use Claude Code Agent Runs as Hydration and Standing Reminders

7 min read

Claude Code 2.1.323: Code Mode, Progress Heartbeat, Auto-Mode Fallback and 1M Context — What Changed for Unattended Runs

9 min read

Notch Media Controls on a Mac: What the MacBook Notch Can and Cannot Do, Dynamic Island-Style Apps vs NotchFit

7 min read