Your Claude Code Session Is a Process

You know the moment. One Claude Code session is deep in a refactor and you are watching it work. There is a flaky test you could be chasing and a README nobody has touched, but the terminal is busy, so you wait.

Why this is worth knowing

Most engineering work has a queue behind it: the upgrade nobody has time for, the test that fails one run in ten. A session you have to watch clears one item at a time. A session that runs as a process lets you hand off the bounded tasks and keep your attention for the one that needs judgment.

Three places that fits:

  • Education. You stay on a grading-sync bug with the learning management system. One background agent writes tests for the quiz-scoring rules, and another works through accessibility fixes on the course pages before the term starts.
  • Healthcare data. A new partner feed needs a mapping change. One agent writes fixture-based tests for the transform, another updates the data dictionary, and --exec runs the long validation suite as a plain job beside them.
  • Marketing. A campaign launches Friday and you own the landing page. One agent audits the site for broken tracking parameters, and another migrates the old email templates to the new component library.

In each case the tasks are small, separable and easy to review afterwards. That is the shape background agents handle well.

Tooling you can build on top

Processes with IDs and machine-readable state can be scripted. claude --bg prints an ID, claude agents --json reports each job’s state, and a blocked job says what it is waiting for. That is enough to build developer tooling on.

The real example is the one behind this post. To run the walkthrough below, I ended up with a small shell script that launches three jobs, captures their IDs, polls the JSON every five seconds, and stops to tell me when a job needs an answer. Then it checks which worktree each agent wrote to and logs the lot.

The same pattern stretches further: a dispatcher that starts one agent per small ticket, or a watcher that messages you the moment a job reports waitingFor. One caution: agent view is still labelled a research preview, and the docs don’t promise the JSON output is stable, so treat the field names as something to re-check after an update. For pipelines with no human in the loop, headless mode and the Agent SDK are the purpose-built routes.

A session is a process

A Claude Code session is now a process: something a supervisor starts, tracks by ID and keeps running whether or not a terminal is attached. A chat window is somewhere you sit. A process is something you start, check on and come back to. Most of us still treat a session as the first kind of thing.

If you know ps, fg, kill and nohup, you already have the vocabulary.

Unix Claude Code What it does
cmd & claude --bg "<task>" Start a job and get the terminal back
ps claude agents --json List sessions (--all adds finished ones)
tail claude logs <id> Recent output, without attaching
fg claude attach <id> Bring a session into this terminal
kill claude stop <id> Stop it; the conversation is kept
systemctl status claude daemon status The supervisor behind all of it

Two commands have no Unix twin. claude respawn <id> restarts a session with its conversation intact, and claude rm <id> takes it off the list while the transcript stays on disk. There is also claude --bg --exec '<cmd>', which runs a plain shell command as a job with no model involved.

What happened when I tried it

I ran this in a scratch git repo holding one Python file, on Claude Code 2.1.325.

Before starting anything, claude daemon status printed not running and exited 1. There is no supervisor until you need one.

claude --bg --name lab-readme "Read calc.py and add a Usage section to README.md with one example per function"

That printed a short ID and the commands for what to do next, and the prompt came back in 0.59 seconds.

I started a second agent to write tests, with --permission-mode default so it would have to ask before running anything, plus a 30-second shell job through --exec. Then I polled claude agents --json. So far what I found:

  • 5 seconds in, the test agent went to blocked, and this time the JSON said why: "waitingFor": "permission prompt".
  • 16 seconds in, the README agent was done.
  • 31 seconds in, the shell job was done.

claude logs on the blocked agent showed the exact prompt: approve a Bash command that writes test_calc.py and runs pytest. It waited. I ran claude attach <id> in a second terminal and said yes, then yes again when it asked to commit. A little over a minute after it first blocked, it was done: six tests, all passing, committed on its own branch. pytest wasn’t installed, so it had run them from a throwaway virtualenv.

Where did the README change go? Not into my checkout. git status in the main folder showed nothing but a new .claude/ directory. git worktree list showed why: each agent had moved into its own worktree under .claude/worktrees/, on its own branch, and git listed both as locked. The README agent committed there as 219995b and told me the git merge command to bring it into main. Nothing was pushed, because the repo has no remote.

claude stop followed by claude respawn brought the finished agent back with its conversation and its done state. It did not redo the work.

Cleanup is where the supervisor pushed back. claude rm removed the shell job and refused both agents, because each worktree had uncommitted changes. The test agent had left an untracked __pycache__/ behind. On an earlier run the refusal was over “2 unpushed commits” that exist on no remote, and it printed the exact --discard-unpushed flag to override it. When the last job settles, the supervisor’s log reads idle 5s with no clients — exiting.

The limits and tradeoffs

  • A job can block on you. A Unix process waits on I/O. An agent waits on a person. Mine was waiting on a permission prompt 5 seconds after launch, and the JSON named the cause. Per the docs, the prompt can only be answered by attaching.
  • A job costs money while it runs. An idle process is free. Per the docs, background sessions draw on your usage the same way interactive ones do, so ten in parallel spend roughly ten times as fast.
  • Jobs share files less than you’d fear. Two processes writing one file is your problem to solve. Here both agents moved into their own worktree before the first edit and my checkout stayed clean. The docs list the exceptions: a session you background from inside a running session stays in your checkout, and outside git there is no isolation. The new chore is the reverse one: finished work sits on a branch until you merge it.
  • nohup stops at the power button. The docs say sessions survive a closed terminal and sleep, and stop on shutdown or restart.

One takeaway, one thing to try

Starting agents is the easy half. The skill is the one that already makes people good with processes: you check on them. & without ps is how an agent ends up parked on a prompt nobody is looking at.

Today, take the next task that will run longer than a couple of minutes and start it with --bg. Then, before you walk away:

claude agents --json
claude logs <id>

Look at the state first. The tools won’t make you check. That part is still yours.

What was the first thing your background agents got stuck on?

Commands checked against the Claude Code CLI reference and agent view docs on 2026-11-15, and run on 2.1.325. Agent view is a research preview, so expect details to move.