Managing claude agents

Background agents are sessions managed by the Claude Code daemon. There are two data sources.

1. The CLI, which is stable, so prefer it: claude agents --json lists live sessions (interactive and background) with pid, id, name, status (busy/waiting/idle), state (working/blocked/done), sessionId, cwd, and startedAt. Add --all to include completed background sessions. Works without a TTY.
2. The files, which are the source of truth for names and cleanup: one directory per job under the jobs root. Resolve paths portably:

CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
JOBS_DIR="$CONFIG_DIR/jobs"            # $JOBS_DIR/<8-char-id>/{state.json,timeline.jsonl,tmp/}
PROJECTS_DIR="$CONFIG_DIR/projects"    # transcripts live here (see below)

Stopping a running job goes through a third channel, the daemon's control socket; see "Stop a running agent" below.

The state.json fields that matter: state (working/blocked/done, plus stopped after a daemon-level kill), name, nameSource (auto/user), detail (last user message or status line), output (final result for done jobs), sessionId, intent (original prompt), cwd, createdAt/updatedAt.

A job's full conversation transcript is not in the job dir. It lives at: