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

genie team create auth-fix --repo . --wish auth-bug
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 workers
$ genie team create auth-fix --repo . --wish auth-bug
✅ Team "auth-fix" created
  Worktree: ~/.genie/worktrees/myapp/auth-fix
  Branch:   team/auth-fix (from dev)
  Wish:     auth-bug
  Leader spawned with wish context.

​
Team Structure

Every team has a hierarchy: 
team-lead
├── engineer (Group 1)
├── engineer (Group 2)
├── reviewer
└── qa
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: 
~/.genie/worktrees/<repo>/<team-name>/
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

create → active → [review] → done/disbanded
PhaseWhat happens
CreateWorktree created, team-lead spawned
ActiveEngineers working on execution groups
ReviewWork complete, reviewer validating
DonePR created, team can be disbanded
DisbandedWorktree removed, agents stopped

​
Managing Teams

For full command details, see the Team CLI reference. 
genie team ls                          # List active teams
genie team hire engineer --team auth   # Add an agent to a team
genie team fire engineer --team auth   # Remove an agent
genie team done auth                   # Mark team work complete
genie team disband auth                # Remove team and worktree

​
Communication Within Teams

​
Direct Messages

Send a message to a specific agent: 
genie send 'focus on the API layer first' --to engineer --team auth

​
Team Broadcast

Message all team members: 
genie send 'switching to review phase' --to team --team auth

​
Reading Team Chat

genie chat --team auth
Team chat is stored in .genie/chat/<team>.jsonl — a newline-delimited JSON log of all messages.

​
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: 
~/.claude/teams/<team>/config.json
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

StateLocationPurpose
Team configPostgreSQL teams tableTeam metadata and member list
Worker registryPostgreSQL agents tableAgent status and tmux sessions
Team chatPostgreSQL team_chat tableMessage history
Wish statePostgreSQL tasks + task_dependenciesExecution progress

​
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.