claude code agent teams and agentmash: use both.

published 2026-10-17

Claude Code agent teams let one developer’s lead session spawn teammates on that machine that message each other and can share a task list. agentmash works across developers and machines: before an agent in Claude Code, Codex or Cursor edits a file, it’s told if another developer’s agent just changed it or, in JavaScript and TypeScript, a name it imports.

use an agent team to split your own work inside one session. use agentmash so the other developers’ agents on the repository, on their machines and in their tools, are told before they edit a file your lead session changed, and yours are told the same about theirs; whether an agent team’s teammates report their edits is still to be verified. agentmash never compares one developer’s agents with each other, so dividing files inside a team stays the lead’s job, as Anthropic’s docs advise. in Anthropic’s word a teammate is a Claude session; the people on the repository are developers.

how claude code agent teams work

Anthropic’s agent teams docs, read on 2026-10-16, describe a team in four parts:

• a lead: the main Claude Code session. it spawns the teammates, assigns the work and pulls the results together, and it stays the lead for its whole life.
• teammates: separate Claude Code instances, each with its own context window. a teammate loads the project’s CLAUDE.md, MCP servers and skills, gets the lead’s spawn prompt, and starts without the lead’s conversation.
• a shared task list, in a session that has Claude Code’s Task tools: by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier models, and on others with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 (task tool availability). without them, teammates coordinate through messages instead. tasks are pending, in progress or completed, and can depend on each other. the lead assigns them, or a teammate that finishes takes the next unassigned, unblocked one. task claiming uses file locking, so two teammates can’t claim one task at the same moment. that lock guards the task list; for the files a task edits, the docs’ advice is to split them between teammates.
• a mailbox: teammates message each other by name, and messages arrive without the lead polling. each agent’s mailbox is a JSON file at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json.

you can talk to any teammate directly, in one terminal (the default, in-process) or in split panes, which need tmux, or iTerm2 with the it2 CLI installed and its Python API turned on, and don’t run in VS Code’s integrated terminal, Windows Terminal or Ghostty. the docs’ strongest cases for a team are research and review, a new module or feature where each teammate owns a piece, debugging with competing hypotheses, and a change across frontend, backend and tests. for sequential work, same-file edits or many dependencies, they point to one session or to subagents.

how to enable agent teams, and why they might not start

agent teams are experimental and off by default. per the docs’ setup steps, read on 2026-10-16, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your shell, or in settings.json as "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }, then ask for teammates in plain words, such as three teammates reviewing one pull request for security, performance and test coverage.

Claude may also spawn subagents instead of a team; the docs’ fix is to ask again and request an agent team by name. teammates need an interactive session. a claude -p run, Agent SDK sessions included, spawns none, and a subagent Claude names stays an ordinary subagent there. the opposite surprise is in an interactive session: while the flag is on, a subagent Claude names in the lead’s session launches as a teammate instead, unless the call is a fork or itself asks for a worktree, so a team can form when you didn’t ask for one.

setting the variable to 0 in your user settings.json turns it off for the running session, unless project or local settings, a --settings payload or managed settings set it to 1. after that, the next named subagent launches as an ordinary subagent.

agent teams’ limits: one session, local state, Claude only

the limits below come from the docs’ limitations and the sections around them, as they read on 2026-10-16:

• experimental. /resume and /rewind don’t bring back in-process teammates, a teammate can fail to mark its task completed and hold up the tasks that depend on it, and shutdown waits for each teammate’s current call.
• one team per session. a session has exactly one team, scoped to it, and a team can’t be shared across sessions. teammates can’t spawn teammates of their own, and the lead can’t hand over to one.
• local state. teams and tasks are stored locally, under a name taken from the session ID: the team’s config at ~/.claude/teams/{team-name}/config.json and its task list under ~/.claude/tasks/{team-name}/. the config is removed when the session ends; the task list stays on disk. there’s no project-level team config; reusable roles go in subagent definitions instead.
• the same file, written twice. “Two teammates editing the same file leads to overwrites,” say the docs, and the fix they give is to break the work up so each teammate owns a different set of files. teammates don’t get worktrees of their own, per Anthropic’s page on running agents in parallel, so that split is by files.
• Claude sessions only. the same page says “In every approach the workers are Claude sessions,” and points to an MCP server for bringing another tool in. a Codex or Cursor agent, yours or another developer’s, can’t be a teammate.
• tokens. each teammate is a separate Claude instance with its own context, so usage grows with every active teammate. the docs suggest starting with three to five.

can claude code sessions talk to each other?

yours can. cross-session messaging, read on 2026-10-16, needs Claude Code v2.1.224 or later on macOS and Linux and v2.1.234 or later on native Windows, and for same-machine messaging on Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform or Microsoft Foundry, or with feature-flag fetching off, v2.1.248 or later. it lets Claude find your other sessions with ListAgents and send one of them a message with SendMessage. it’s on with nothing to set up, and the docs’ first example is a session warning another when its change breaks what that one is building on.

