← All posts

Guide

How to run Claude Code in the background (and still catch when it needs you)

Yes — Claude Code can run in the background. The /background command (alias /bg) detaches a whole session to keep working as a background agent, long commands can run in the background inside a session, and headless mode (claude -p) runs with no terminal at all. What none of them do on their own is tell you the moment the agent needs a decision — and that gap is why background agents quietly stall.

The scenario is always the same: you hand Claude Code a task — refactor a module, chase down a flaky test, wire up an endpoint — and then you want to go do something else. Read a PR, answer Slack, ship a different feature. The phrase people reach for is "run Claude Code in the background," but it hides two very different things: keeping the process alive and keeping yourself in the loop are separate problems. This guide covers both, and the workflow that closes the gap.

Two meanings of "background"

There's truly detached, and there's running but still watchable. They are not the same problem.

• Detached / headless — fire-and-forget. The agent runs with no interactive terminal, does its thing, and you collect the result later (a commit, a log, a PR). This is great for work that needs zero decisions: a scripted migration, a batch edit, a CI-style job where you've pre-approved everything.
• Running but still notified — the agent keeps working while you do other things, but it can still reach you the moment it hits a yes/no, asks a clarifying question, or finishes. You're not staring at it; you're just reachable.

Here's the thing most people miss: a coding agent is not a batch job. It pauses. Claude Code stops for permission before a risky command, asks what you meant when your instructions were ambiguous, and waits at the end for the next move. Those pauses are the whole interaction. So when developers say they want to run Claude Code in the background, they almost always want the second meaning — out of the way, but not out of reach. Treat an interactive agent like a headless one and it sits idle on a prompt you never saw.

The native-ish options, and where they leak

The instinct is to reach for the classic Unix toolbox. Each one keeps the process alive; none of them keep you in the loop.

• A second terminal / split pane. Fine until the window is buried behind your editor or browser. You stop glancing at it, and the approval prompt sits there for ten minutes while you're heads-down elsewhere.
• tmux / screen. Genuinely good at keeping the process running — detach the session, close the terminal, the agent survives. But a detached tmux pane has no way to tap you on the shoulder. You have to remember to tmux attach and look. The agent is alive and the prompt is waiting; you just don't know it.
• nohup / & / disown. These detach a process from your shell so it outlives the terminal. That's exactly wrong for an interactive agent — it now has nowhere to send a question and nowhere to read your answer. You get headless behavior whether you wanted it or not, and any prompt becomes a hang.
• Claude Code's own background features. Claude Code can run tools and longer operations in the background, and that's useful inside a session. There's also a real /background command (covered just below) that detaches a whole session. But these solve "this step shouldn't block the agent" and "free up my terminal," not "I closed the window and want to be pinged across the whole run." The session is still alive in a terminal you have to keep checking.

Is there a /background command in Claude Code?

Yes — and it's worth clearing up, because a lot of people search for the literal slash form, claude /background, and aren't sure it exists. It does. /background (alias /bg) detaches the current session so it keeps running as a background agent and hands your terminal back; claude --bg starts a session detached from the outset. While it runs, /tasks lists what's working in the background of the session, and you re-attach later to see where it got. So when someone asks "can Claude Code run in the background?" or "how do I run Claude Code background tasks?", the short answer is: through /background / --bg for a whole detached session, the in-session background tooling for individual long commands, and headless mode (claude -p "…") for a fully scripted, non-interactive run.

Here's the catch, and it's the same one as every option above: detaching the session frees your terminal, but nothing in /background taps you on the shoulder when the agent hits a decision. You still have to remember to check the agent view. "Can Claude work in the background?" — yes; "will it come find me when it's stuck?" — that's the piece you have to add.

The common failure is identical across all of them: the agent keeps running, but the signal — it needs a decision, it finished — never finds you. You traded babysitting for blindness. That trade is the subject of stop babysitting your AI coding agent.

The workflow that actually works

If what you want is "running but still notified," three pieces have to be true at once:

• The agent lives in a lightweight, always-on-top surface instead of a buried tab. You can glance at its state in a second without alt-tabbing away from what you're doing — closer to a GUI for Claude Code than a raw terminal you have to keep finding. The mechanics of doing this over any window are covered in an always-on-top terminal over any app.
• A daemon owns the agent, not the UI. The process that runs Claude Code should be separate from the window you look at, so closing or restarting the UI never kills the work. This is the part tmux gets right and a plain terminal gets wrong — except here you can also re-attach and replay the scrollback instead of squinting at a detached pane.
• You get an explicit ping on the events that matter. Not a firehose of every tool call — just the transitions where the agent actually needs you: a permission request, a blocking question, or "done." Everything else stays silent.

That last piece is the one tmux and nohup structurally can't give you, and it's where Claude Code's design helps. Claude Code exposes lifecycle hooks — roughly Notification (it wants attention), Stop (it finished), and PreToolUse (about to run a tool, can pause for allow/deny). Those are the exact moments worth a sound or a flash; Claude Code hooks, explained walks through how each one fires. Wire them to a notifier and "background" stops meaning "blind." The same plumbing is what lets you push past one task at a time and run multiple AI agents at once without losing track of which one is waiting on you.

Frequently asked questions

Where Backgrind fits

This is the shape Backgrind is built around. A background daemon keeps your agents alive across UI restarts and crashes, and notifications fire even while the window is hidden — a chime plus an accent ring on the tab that needs you, driven by those same Claude Code hooks. You run your real claude CLI (your login, your history), put it out of the way, and answer only when it actually pings — and when the ping catches you away from the keyboard, you can drive your agent from your phone instead of running back to the desk. If you want the deeper mechanics of pinning it over your other windows, see an always-on-top terminal over any app, or try the live demo to feel the notification loop.