Skip to content
Navi

Agent Teams

Overview

Section titled “Overview”

Navi detects and displays Claude Code agent team sessions, showing each teammate’s status inline below the main session. This prevents teammate hook events from corrupting the main session’s status and provides visibility into multi-agent workflows.

Display

Section titled “Display”

When a session has active teammates, team info appears below the session entry:

⚙️ my-project                                     2m ago
  ~/workspace/app
  Team: my-project (3 agents)
    ⚙️ researcher  ⏳ implementer  ✅ tester

Each teammate shows their own status icon and name.

How It Works

Section titled “How It Works”

Hook Integration

Section titled “Hook Integration”

The notify.sh hook reads JSON from stdin to detect teammate events:

{
  "teammate_name": "researcher",
  "team_name": "my-project",
  "hook_event_name": "SubagentStart"
}

Teammate-relevant hook events:

  • SubagentStart — Teammate started, status set to working
  • SubagentStop — Teammate stopped
  • TeammateIdle — Teammate went idle
  • TaskCompleted — Teammate completed a task

Status Routing

Section titled “Status Routing”

The hook script routes events based on whether a teammate_name is present:

  • No teammate: Update the main session status normally
  • With teammate: Update the teammate’s entry in the session JSON under team.agents[]

This prevents a teammate’s “working” or “idle” status from overwriting the main session’s actual status.

Stale Permission Fix

Section titled “Stale Permission Fix”

The PostToolUse event clears stale permission/question icons. Without this, a session could remain stuck showing “permission needed” after the user already approved the action.

Session Data Structure

Section titled “Session Data Structure”
{
  "tmux_session": "my-project",
  "status": "working",
  "message": "Implementing feature X",
  "team": {
    "name": "my-project",
    "agents": [
      {"name": "researcher", "status": "working", "timestamp": 1738972800},
      {"name": "implementer", "status": "idle", "timestamp": 1738972850},
      {"name": "tester", "status": "done", "timestamp": 1738972900}
    ]
  }
}

Session Sorting

Section titled “Session Sorting”

Sessions with teammates that need attention (waiting, permission status) are sorted higher in the priority sort mode, ensuring you see blocked agents quickly.

Section titled “Related Features”