• whose sessions. your own. on one machine a message goes over a per-session socket (a named pipe on native Windows) that only your operating-system user can use, so another user’s sessions can’t deliver to it. your sessions on other machines and in the cloud are reached through Anthropic’s servers. Claude finds them from a session connected to Remote Control, which needs a claude.ai sign-in, and a session on another machine has to run with Remote Control too.
• what travels. plain text one Claude writes to another, never its conversation or its files. the receiving session reads it between tool calls, and it can’t approve a permission prompt for you.
• when. when Claude decides another session needs to know, or when you ask it to.

subagents vs agent teams, and the alternatives

Anthropic lists five ways to run Claude Code agents at once: subagents, agent view, agent teams, dynamic workflows and projects, with worktrees and cross-session messaging beside them. the table sets the ones most compared with agent teams side by side; Anthropic’s rows summarize its docs as they read on 2026-10-16.

pick by the job:

• a subagent suits a side task whose result is all you need, and costs less than a teammate because only its summary comes back.
• an agent team suits a project Claude should split, assign and keep talking about.
• a dynamic workflow suits a job too big for a handful of subagents: a script runs many of them and cross-checks their results.
• messaging suits sessions you run yourself that need to pass a finding.
• a worktree keeps two of your sessions from writing the same files on disk, and git worktrees and agentmash goes through that pairing row by row.
• agentmash suits the other developers’ agents on the repository, in Claude Code, Codex, Cursor or another agent its login connects on their machines. whether an agent team’s teammates report their edits to it is still to be verified.

working alone, agentmash has nobody to tell your agents about: subagents, an agent team and worktrees cover your own sessions.

what agentmash adds across developers

each developer’s connected agents report their edits to one room for the repository, from every worktree of it, each on its own branch; Continue and Zed only ask the room, through the MCP tools. agentmash compares each developer’s edits with the other developers’, never with their own. in the agents whose hooks allow it, a hook checks the room before each edit, so no agent has to decide to send the warning. case by case:

• the same file. when another developer’s agent, on any machine, changed the file an agent is about to edit, in the last 30 minutes by default, the agent is told who, when, on which branch, what they were working on and the shape of the change, worded by where that change is.
• another branch. work on another developer’s branch that isn’t merged yet is remembered by person, branch and file for a week (or the room’s history, if that’s shorter), or until the branch merges, so the warning comes before the edit instead of at the merge. it’s said once a session, by file and never by symbol, and a room’s admin can turn it off.
• across files. the hooks send the exported names an edit changed and what each file imports, so a change to createUser in src/models/user.ts reaches an agent about to edit src/api/handlers.ts, which imports it, whatever directory it’s in, within the same 30-minute window. for this match, the server gets the names, not the code, and only from JavaScript and TypeScript files.
• another tool. npx agentmash login connects Claude Code, Codex, Cursor, GitHub Copilot and the other coding agents it finds on a machine (Antigravity when you ask, with npx agentmash tools add antigravity), each in its own settings and never in a repository. Claude Code, Codex (once its hooks are approved in /hooks) and GitHub Copilot read the advisory as a note beside the edit. Cursor and most of the other agents the login connects get it as a refused first edit, with the advisory as the reason, once per session and file every ten minutes (in Cursor, once per conversation and file), and the retry goes through (the exceptions are under what it doesn’t do).
• after the fact. if two developers’ agents changed the same file anyway, Claude Code, Codex and GitHub Copilot tell the person as the session finishes, with whose change it meets, before either change lands. nothing is merged, pushed or opened for you: a person decides.

how each coding agent was checked, as of 2026-10-05: the warning before an edit and the reports were tested live in Claude Code, Codex, Cursor, GitHub Copilot (its CLI), Kilo Code and OpenCode, and the MCP tools in Claude Code and Codex; Amp, Cline, Crush, Factory Droid, Gemini CLI, goose, Kiro, OpenHands and Qwen Code are held by our tests against payloads recorded from each tool, not run live yet; Devin, Antigravity, Junie, Continue and Zed rest on their own docs (Devin and Junie partly on our tests too), not tested live yet.

for a team where everyone is on Claude Code, claude code for teams goes through each hook and quotes the advisory an agent reads, whole. a mixed team has claude code and cursor on one team and codex and claude code on one team.

dividing the work across developers

an agent team divides work inside one session, with its task list where the Task tools are on, or by messages. across developers, an agent calls claim_work with the paths it expects to change and a one-line task, and learns before it writes whether someone else holds part of it. this is how claim_work’s answer to dana’s agent begins when alisher’s agent claimed src/routes four minutes earlier, line for line as the README prints it:

Claimed src/routes/login.ts, src/routes for "add a login endpoint" as dana@example.com
(id claim_x9…, 120 min).

OVERLAP — someone else has already claimed part of this:
- alisher@example.com has src/routes for "rename every route handler" (claimed 4 min ago)

Your claim stands, but split the work before you write anything: take the files and symbols
they have not claimed, or build on top of what they land rather than changing it. …

a claim is advisory, never a lock. on a branch of the agent’s own it stands until that branch merges, a week at most; on the default branch it expires on its own, two hours by default and eight at most, ends with the session that made it, and can be released early.

