Background sessions with Claude agents: run long tasks without blocking your terminal

You start a bigger task, a migration, a test refactor, a documentation pass across twenty files, and then you sit there watching your terminal work. For an hour. During that time the session is occupied, you cannot do anything else, and if you close the window the work is gone. That is exactly what the claude agents command is for. It dispatches a session into the background, gives you your terminal back immediately and lets Claude keep working while you sit on something else. Later you pull the session back with --resume, look in, give feedback, carry on. We will set that up now and I will show you the traps that cost me time at the start.

Step 1, get the difference between interactive and dispatched

A normal Claude Code session is interactive. You type, Claude answers, you wait, you type again. That is good for work where you want to stay close. A background session is different. You give it a job, it runs off, and you are out of the loop until you open it again. The command for it is claude agents. It dispatches one or more sessions that run in the background, with their own defaults for model, effort and permissions.

Important for expectation management: background does not mean autonomous-and-forget. You pass the permission rules along, and anything you have not allowed still waits for you. A background session that gets stuck on every git push because you set no permission has bought you nothing. Half the work in this playbook is therefore setting the defaults so the session actually runs through.

Step 2, dispatch your first background session

Getting in is a single command. You give claude agents the model and effort you want, and a clear job.

claude agents --model sonnet --effort medium

The officially documented flags for claude agents are --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort and --dangerously-skip-permissions. They set the defaults for the dispatched session. Rule of thumb for the start: take --model sonnet for normal work, --effort medium, and keep your hands off --dangerously-skip-permissions until you understand what the session touches. The reason is in step 7.

Step 3, give the session a name instead of a cryptic ID

Background sessions get a session ID. It is unique, but nobody remembers a3f9c1e2-.... Inside a session you can rename it with /rename, and then you pull it back later by name instead of by ID.

/rename test-refactor-june

Do that right at the start of every background session that runs longer than a few minutes. When you have three of them in parallel, the difference between "which one was the one with the tests again" and a clear name is exactly the difference between relaxed and annoyed.

Step 4, pull the session back with resume

This is the core. A background session keeps working while you are away, and when you want to look in, you pull it back. Three commands worth remembering:

# A specific session by its ID
claude --resume <session-id>

# A named session in print mode
claude -p --resume test-refactor-june

# Simply continue the last session
claude --continue

--resume with ID or name opens exactly the session you want. --continue takes the last one. Print mode -p gives you the answer straight on stdout instead of in the interactive interface, which is handy when you only want a quick look at the state without jumping into the session.

Step 5, let background sessions work in the right directory

By default Claude Code isolates background sessions in a git worktree, so they do not pull your working copy out from under you while you are typing in the repo yourself. That is usually right. Sometimes it is in the way, for example in repos where worktrees are awkward or where the build pipeline has trouble with two working copies.

For that there is the worktree.bgIsolation setting in your settings.json. Set it to "none" and the background session may edit directly in the working copy instead of an isolated worktree.

{
  "worktree": {
    "bgIsolation": "none"
  }
}

My advice: leave the isolation on as long as you work in the repo yourself in parallel. Only switch it off when you have exactly one reason to and know that no second session is touching the same files at the same time. Two processes writing into the same working copy without coordination is the fastest route to a merge mess you get to clean up by hand.

Step 6, give the session its context via a SessionStart hook

A background session starts cold. It does not know what you know, beyond what is in CLAUDE.md. If you want it to run off with the right context, without typing that into the prompt every time, use the SessionStart hook. It fires when a session begins and can load context, set an environment or pull a note out of your memory.

A minimal SessionStart hook in settings.json looks like this:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "cat .claude/context-brief.md" }
        ]
      }
    ]
  }
}

The output lands in the context of the starting session. In our setup the hook loads a short brief with the current state, so every background session immediately knows which project it is in and which rules apply. If you have not set that up in the Academy yet, read the lesson on hooks and skills first, they belong together.

Step 7, be careful with dangerously-skip-permissions in the background

--dangerously-skip-permissions waves every tool call through blind. In an interactive session that is already risky, because a poisoned package or a prompt injection takes exactly that door. In a background session it is worse, because you are not sitting next to it. The session fires rm, npm install and git push without you noticing at the time.

The better route is --permission-mode with a considered permission allowlist in your settings. Explicitly allow the commands the task needs and let the rest be blocked. If the session then hangs on a disallowed action, you pull it back with --resume, look at what it wanted and decide. That is one minute of extra effort and saves you the day a background session breaks something you only see two hours later. If you want to secure bash commands in general, look at the playbook on the bash sandbox, it complements this well.

Step 8, dispatch several sessions for parallel work

The real leverage comes when you run several background sessions in parallel. One writes tests, one does the documentation update, one cleans up a module. Each gets its own name via /rename, its own defaults at dispatch, and you collect the results when they are done.

The important part: give every session a sharply bounded job. Three sessions all fiddling with the same module step on each other, especially when you have switched off the worktree isolation from step 5. Three sessions working on three different corners are real parallelism. The pattern is the same as with parallel interactive sessions using git worktrees, except you are not sitting in each of them yourself.

Step 9, build yourself a collection routine

Background sessions have a blind spot. If you do not look in, you do not know whether they are done, blocked or have run off in the wrong direction. My setup against that is simple: once in the morning and once in the late afternoon I go through the open sessions. --resume in, read the state, give feedback or approve, out.

If you want to automate that, combine it with the scheduled routines from the corresponding playbook. A routine that sends you a short overview of the running sessions twice a day into a chat or as a notification takes the chasing off your hands. The point is not the technology, the point is the habit. A background session nobody collects is a session you might as well not have started.

Step 10, clean up and name consistently

After a few days with background sessions you have a list of old sessions doing nothing. Go through them, pull the finished ones in once with --resume to be sure nothing is open, then leave them be. What remains is discipline in naming. A consistent naming convention, for example task-module-date, makes the difference between a usable session list and a heap of cryptic IDs.

My mistake at the start was running everything through --continue because it is the most convenient. Then I had three background sessions and --continue always took the most recently touched one, not the one I meant. Since then I rename every session that lives longer than ten minutes immediately with /rename and pull it back by name. Sounds like a small thing, but it is the difference between "I know what is running" and "why did that one change this now".

What next

Once background sessions are solid, the next logical step is the headless setup for CI/CD, so Claude Code entirely without a terminal in a pipeline. There is a separate playbook for that. And if you start running several sessions in parallel, read the playbook on parallel sessions with git worktrees, it explains the isolation from step 5 in more detail. Level 5 in the Academy is about the CEO worker pattern, which is the next stage when you want not only to run sessions in parallel but also to coordinate them.

Source

Specs verified against the official Claude Code CHANGELOG and the CLI reference:

• Claude Code CHANGELOG (claude agents flags, worktree.bgIsolation, resume by ID and name): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Claude Code CLI reference: https://code.claude.com/docs/en/cli-reference
• SessionStart hook: https://code.claude.com/docs/en/hooks