Skip to main content
Teams turn “one chat” into a coordinated group of chats.

​
The basics

  • A team is a named group of agent threads.
  • Every team has exactly one lead thread.
  • The lead can add/remove members and broadcast instructions.
  • Members are normal threads with their own context and timelines — they’re just connected.

​
Why teams are useful

  • Parallelism: run research, implementation, review, and docs work at the same time.
  • Specialization: pick different models for different roles.
  • Coordination: send tasks to members and track delivery.
  • Visibility: see what’s happening across the team without switching apps.
Teams aren’t just a UI grouping. Membership changes and lead ownership live in the Rust runtime, and the UI subscribes to those updates. That keeps correctness and performance tied together: team state stays authoritative and delivery tracking stays reliable even when a lot of threads are streaming and tool calls are firing.

​
Typical workflow (high-level)

  1. Create a team chat and choose a lead model.
  2. Add a few specialist members (for example: planner, frontend, reviewer, docs).
  3. Ask the lead to break the work into tasks and delegate.
  4. Review outputs in each member’s thread and in Team Comms.
  5. Have the lead integrate changes and run checks.

​
Native worktree add behavior

When gg_team_manage(add) includes worktree_name, member creation can take different native-worktree paths:
  • worktree_name set and use_existing_worktree omitted/false: gg creates a new native worktree owner session.
  • worktree_name set and use_existing_worktree=true: gg reuses an existing native worktree and the new session is added as a consumer.
  • worktree_name omitted: gg does not request create/reuse for a native worktree.
In the create-new path, gg also checks for .agents/gg/worktree-init.sh in the new worktree checkout and runs it before session creation when present. Reuse and inherited-consumer paths do not run worktree-init. For the exact contract and branch-specific behavior, see Configure: Worktree Init.

​
Roles and permissions

By default, gg keeps team mutation actions conservative:
  • Leads can always add/remove members.
  • You can optionally allow non-leads to add (or remove) members in Preferences.
That opt-in is more than a convenience toggle — it changes the shape of delegation. When non-leads are allowed to manage membership, teams stop feeling “one layer deep.” A member can delegate work by adding another member, who can delegate again, and so on. The organization stays flat (it’s still one team with one lead), but delegation can go arbitrarily deep without the lead becoming a bottleneck. If you want this behavior, enable it in Preferences → General → Team Permissions.

​
Lead notice noise reduction

Team membership notices are now less redundant for the initiating lead:
  • If the effective initiator is the lead, lead-targeted add/remove self-notices are suppressed.
  • Quick spawn also suppresses the extra manual lead notice when it would only notify that same initiating lead session.

​
Tips for smooth coordination

  • Keep tasks small and measurable (“update these three copy strings” beats “improve the UX”).
  • Use model presets so “frontend” always means the same setup.
  • Put repo-specific conventions in Lead Instructions so new members get consistent guidance.