Claude Code Background Tasks: Start, Monitor, Kill
9 Min. Lesezeit
Key takeaways
- Start a Claude Code background task with the & suffix or Ctrl+B, and check its status with the /tasks command.
- Write unattended prompts as three blocks: goal, acceptance criteria, and stop conditions, naming files and directories in scope.
- Give every parallel task its own git worktree and branch named after the ticket, for example worktrees/PROJ-142-login-retry.
- Treat every kill as a code review trigger: inspect the task's worktree diff, then commit the usable part or discard it.
- Retry a failed task only for environmental failures; kill it when the diff touches files outside scope or it loops without progress.
Claude Code background tasks let you launch an agent with &, check its status with /tasks, and kill it with Ctrl-B or a task kill command, so one terminal can supervise several parallel runs. This guide walks the full start → check → kill workflow, plus what to do when a task hangs, drifts off track, or burns your token budget.
What are Claude Code background tasks?
A background task is any Claude Code process launched with run_in_background: true or the & suffix in bash mode. Instead of blocking your session, it returns a task ID and keeps running while you prompt elsewhere, then reports output on demand. The Anthropic Claude Code documentation covers the commands, flags, and status output.
Use background mode for long-running, independent work: test suites, dependency upgrades, or a merge request that will take twenty minutes. Stay in the foreground when the task needs your judgment at each step, like exploratory refactoring or debugging something ambiguous. The distinction matters most when you run several agents at once, because a background task nobody checks becomes the agent that spent three hours fixing the wrong thing.
How do you start a Claude Code background task?
Launching from the CLI
Run claude --background "your prompt" or press Ctrl+B on an active session to push it to the background. Both produce the same thing: a task that keeps working after your terminal closes, tracked by a task ID you can query later. For scripted fleets, pass --print with a prompt file so each task starts from identical instructions rather than whatever you typed last.
Prompt structure for unattended runs
A background task has no one to ask, so the prompt has to carry the whole contract. Write it as three blocks: the goal, the acceptance criteria, and the stop conditions. "Add pagination to /orders endpoint" is a task that wanders. "Add pagination to /orders endpoint, max 50 items per page, tests must pass, do not touch auth code, stop and report if migrations are needed" is a task that survives an hour alone.
Name the files and directories in scope so the agent does not go exploring, and state what to do on failure: retry once, then stop and leave a summary. This is the same discipline behind splitting the thinking from the doing: the direction lives in the prompt, the execution happens unattended. If you are used to Cursor background agents running in parallel, the difference is that here the prompt is the only manager the task gets.
How do you see background tasks in Claude Code?
Inside an interactive session, press Ctrl+B to background a running task, then use /tasks to list everything running with its status and output location. Each task shows as running, completed, or failed, and you can select one to view or retrieve its output. For unattended runs, the same visibility comes from headless mode: claude -p "task" --output-format stream-json emits JSON events you can pipe into a dashboard or log tailer, which is the pattern Anthropic documents for non-interactive runs.
Reading task status and output
| Status | Meaning | What to do |
|---|---|---|
| running | Agent is still working | Check output tail; look for repeated retries |
| completed | Task finished, exit recorded | Review the diff before merging |
| failed | Crashed or hit an error | Read the error, decide on restart or kill |
The failure mode at fleet scale is that per-terminal status tells you nothing about which of ten agents is stuck versus progressing. That is the gap Aerunit's instant feedback for coding agents addresses: one view of every session's state across repos, so a waiting agent surfaces before it burns an hour.
How do you check background task progress without watching the terminal?
The goal is periodic checks on your schedule, not a wall of tabs you refresh by hand. Three signals tell you most of what you need: the task's log output, the state of the git branch it is working on, and whether it is blocked waiting on you.
Polling with git and logs
Each Claude Code background task works on a branch, usually in its own worktree. git log --oneline -5 on that branch shows whether the agent is committing or stuck. A diff against the base branch tells you if it is drifting from the acceptance criteria you wrote in the task. Log files catch the rest: repeated retries, the same error twice in a row, or a token budget climbing with no commits to show for it are all early stop signals. A two-minute sweep across your fleet, repo by repo, beats an hour of tab-watching.
Approval prompts while you are away
The failure mode that costs the most is an agent sitting blocked on an approval prompt for an hour while you assume it is working. Check for pending prompts as part of the same sweep, and batch your approvals in one pass instead of reacting to each one. If a task needs more approvals than you expected, that is a sign the task was scoped too loosely.
For a fuller picture of tracking a fleet this way, see our guide to good stories for coding agents.
How do you kill a Claude Code background task safely?
Killing a single task
Press Ctrl+B to background a running task, then use bashes in the /tasks panel to see every running shell and pick the one to stop. Killing the process is safe; the risk is what it leaves behind. A task killed mid-edit can leave unstaged changes, a half-written file, or a branch nobody reviewed. Before you kill, note the task's branch and worktree so you know exactly which diff to inspect.
Cleaning up after a kill
Treat every kill as a code review trigger: run git status and git diff in the task's worktree, then either commit the usable part or git checkout -- . and delete the worktree. If you run unattended with permission prompts bypassed, Anthropic's docs on hooks and permissions show how to gate dangerous commands so a killed task can't have left destructive changes mid-flight. For fleet-level cleanup discipline across tools, see our cloud coding agents compared.
What do you do when a background task goes off track?
Signals a task is lost
Watch for three patterns: the diff keeps growing but touches files outside the task's scope, the agent re-runs the same command or test loop without progress, or it sits idle waiting on an approval prompt you never saw. A task that has burned its token budget on retries without a new commit in the last stretch is usually stuck, not working. Check the diff scope first; it is the fastest tell, because scope creep shows up in git diff --stat long before the agent's own logs admit anything is wrong. Pair that with a timestamp check: if the last commit is forty minutes old but the log tail is still streaming output, the agent is spinning rather than shipping. Caught early, at the twenty-minute mark instead of the two-hour mark, a drifting task costs you one cleanup instead of an afternoon of unwinding a wrong-direction branch.
Retry vs kill vs take over
Retry only when the failure is environmental: a flaky test, a transient API error, a missing dependency. Re-send the task with the error pasted in and the acceptance criteria restated. Kill when the agent is editing the wrong files or circling; a lost task does not recover by waiting. Take over when the work is 80% right: stop the task, keep the branch, and finish the last mile yourself. The expensive mistake is letting a wrong-direction agent run for three hours because it looked busy.
How do you run several background tasks in parallel without losing track?
One task per git worktree
Parallel tasks that share a checkout overwrite each other. Give every background task its own git worktree and branch, and name both after the Linear issue: worktrees/PROJ-142-login-retry. That single convention answers the three questions your terminal tabs cannot: which task, which repo, which ticket. Track token burn per task so you can kill the expensive ones early; Anthropic documents how to read usage and cost for Claude Code sessions in its cost-tracking docs. Keep acceptance criteria in the task description, not in your head, so a task you rediscover an hour later is still judgeable.
When to add an orchestrator
Past roughly five concurrent tasks, a terminal-tab fleet stops being legible: one agent waits on a question, another fixes the wrong thing, and nothing on screen says which. That is the point where a coordination layer earns its keep. Vibe Kanban gives tasks a board-level view with per-task status; Cursor offers background agents natively in its own app. Honest limitation: Aerunit focuses on task distribution, state tracking, and retries across repos, and it does not manage your Linear board for you. If your bottleneck is deciding what agents should do next rather than watching them, Linear plus the patterns above may be enough.
How does this compare with Cursor background agents?
If you already run Cursor Cloud Agents, the workflow difference is control surface. Cursor hands you a managed agent you prompt from its app; Claude Code background tasks are processes you start, watch, and kill yourself, which means state tracking and retries are your job. That extra work buys you the ability to run the same fleet pattern across Codex or local models, not just one vendor's runtime.
Claude Code fits when you need task distribution across multiple repos, git worktree isolation, or a daemon that survives outside a single IDE. Cursor fits when you want the orchestration handled and your work stays in one codebase.
Where Aerunit sits: it coordinates both, adding acceptance criteria and merge request tracking on top. The honest gap: if you run two or three agents in one repo, Aerunit is overhead you don't need yet.
FAQ
Do Claude Code background tasks keep running if I close the terminal?
Yes. A task launched with claude --background or pushed with Ctrl+B keeps working after your terminal closes, tracked by its task ID. You can query its status and retrieve output later. The caveat: nobody is watching it, so a task that drifts off track will keep drifting until you check in.
Can I resume a background task after killing it, or do I have to start over?
There is no resume command. What survives is the branch: the agent's commits and partial edits stay in its worktree. If the work is mostly right, stop the task, keep the branch, and finish the last mile yourself. If it is wrong, inspect the diff, clean up, and re-send a tighter prompt with the error included.
How much does it cost to leave a Claude Code background task running for an hour?
It depends on the model, the task's prompt size, and how much it retries. A stuck agent burning tokens on the same failed loop with no new commits is the expensive case. Anthropic documents how to read usage and cost per session in its cost-tracking docs, so check burn per task and kill the ones climbing with nothing to show.
Can Claude Code background tasks work on the same branch at the same time?
They can, but you should not let them. Parallel tasks sharing a checkout overwrite each other's edits. Give every task its own git worktree and branch, named after the ticket, for example worktrees/PROJ-142-login-retry. That isolation is what lets you kill one task without corrupting another agent's in-flight work.