Claude Code agents: subagents, background agents and fleets

Four kinds of Claude Code agent

"Agent" means several things in Claude Code. They differ in where they run, how long they live and who coordinates them.

Subagents

A subagent is a specialist Claude can hand a job to. It runs in its own context window with its own system prompt, tools and permissions, and only its summary comes back to your conversation. That keeps your main context clean when the job involves reading a lot.

Where subagents live

Subagents are Markdown files with YAML frontmatter:

• .claude/agents/ in the project, for agents the team shares through git
• ~/.claude/agents/ for your own agents across every project
• a plugin's agents/ folder, or --agents JSON for one session

When names collide, the project wins over your user folder, and both lose to managed settings.

Writing one

Only name and description are required:

---
name: test-runner
description: Runs the test suite and fixes failing tests. Use proactively after code changes.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

Run the tests. For each failure, find the cause, fix it and run the tests again.
Report what failed, what you changed and the final result.

Claude delegates on the strength of the description; "use proactively" encourages it. You can also call one by name ("use the test-runner subagent"), mention it with @agent-test-runner, or run a whole session as it with claude --agent test-runner. Useful optional fields include tools and disallowedTools, model (sonnet, opus, haiku or inherit), permissionMode, effort, background and isolation: worktree, which gives the subagent its own temporary git worktree.

Claude Code also ships built-in subagents: Explore (fast, read-only search), Plan (read-only research in plan mode) and general-purpose.

Background sessions

A background session is a whole Claude Code session that runs without a terminal attached:

claude --bg "Fix the flaky date test in billing and open a PR"

It prints a short id and returns at once. Then:

• claude agents lists your sessions, and claude agents --json prints them for scripts
• claude attach <id> opens one in your terminal
• claude logs <id> prints its recent output
• claude stop <id> stops it, and claude rm <id> deletes it and its worktree when that is safe

Combine it with --worktree so each background session edits its own checkout, and pick the model and effort per session with --model and --effort.

Permissions

A session that runs while you are away still asks before risky steps. Choose a permission mode with --permission-mode: plan (read and propose only), acceptEdits (edits without asking), auto (a classifier approves routine actions), dontAsk (only pre-approved tools) or bypassPermissions, which Anthropic recommends only in sandboxes without internet access. Pre-approve the commands you trust with --allowedTools or permissions.allow in settings, and deny the rest.

Agent teams

Agent teams, still experimental, let a lead session spawn teammates that share a task list and message each other. They suit research, review and work that splits cleanly by file. Claude Code agent teams covers them in full.

Fleets: background agents that take work from a board

Subagents, background sessions and teams all answer "how does Claude do this job". None of them answers "which job is next, and who is already on it". With one session that question is easy. With five, across two machines and a colleague, it is the whole problem.

A fleet answers it by putting a board in charge. The Projectify fleet works like this:

1. You switch the fleet on for a project in the Projectify web app. Projects start with it off.
2. You run projectify fleet in a terminal. It waits on the board without spending tokens.
3. When a task is ready, unblocked and unclaimed, it starts a worker: claude --bg --worktree with the Projectify worker agent, in that project's repo.
4. The worker claims the task with its worktree and branch, follows the project's workflow, pushes the branch, opens a pull request with gh and moves the task to Review with a handoff. It never merges.
5. A Reviewer reads the PR and runs the repo's checks; changes go back to a developer on the same branch. A Coordinator answers workers' questions and approvals within the policy you set per project, and leaves the rest for you in Needs you.

Each role can have its own model and effort, set per project or as your own defaults. Workers run on your machine and your Claude plan: Projectify never runs Claude itself. Run Claude Code overnight is the step-by-step.

Which one to use

• One focused job inside your session: a subagent.
• A job you want off your terminal: claude --bg, ideally with --worktree.
• A burst of parallel thinking with discussion: an agent team.
• A backlog worked through while you do something else, with a record of who did what: a fleet on a board.

Projectify Solo is free for one person with every feature, the fleet included, and agents never take a seat.