Subagent, background session, or agent team: three things people conflate

In Claude Code

3 of these are there.

Subagent. Agents (subagents), which is also the name of a CLI command, are Markdown files with YAML frontmatter. You can find these in .claude/agents/ (project level) or ~/.claude/agents/ (user level). These are 2 out of 5 scopes and the only 2 you'd want to define on your own. They require name and description fields defined in the frontmatter, with the body being the system prompt for it. The description is also a piece of information Claude uses to decide whether to hand off the session to an agent. In general, you can define your subagents like this:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Two frontmatter fields matter here: you can set background to true so the subagent works in the background without blocking, and also isolation: worktree so it can use a disposable copy of the repository.

Background session. When it comes to background sessions, you can run them with:

• claude --bg "..." which launches one and returns the control to you instantly

• claude agents which shows a list view

• claude attach, claude logs, claude stop which behave as their names suggest

• /bg which detaches the current session (from within it)

• /fork which forks the current session into another one (concurrently)

Agent team. The agent teams are an experimental feature that you can try if you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. If enabled, a lead session can create teammates by sharing a task list and a mailbox with them. You can message a teammate directly (no need to go through the lead).

The /agents slash command and claude agents are not the same feature, and the docs say so outright — the former is about subagent definition files (from v2.1.198 it only prints their paths as it doesn't run the wizard anymore), while the latter is about background sessions.

It's also worth mentioning that the "Task" tool was renamed to "Agent" in v2.1.63, so in older articles you might come across this name which nowadays is just an alias for the same tool. Also, --tmux flag goes with --worktree, not with teams (which use --teammate-mode).

When it comes to worktrees — the way they're handled varies if you're parallelising sessions: in case of background sessions, a worktree gets automatically created, while for agent teams no worktree is set up and you need to split your files manually as described in the official docs.

In Codex CLI

Subagents are a thing, but there's no such thing as local "detached" sessions, and the "team" concept doesn't exist.

Subagent. Subagent is just another word for an agent — it's a single TOML file per agent, located under ~/.codex/agents/ (at the user level) or .codex/agents/ (at the project level). It must contain the following keys: name, description and developer_instructions; you can layer further config keys on top if needed. Here's an example of a TOML file defining a PR reviewer agent with its model, effort, sandbox mode, and instructions:

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""

The thing is, this agents directory isn't created automatically; you need to create it manually. There are also three built-in subagents that come preinstalled with the Codex CLI: default, worker, and explorer, so even if you've been running Codex for months you might not have the agents directory at all, as there's nothing that needs to go in it.

Background. The thing is, there's the /ps subcommand in Codex that lists background terminals and their last output (which are just regular shell processes), but there's also the /stop subcommand that stops them. But there's no way to detach a live interactive session described in the documentation. Instead, you can either use codex exec for non-interactive runs (letting the user background it with their shell) or codex cloud (which is an isolated cloud environment in which you run the code; after it finishes, it returns a diff that you then apply with codex cloud apply).

The shipped 0.146.0 labels codex cloud experimental in its own help text, just so you know what you're reaching for.

Team. There's no such thing as "team" in the context of agents in the Codex docs. The machinery is real though — it's a feature called features.multi_agent, enabled by default, and its documented description is the one place the tools get named:

• spawn_agent

• send_input

• resume_agent

• wait_agent

• close_agent

In the documentation, it's also said that Codex is responsible for orchestrating this by spawning new threads, forwarding your next steps there, waiting for the results, and then closing them. That means that subagents are not something you can directly address; they're something you ask Codex about.

There's the /agent subcommand in Codex which switches which agent thread is currently visible.

Codex is also the one that stretches this whole framing furthest, as a subagent here is really a separate persisted thread with a recorded edge to its parent, rather than a temporary context sitting inside it. What makes it a subagent rather than a second session is that edge, plus the fact that only the parent gets to talk to it.

You can just ask: "Can you create three subagents for me and analyse the security risks, what needs to be tested and what to do to make this more maintainable? Then wait for them to finish and summarise their findings per category"

In Cursor

Cursor is the tidiest of the lot — three separate things that have three distinct names and point to three different doc pages. The only complication is at the end.

Subagents

The first mechanism — a subagent defined as a markdown file with YAML frontmatter placed under .cursor/agents/ or ~/.cursor/agents/. The following frontmatter fields: name, description, model, readonly, is_background. For example, here's how we could define a security-review specialist, that we'd invoke for authentication, payments and sensitive data workflows, with the inherited model and the read-only flag:

---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
model: inherit
readonly: true
---

You are a security expert auditing code for vulnerabilities.

There are also three built-ins that you don't need to configure — Explore, Bash, Browser. The main reason behind them is to get rid of the parent conversation's noise by moving it to sub-conversations, but Cursor also mentions a few more: choice of the model, limited toolset, cost. If you were wondering how they were picked — Cursor says it analysed the conversations that hit the context limit and built them from that.

Cloud Agents

The second mechanism are Cloud Agents (formerly known as Background Agents). These are whole sessions rather than subagents, and the reason why it's so confusing is that the doc page about them still asks "What are background agents?", answering that their name in Cursor is "Cloud Agents". What they do is creating a new VM for each of them with the repository cloned, and creating a PR on completion.

Multi-agent

The third one is multi-agent, which is the Agents Window combined with /multitask, allowing to run subagents asynchronously (rather than queuing requests).

There's also this — setting is_background: true marks a subagent as non-blocking, so "background" is both an attribute of a subagent and a name of another product.

Which means that the same company, same word, two meanings — it's natural some of the confusion comes from that. Also, .claude/agents/ and .codex/agents/ are compatibility paths as well; if there's a subagent defined under .cursor/ with the same name, it'll be used instead.

In Antigravity CLI

Subagents. They are defined in Markdown files with YAML frontmatter, in two scopes:

• project scope — .agents/agents/<name>.md or .agents/agents/<name>/agent.md, at the root of your repository

• global scope — ~/.gemini/config/agents/, not ~/.agents/

In CLI 1.1.0 Google have corrected their own panel by fixing the global path; ~/.gemini/antigravity-cli/ is actually the runtime storage, and agents placed there are not being picked up.

Here's an example of an agent definition file: name and description in the frontmatter, system prompt as body.

---
name: code-reviewer
description: Rigorous code review specialist focusing on edge cases and security.
---

You are an expert code reviewer. Analyze diffs carefully and verify edge cases.

Note that agy agents (non-interactive) shows only the content of the global directory; on 1.1.9 in a repo even workspace agents weren't there — so an empty list doesn't mean it's malformed.

They can also be defined within a plugin, and are invoked via the invoke_subagent tool by the parent agent — there's no subagent creation command from the user perspective.

The only things you can configure for them are the description the planner sees and the prompt, nothing else.

They start with an empty context, and don't inherit the history of their parent; if you were to change the primary agent mid-conversation in the /agents panel you'd fork it instead, so you keep your context. Same panel, opposite semantics.

Background tasks. The /tasks panel is actually the Task Manager, keeping track of background processes started from the terminal; the /agents panel is for agents.

You can ask a single background question without interrupting the main thread using /btw, and it appears under /tasks, not under /agents.

There's no documented flag that forces something into the background, the planner decides.

Teams. Not documented for the CLI surface; the only place where you can find /teamwork-preview is the subagents page on the platform, for the Ultra plan, and marked as preview.

That being said, we see that it's implemented in the binary, but Google haven't shared anything about it for the CLI.

They have documented the inter-agent messaging, and the CLI docs point to this section: agents communicating via conversation IDs, waking up each other with a message, being able to access each other's transcripts. That's the only harness here where they're actually peer-addressable, but from the prompt it's not possible for you.

In Kimi Code CLI

Make sure to differentiate which CLI you use. The Python-based one (kimi-cli) is being wound down in favour of the Node rewrite, called Kimi Code CLI. But, the legacy documentation site still uses "Kimi Code CLI" in the text, so always base your decision on the URL path rather than the product name. If you use the Python-based one, you can migrate to the new one using kimi migrate, which will port over your config and sessions, or via /upgrade (from within the old tool), which does both — installing the new one and migrating at once.

In the new one, these are three separate features: none of them is a slash command that launches a subagent.

Sub-agents. In the new Kimi Code CLI there's the Agent tool, which provides three predefined types of sub-agents: coder, explore, plan. The main agent decides autonomously when to use them, but you can also ask it to invoke one using natural language — for example asking explore to examine the relevant files before the actual changes. Each of these sub-agents operates in a separate isolated context window and doesn't have access to the history of the main conversation. If you want to, you can also run them asynchronously using run_in_background param against the same tool — this will return the task ID immediately, rather than waiting for the result.

Background tasks. The new Kimi Code CLI introduces a few ways to interact with background tasks:

• Ctrl+B to send the currently running command or sub-agent to the background

• /tasks to list all of them

• A couple of tools — TaskList, TaskOutput and TaskStop — that let you control these tasks

Swarm. You can enable the swarm mode by either running /swarm on, or using /swarm <task> to enable it and pass a prompt in one go. This way, you're provided with the AgentSwarm tool, which is a single prompt template, with an array of items as its parameter. You need to provide at least two items when starting a new swarm, but not when resuming one (as it's based on the previous run). You can't exceed 128 sub-agents. Whenever you enable the swarm, 5 of them are launched straight away and then another one is being added every 700ms; the process ends automatically once all of them are done. Until this point, it waits for every sub-agent to finish and returns a single combined report at the end. For example, you can run

/swarm Audit each service in services/ for missing timeout handling

which will go through every service under services/ and check if it doesn't have a timeout handling in place.

The last thing is that swarm is a feature about running multiple things in parallel (fan-out); it's not the sub-agents feature itself, as they still report up. There's no team structure there, and no mailbox for communicating between agents.