How to install and use Claude Code Agent Teams (Reverse-engineered)

Key Concepts

• Cloud Code Agent Teams: A feature allowing multiple, collaborative AI agent sessions to work on a single project.
• Sub-agent vs. Agent Teams: Unlike the previous single-task sub-agent model, Agent Teams allow for persistent, multi-agent communication and shared task management.
• Task Orchestration: The use of team create, task create, and task update tools to manage dependencies and workflows.
• Communication Protocols: Methods including direct messaging, broadcasting, and shared inbox management.
• Observability: Using tools like LangFuse to track LLM calls and agent interactions.

---

1. Installation and Setup

To enable the Agent Teams feature, users must:

1. Update: Ensure Cloud Code is at version 2.1.34 or higher.
2. Configuration: Open settings.json (via code/cloud/settings.json) and set "cloud.code.experimental.agentTeams": 1.
3. Terminal Optimization: For a "Tmux-like" experience, use iTerm 2 (macOS) with the Python API enabled. Run the command cloud-teammate-mode tmux to view multiple agent sessions in a split-screen layout, allowing real-time monitoring of each agent's actions.

---

2. The Agent Team Framework: Step-by-Step Process

The architecture of Agent Teams is significantly more complex than previous iterations, involving a structured lifecycle:

• Step 1: Team Creation (team create): The main agent initializes a team, creating a configuration file in .cloud/teams. This defines the team structure and identifies the "Team Lead."
• Step 2: Task Definition (task create): Tasks are logged in the .cloud/task folder as individual JSON files. Each file tracks subject, description, status (pending, in progress, complete, deleted), and dependency metadata (blocked / blocked by).
• Step 3: Execution: The task tool is invoked to spin up new Cloud Code sessions. These sessions inherit the team ID and task list, allowing them to operate autonomously while remaining connected to the team context.
• Step 4: Communication: Agents use the send message tool to communicate. Methods include:
  • Message: One-on-one communication.
  • Broadcast: Sending information to all team members.
• Step 5: Termination: The Team Lead uses a shutdown request to terminate sub-agent sessions, followed by a team delete tool to clean up the entire team environment.

---

3. Communication and Context Sharing

Communication is handled via an Inbox folder within the .cloud/teams directory. Each agent has an inbox that tracks read status. When a message is sent, it is injected into the recipient's conversation history with a teammate message tag, allowing the receiving agent to process the new information and decide on the next logical step.

---

4. Real-World Application: Complex Debugging

The author highlights a "Scientific Debate" model for debugging deep-seated code issues:

• Methodology: Instead of one agent finding a single explanation, the user spins up five agents to investigate different hypotheses.
• Process: Agents use the broadcast tool to share findings and the write memory tool to document consensus. They actively critique and disprove each other's theories.
• Outcome: This collaborative approach results in a more comprehensive, verified solution compared to the linear, often limited, output of a single sub-agent.

---

5. Observability and Monitoring

Because standard tracing tools like "Cloud Trace" are currently incompatible with the latest Cloud Code, the author recommends LangFuse. By utilizing the Cloud Code "stop hook," LangFuse automatically synchronizes data after each session, providing visibility into the system prompts, tools accessed, and the data flow between agents.

---

Synthesis and Conclusion

The transition from single sub-agents to Agent Teams represents a shift toward multi-agent orchestration. By enabling agents to share context, manage dependencies, and engage in peer-to-peer debate, Cloud Code has moved closer to simulating a human development team. The primary takeaway is that Agent Teams are best utilized for complex, multi-faceted problems where diverse perspectives and iterative verification are required to reach a high-quality outcome. Users are encouraged to experiment with these collaborative workflows to unlock new levels of autonomous problem-solving.