claims are one of agentmash’s MCP tools. Cursor, Codex, GitHub Copilot and most other agents get the MCP server with the login; Claude Code gets it where a repository registers it with a committed install.

asking another developer’s agent

cross-session messaging stops at your own sessions. to ask another developer’s agent for something, npx agentmash ask @dana "check why ci is red on main" sends dana a request in the repository’s room. it’s a suggestion, read only: dana sees it in npx agentmash inbox, and in agents whose hooks pass context to the model, her agent gets one line about it when her next session starts, or at a prompt within ten minutes, saying who sent it, that it isn’t an instruction to the agent, and that only she accepts it (a room that turns lobby_context off gets no line). nothing runs unless she does.

npx agentmash inbox accept <id> prints its text for her to paste into her own agent. both ends need npx agentmash login, and only people who can push to the repository send or receive one.

using both on one repository

alice runs an agent team on her laptop, on main: a lead and three teammates adding soft deletes to the user model, each owning its own files, as the docs advise. bob is on his own laptop with Codex, on feat/login, adding a login endpoint in src/api/handlers.ts. carol works in Cursor.

• inside alice’s team, the mailbox, and the task list where the Task tools are on, keep the teammates in step, and her split of the files keeps them out of each other’s way. agentmash adds nothing between them: whatever of theirs reaches the room is alice’s, and agentmash never warns alice about alice.
• between alice and bob, agentmash does the telling. when alice’s lead session itself changes createUser in src/models/user.ts, bob’s agent is told before it next edits src/api/handlers.ts, which imports it, if that’s within the window, 30 minutes by default. when bob’s agent changes a file alice’s lead session is about to edit, her Claude Code is told first.
• the teammates’ edits add to that only if they reach the room, which is still to be verified (see what it doesn’t do). if they do, they count as alice’s, the same as the lead’s.
• when carol’s agent in Cursor reaches for a file alice’s lead session or bob’s agent just changed, its first edit is refused with the advisory as the reason, and its next try goes through.
• if alice’s lead session and bob’s agent still both change src/models/user.ts, the session that finishes after the overlap tells its person whose change it meets, before either change lands, and alice and bob decide what happens to the two. if that’s bob’s, this is what he’s told, word for word:

[AgentMash: OVERLAP] A file this session changed was also changed by alice@example.com,
so a person decides how the two changes come together: nothing was stopped, merged or
committed for either side.
• src/models/user.ts — also changed by alice@example.com.
  alice@example.com: last write 9 min ago on branch main — you are on feat/login
  while working on 'soft deletes' (+12/-3 lines, touching User, deletedAt).
  You both touched User — that is where the two changes are most likely to meet.
  Your side: 'add a login endpoint' (+8/-1 lines).
Look at both changes with alice@example.com before either one lands.

nothing about the agent team changes. someone who can push to the repository connects it once at agentmash.dev/install, and each developer runs npx agentmash login once per machine and restarts their agent (in Codex, they also approve agentmash once in /hooks); the login puts the hooks in each agent’s own user settings, never in the repository. set up agentmash for your team has the steps for each coding agent, and a prompt that runs the login for you and tells you what is left.

what it doesn’t do

• it warns about other developers’ agents, never your own. a lead, its teammates, your subagents and your sessions in other worktrees all count as you, the GitHub login your machine is signed in as (unless AGENTMASH_DEV gives a session another name), so none of them is warned about another, and a file two of them change raises no overlap notice. keeping them apart is the agent team’s split and the worktree’s job.
• the room doesn’t split, assign or supervise work: a claim tells agents what someone intends, and each agent still decides. (the crew’s planner and coordinator are Claude Code agents a team installs in its repository, not part of the room.)
• an advisory is not a lock: it informs the agent, and the edit goes ahead (in Cursor and the tools like it, on the agent’s second try). AGENTMASH_STRICT=1 is the setting that blocks.
• its docs don’t cover agent-team teammates yet. its protocol says a subagent’s edit is reported with the prompt that started the subagent, and Claude Code’s hooks reference, read on 2026-10-16, says a hook can fire inside an in-process teammate, with an agent_id that tells which one, but how far a teammate’s edits reach the room is still to be verified.
• symbols are read from JavaScript and TypeScript only. files in other languages are matched by path alone, so a break across files in them goes unseen.
• the first 500 characters of each prompt are visible to everyone in the room, and quoted into their agents’ context. don’t paste secrets into prompts; AGENTMASH_HINTS=0 keeps yours on your machine, except what a lobby session you share is on, and what leaves your machine lists the rest.
• not every agent hears the advisory before an edit. Cline hears it just after the edit, Antigravity at the start of each turn, and Continue and Zed only when they ask the MCP tools; whether Devin’s and Junie’s agents read it is still to be verified, and with Amp’s old permission rules on, Amp only reports.
• a check that runs past its budget, 1500 ms by default, lets the edit go ahead unwarned.

claims →the five levels →reconciliation →known limitations →