Claude Code background tasks: dev servers and Ctrl+B

To keep a dev server, watcher or test run going while Claude Code works, ask Claude to start it in the background, or press Ctrl+B while the command is running (twice inside tmux). It becomes a background task with its own ID. Claude reads its output from a file, /tasks lists and stops it, and Claude Code stops it when you exit unless you move the session to the background first.

The details below come from Anthropic's pages on interactive mode, the tools reference and agent view, read on 24 October 2026. We build Shuriken in many worktrees at once, each with its own servers, which is why a section near the end is about ports.

How to run a dev server in the background in Claude Code#

There are two ways in, and they end in the same place.

1. Ask for it: "start the dev server in the background and tell me which port it's on". Claude calls its Bash tool with run_in_background: true, gets a task ID back straight away and carries on with the next step.
2. Or let Claude start the command normally, then press Ctrl+B while it is still running. The command moves to the background and the turn continues. In tmux, press Ctrl+B twice, because tmux takes the first press as its prefix key.

Ctrl+B backgrounds running subagents as well as shell commands, and it works on commands you type yourself in shell mode, such as ! npm run dev. Anthropic lists the commands people usually background: build tools (webpack, vite, make), package managers, test runners like jest and pytest, development servers, and long processes such as docker and terraform.

Sometimes Claude Code moves a command for you. A foreground command that reaches its timeout (2 minutes by default, set by BASH_DEFAULT_TIMEOUT_MS, unless Claude asked for longer) goes to the background instead of being killed, unless it starts with sleep. The result then reads Command did not complete within its 120s timeout and was moved to the background, followed by the task ID and the path of its output file. A cd inside a moved command does not carry over to the commands after it.

How Claude reads the output of a background command#

The output goes to a file, and Claude reads that file with its ordinary Read tool whenever it wants to check: after an edit, to look for a compile error, or because you asked whether the server is still up. A separate TaskOutput tool used to do this job; Claude Code v2.1.277 removed it.

A monitor works the other way round. With the Monitor tool, Claude runs a small watching script in the background and gets each new output line as it arrives, so it can react to a log line mid-conversation. Each watch has a deadline, 5 minutes by default and 30 at most, so a monitor watches a server; it is not what keeps one running.

One hard limit: a background task whose output passes 5 GB is ended, with a note in stderr saying why.

See and stop background tasks with /tasks#

/tasks (also available as /bashes) lists the session's background work: shell commands and subagents, including subagents that have finished. It opens at once, even while Claude is mid-turn. Stop a command there and Claude moves on instead of waiting for it. On macOS and Linux, stopping a task also stops processes that detached from its shell, such as ones started under setsid or timeout.

You can also say "stop the dev server" in plain words, because Claude has a TaskStop tool that ends a background task by ID.

Ctrl+T is not the shortcut you want here. It shows or hides Claude's to-do checklist, which Anthropic's shortcut table calls out as separate from the background-task view. The rest of the keys are in our Claude Code keyboard shortcuts list.

What happens to background tasks on exit, /bg and other moves#

A local session you work in from a terminal, the desktop app or the VS Code extension puts no time limit on background commands. What ends them is mostly what you do with the session:

Monitors are the exception to the /bg row. A running monitor can't move to a background session, so /bg stops it, after a Background this session? dialog asks you to confirm. The ← row has a catch of its own, in Anthropic's words: "In the background session, Claude has no record that the command started, so Claude may run the command again." Pressing Ctrl+B while Claude Code waits turns the command into a background task, and those carry over to the background session.

The full rules for background sessions, including the supervisor that keeps them alive after you close the terminal, are in our Claude Code agent view guide.

How to turn off background tasks#

Set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 before starting Claude Code:

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude

With it set, the run_in_background option disappears from the Bash, PowerShell and subagent tools, Ctrl+B stops working, and forked skills no longer run in the background. Claude Code also stops moving subagents, long MCP tool calls and timed-out shell commands to the background, so a command that reaches its timeout is stopped. The Monitor tool and MCP tasks still run in the background. Starting Claude Code in bare mode has the same effect.

That trade suits a script or a CI job where a hung command should fail rather than linger. For day-to-day work with a dev server, leave it on.

Two worktrees, one port: the parallel trap#

Background dev servers get awkward once several Claude Code sessions run side by side in their own worktrees, for example with claude --worktree. Each worktree has the same package.json, so each session starts the same dev script on the same port. The second server either fails with EADDRINUSE or, with Vite, moves to the next free port and says so in one log line: Vite's docs say the configured port "may not be the actual port the server ends up listening on". An agent that then opens the usual address is testing the other branch's code.

The way out is to stop trusting the default port. None of this needs an extra tool.

1. Give each worktree its own port in the command Claude runs: npm run dev -- --port 5174 for Vite, PORT=3001 npm run dev for a server that reads PORT.
2. Add --strictPort to Vite, which makes it exit when the port is taken instead of drifting to another one.
3. Tell Claude the port in your prompt, so it checks the right address.
4. Find what holds a port with lsof -nP -iTCP:5173 -sTCP:LISTEN on macOS and Linux, or netstat -ano | findstr :5173 on Windows. If it's a background task, stop it from /tasks in the session that started it.

We wrote up how we hit this in Shuriken's own repository, and what we changed, in many dev servers, many worktrees, no port fights.

How Shuriken handles background commands and dev servers#

Shuriken is a harness: it runs Claude Code, Codex and other agents on your own computers, and you follow their chats from any device. When Claude Code starts a dev server or a watcher in the background of a Shuriken chat (npm run dev, vite, next dev and the like), it lands in the project's Dev servers list, pinned at the foot of the chat's Activity panel on a wide screen. Shuriken fills that list by itself, from the project's scripts and from the processes really listening on a port, including a server you started in another terminal. Each row shows its port and device, and when a port is taken the list names the holder ("Port 3000 is in use by node (PID …)").

Other background commands, such as a test run, show up in Activity as chips, and a chip names its port when the command serves one ("node server.js · :3000"). Open a chip and you get its own tab with the whole command, how long it has been running, its last output and a Stop button. The chat's running pill counts those commands with the subagents. In the desktop app's built-in browser, a page whose server isn't running shows Start this server instead of a connection error.

For parallel worktrees, mark a long-running script as a service in shuriken.json. Each worktree's copy then gets a free port of its own in SHURIKEN_PORT, which you pass on with something like PORT=$SHURIKEN_PORT npm run dev. And since Shuriken 3.1, a dev server running on another of your devices opens live in Shuriken, so you can check a chat's work on your desktop from your laptop. That preview traffic passes through Shuriken's cloud over HTTPS without being stored; unlike your chats, it is not end-to-end encrypted.

If that's the setup you want, download Shuriken and open a project.