Skip to main content

​
Teams

A team is a group of agents working together on a wish. The team-lead orchestrates, engineers build, reviewers validate — all in isolated git worktrees with shared state.

​
Creating a Team

This command:
  1. Creates a git worktree for isolated work
  2. Spawns a team-lead agent
  3. Registers the team in ~/.genie/teams/<name>.json
  4. The team-lead reads the wish and dispatches agents

​
Team Structure

Every team has a hierarchy:
The team-lead is the orchestrator — it reads the wish, dispatches execution groups to engineers, runs fix loops when review returns FIX-FIRST, and creates the PR when everything passes.

​
Worktree Isolation

Each team works in its own git worktree:
Worktrees provide:
  • Isolation — each team has its own working tree, no merge conflicts between teams
  • Shared state — .genie/ directory is shared via git rev-parse --git-common-dir
  • Clean cleanup — genie team disband removes the worktree

​
Team Lifecycle

​
Managing Teams

For full command details, see the Team CLI reference.

​
Communication Within Teams

​
Direct Messages

Send a message to a specific agent:

​
Team Broadcast

Message all team members:

​
Reading Team Chat

Team chat is stored in the PostgreSQL team_chat table.

​
Autonomous Execution

When a team is created with a wish, the team-lead runs autonomously:
  1. Reads the wish — parses execution groups and dependencies
  2. Dispatches groups — spawns engineers for independent groups in parallel
  3. Monitors progress — checks completion via genie done signals
  4. Runs fix loops — if review returns FIX-FIRST, dispatches fix agents
  5. Creates PR — when review returns SHIP, creates the pull request
The entire flow from genie team create to PR can run without human intervention.

​
Native Teams (Claude Code Integration)

Genie integrates with Claude Code’s native team feature:
Native teams provide:
  • Built-in teammate messaging via SendMessage
  • Shared task lists in ~/.claude/tasks/<team>/
  • Team-wide context through team config
Genie bridges both its own team system and Claude Code native teams, so agents can use either communication channel.

​
Team State

​
Best Practices

Each team should focus on a single wish. If you have multiple wishes, create multiple teams.
Don’t micromanage — the team-lead knows the wish pipeline. Intervene only when blocked.
Worktrees prevent merge conflicts. Two teams working on different wishes in the same repo won’t step on each other.
Teams consume tmux sessions and disk space. Disband after the PR is merged.