Running Claude Code in the Background: A Workflow Guide

One of the best things about Claude Code is that it can do real work while you do something else. Write tests, refactor a module, update documentation — hand it off, switch to another task, and come back when it’s done.

But “running in the background” with an AI agent isn’t the same as running a build script. Claude Code is interactive. It asks questions, requests permissions, and sometimes needs course corrections. If you ignore it for too long, it might sit idle waiting for approval. If you check too often, you lose the productivity benefit of async work.

This is how I structure my workflow for background Claude Code sessions.

The approval problem

Claude Code operates with permission gates. Depending on your approval mode, it will pause before running shell commands, editing files, or performing other actions. This is good — you want oversight. But it means a background agent can stall silently if you’re not watching.

In a standard terminal, a stalled agent looks exactly like a working agent: the cursor sits there, nothing’s scrolling. You have to click into the tab and read the output to know whether it’s thinking, executing, or waiting for you.

This is the fundamental tension of background agent work: you want to walk away, but the agent might need you.

Setting up for background work

Before you hand off a task and switch focus, a few things make the experience dramatically better.

Choose the right approval mode

If you trust the task scope, consider using a more permissive approval mode. Claude Code’s auto-approve options let you whitelist certain actions — file edits in a specific directory, test runs, lint commands — so the agent can keep working without hitting permission gates for routine operations.

Be intentional about this. Auto-approving everything defeats the purpose of oversight. Auto-approving npm test and file writes within src/ is usually a reasonable middle ground for a contained task.

Write clear, scoped prompts

Background tasks work best when they’re specific. Compare these two prompts:

Vague: “Clean up the API layer.”

Specific: “Refactor the functions in src/api/users.ts to use the new ApiClient class from src/lib/client.ts. Update the corresponding tests in src/api/__tests__/users.test.ts. Don’t modify any other files.”

The specific version gives the agent a clear finish line and constrains its scope. It’s less likely to wander into unexpected territory or make changes you didn’t anticipate.

Use isolated sessions for risky work

If you’re handing off a task that touches core code, run it in an isolated session. Crystl’s isolated shards create a git worktree for the agent, so it works on its own branch. If the agent goes sideways, you haven’t touched your main working tree. You can review the diff, cherry-pick what’s good, and discard the rest.

How to check in on background agents

The check-in cadence depends on the task complexity and your trust level.

Short tasks (under 10 minutes)

Check in once around the 5-minute mark. The agent is probably either done or stuck.

Medium tasks (10-30 minutes)

Check in every 10 minutes or so. Skim the recent output and look for approval prompts waiting for input, error messages the agent is trying to work around, or scope creep where the agent modifies files you didn’t ask it to touch.

Long tasks (30+ minutes)

These usually mean the task should be broken into smaller pieces. If you do run a long task, check in at 15-minute intervals.

Getting notified instead of polling

Manually checking agents is the biggest friction point. You lose focus context-switching, and you either check too often (wasting time) or too rarely (finding a stalled agent 20 minutes later).

The better approach is getting notified when an agent needs you.

In a basic terminal setup, you can use tools like terminal-notifier on macOS to watch for output patterns, but it’s hacky and fragile.

Crystl solves this natively. When a shard hits an approval prompt or finishes its task, you get a macOS notification. The shard’s status indicator on the Crystal Rail changes color so you can see at a glance what needs attention, even from across the room.

This turns background agents from a “poll and hope” workflow into a genuine notification-driven one. You work on something else — another shard, your editor, a different app entirely — and Crystl tells you when to come back.

Reviewing background work

When a background agent finishes, don’t just accept the output. Review it like you’d review a pull request:

1. Read the conversation. Skim the agent’s reasoning and decisions. Crystl’s conversation history makes this easy — you can scroll through the full session and see every decision the agent made.
2. Check the diff. Look at what files changed and whether the changes match what you asked for.
3. Run the tests. If the agent wrote or modified tests, run them. If it didn’t, consider whether tests are needed for the changes it made.
4. Look for shortcuts. Agents sometimes take expedient approaches — hardcoded values, skipped edge cases, TODO comments. These are fine for a first pass but should be caught before merging.

The key insight

Running Claude Code in the background isn’t about fire-and-forget. It’s about reducing the time between when an agent needs you and when you respond. Tight feedback loops mean agents spend less time stalled and more time working.

Whether you use notifications, status dashboards, or just a disciplined check-in schedule, the goal is the same: let the agent do its thing, but stay close enough to keep it on track.

Get started with Crystl at crystl.dev/login to see how purpose-built agent monitoring changes the workflow.