agent-teams
Coordinating Multi-Agent Collaboration for Claude via a Filesystem Protocol
Install & Use
Copy this prompt and send it to your AI assistant (Claude / Cursor / TRAE / Codex / WorkBuddy etc.) to auto-install:
Help me install this AI Skill: agent-teams. It is used for: Coordinating Multi-Agent Collaboration for Claude via a Filesystem Protocol Full Skill content: https://321skill.com/skills/agent-teams/raw/index.md Read that page and install it.
The prompt includes a link to the full Skill content. You can also view the full content.
This Skill addresses the inefficiency in coordinating multiple Claude agents during parallel development. In practice, developers often need to handle multiple files, modules, or subsystems simultaneously, but a single Claude session is limited by context length and sequential execution, making parallel progress difficult. By leveraging a filesystem protocol and tmux panes, each agent runs independently, communicating via JSON files with fcntl locks—eliminating the need for a database or network layer—to achieve loosely coupled multi-agent team collaboration.
Usage is straightforward: first, create a team configuration (written to ~/.claude/teams/), then launch separate claude processes for each agent by specifying identity flags (e.g., --agent-id, --team-name). You can then assign tasks using natural language instructions, such as "Have the frontend agent implement the user login component while the backend agent designs the API interface simultaneously." Agents automatically poll their own inboxes, read task files, execute them, and write results back to the task files.
It is particularly well-suited for teams or individuals who need to process multiple code modules in parallel, especially those already using the Claude CLI for daily development and looking to overcome single-session limitations. It significantly reduces overall development time for scenarios like large-scale refactoring, cross-file code reviews, and parallel implementation of multiple modules. It also fits project managers who need to orchestrate multiple AI agents for complex workflows.
Before use, ensure tmux and the Claude CLI are installed, and set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Note that it is primarily effective for tasks that can be decomposed for parallel execution; it performs poorly on tasks requiring strong sequential reasoning (e.g., step-by-step algorithm derivation). Additionally, due to the filesystem polling approach, response latency is relatively high, making it unsuitable for real-time interactive scenarios.
Key Features
Unlike using a single Claude session directly, Agent Teams support true parallel execution: each agent runs independently in a tmux pane, with file consistency ensured via fcntl locks, eliminating the need for centralized scheduling or network message queues as seen in frameworks like LangChain's AgentExecutor.
Limitations
Requires installation of tmux and the Claude CLI; relies on fcntl file locks for concurrency control; the loosely coupled polling mechanism results in relatively high response latency, making it unsuitable for collaboration scenarios requiring real-time interaction.
FAQ
How do I create and start an Agent team?
Write a team configuration file to `~/.claude/teams/<team-name>/config.json`, defining the member list and roles; then launch a separate claude process for each member, passing parameters like `--agent-id` and `--team-name`. The system will automatically create inboxes and task queues.
How do Agents communicate with each other?
They communicate by writing JSON messages to the filesystem. Each agent has its own inbox file (`inboxes/<agent-name>.json`), and fcntl locks are used to prevent concurrent read/write conflicts. Task files are named with sequential auto-incrementing IDs, and agents poll for new task files to process.
Installation guide for AI assistants
If your AI coding assistant (Claude Code, Cursor, TRAE etc.) can see this page, send it this message to auto-install:
Visit https://321skill.com/skills/agent-teams/raw/index.md to read the original Skill definition (Markdown format) for agent-teams, and install it according to the instructions.
Raw Markdown URL for AI: /skills/agent-teams/raw/index.md