Claude Code Background Tasks: How to See, Stop and Track Them

A background task in Claude Code is work that keeps running while you carry on with something else: a shell command such as a dev server or a test run, a subagent, a monitor watching a log, or a whole session running without a terminal. You start one by asking Claude to run something in the background or by pressing Ctrl+B while it runs. Inside a session, /tasks lists them and lets you stop them; background sessions have their own screen, claude agents, and their own claude stop. None of these lists is a record: a finished item leaves them within seconds or at exit. If the result matters, it belongs on the card for that job.

Four kinds of background work

• Background shell commands. Claude runs a Bash command asynchronously, gets back a task ID straight away and keeps answering you. Output is written to a file Claude can read. The docs↗ (opens in a new tab) list the usual candidates: build tools, package managers, test runners, dev servers.
• Background subagents. Workers that run concurrently↗ (opens in a new tab) while you keep going. Their results reach Claude as a completion notification in a later turn. If one needs permission, the prompt surfaces in your main session and names the subagent asking.
• Monitors. The Monitor tool↗ (opens in a new tab) runs a script in the background and feeds each output line back to Claude, so it can react to a log line or a CI status. Every watch has a deadline: five minutes by default, thirty at most.
• Background sessions. A full Claude Code conversation that runs without a terminal attached, hosted by a separate supervisor process, so you can close the shell and it keeps going. Managed from agent view, which is a research preview.

One thing that is not background work: Claude’s own task list, the checklist Ctrl+T shows. The docs call it out as separate from the background-task view. The difference is covered in Claude Code tasks vs to-dos.

Starting one

• Ask. “Start the dev server in the background” is enough; Claude sets run_in_background on the command.
• Press Ctrl+B while a command or agent is running to move it to the background. Under tmux, press it twice, because Ctrl+B is tmux’s prefix key.
• Wait. When a command reaches its timeout, Claude Code moves it to the background instead of killing it, unless the command starts with sleep.
• Send a whole session. /background (or /bg) moves the current conversation to a background session and frees the terminal. /fork sends a copy and keeps you where you are. From the shell, claude --bg "<prompt>" starts one directly.

Seeing what is running

Inside a session, run /tasks (it also answers to /bashes). It lists the background work in the current session, lets you check on, attach to or stop each item, and includes subagents that have finished. Select a subagent and press Enter to open its transcript. Running background subagents also appear in a panel below the prompt input.

For background sessions, the view is claude agents. It groups every background session by state: Working, Needs input, Idle, Completed, Failed and Stopped. Select a row and press Space to peek at its latest output, or Enter to attach to the full conversation. From a script, use the shell commands:

claude --bg --name "bu-042" "Work on BUG-042 from the board"
claude agents                  # the full-screen view
claude agents --json --all     # state for scripts: working, blocked, done, failed, stopped
claude logs 7c5dcf5d           # recent output of one session
claude attach 7c5dcf5d         # open it in this terminal
claude stop 7c5dcf5d           # stop it (claude kill also works)

The ID is the short one printed when the session starts. The docs↗ (opens in a new tab) recommend claude agents --json over reading the files under ~/.claude/jobs/, which are not a stable interface.

Stopping one

• A shell, monitor or subagent in this session: open /tasks, select it and stop it, or ask Claude to stop it; Claude does that with its TaskStop tool. Stopping a subagent from /tasks also stops any monitors it started.
• Every background subagent at once: Ctrl+X Ctrl+K, pressed twice within three seconds to confirm.
• A background session: Ctrl+X on its row in agent view (press again within two seconds to delete it), claude stop <id> from the shell, or /stop while attached, which keeps the transcript and any worktree.
• Everything, by leaving: background tasks are cleaned up when Claude Code exits. If work is still running, Claude Code asks first and offers to move the session to the background instead.

Stopping the turn Claude is in is a different control. Esc interrupts the current response or tool call. That is covered, with rewinding, in how to stop a Claude Code task midway.

What the lists forget

The views are built to show what is happening now, and the docs are specific about how quickly they let go:

• A background subagent that completes stays in /tasks for about 30 seconds, marked done. One that fails or that you stop leaves the list.
• Background shell and monitor tasks are never restored when you resume a session.
• In a claude -p run, a background shell is terminated about five seconds after the final result↗ (opens in a new tab).
• A background command whose output passes 5 GB is terminated, with a note in stderr saying why.

So the question “what happened to the test run I sent to the background at lunch?” has a short shelf life inside Claude Code. The answer was a notification in a conversation, and the conversation has moved on.

Recording outcomes on the card

The fix is to decide, before anything goes to the background, which card it belongs to, and to have the outcome written there. A dev server does not need a card. A flaky-test investigation, a migration dry run or a background session working on a bug does: somebody will ask how it went.

For background sessions, put the ref in the prompt and the name, as in the example above; the row in agent view and the card then carry the same label. For background shells and subagents inside a session, one paragraph in CLAUDE.md does it. This assumes a fenbs board connected over MCP.

## Background work and the board
- Before sending anything to the background for a card, comment on it:
  what you started and why.
- When a background task or subagent finishes, comment the outcome on
  that card: result, commit if any, and the check you ran.
- If you or I stop it before it finishes, comment that it was stopped,
  where it got to, and what is left.
- Dev servers and watch builds need no comment.

Two comments per job is the right size: started, and finished or stopped. The board’s history then holds what /tasks could only hold for thirty seconds, and a person who was not in the session can read it. For a whole day of such work, the AI assistant work log template is a board laid out for exactly this.

A caution for the tidy-minded: do not ask Claude to comment every line a monitor reports. The card is for outcomes. A watch that saw forty log lines and one error has one thing worth writing down.