Multi-Agent Support

Overview

Navi tracks multiple AI agents running in the same tmux session — Claude Code, OpenCode, and others — displaying each agent’s status and making the main session icon reflect the highest-priority status across all agents. External agents are first-class citizens in the display.

Quick Start

Run ./install.sh to deploy the OpenCode plugin alongside Claude Code hooks
Launch Claude Code and OpenCode in the same tmux session
Each session row shows per-agent indicators: [OC ●] for OpenCode working
The main session icon reflects whichever agent needs the most attention

Session List Display

When a session has multiple agents, compact indicators appear inline:

⚙️ api        [OC ●]     main ✓  2m ago
✅ frontend   [OC ○]     feat/nav ~  5m ago
❓ backend                main ✓  1m ago

[OC ●] — OpenCode working (filled circle, cyan)
[OC ○] — OpenCode idle (hollow circle, gray)
No indicator for single-agent sessions (zero overhead)

Agent Indicator Colors

Status	Icon	Color
`working`	●	Cyan
`permission`	●	Magenta
`waiting`	●	Yellow
`error`	●	Red
`done`	○	Green
`idle` / `stopped`	○	Gray

Agent Labels

Agent Type	Label
`opencode`	`OC`
Other	First 2 characters (uppercased)

Composite Session Status

The main session icon reflects the highest-priority status across all agents:

Priority (highest to lowest):
  permission > waiting > working > error > idle > stopped > done

If Claude Code is idle but OpenCode is working, the session shows ⚙️ (working) — not ⏸ (idle). When the composite status differs from Claude Code’s own status, a [CC ⏸] indicator appears alongside the agent indicators.

Examples

Claude Code	OpenCode	Main Icon	Indicators
working	idle	⚙️	`[OC ○]`
idle	working	⚙️	`[CC ⏸] [OC ●]`
idle	permission	❓	`[CC ⏸] [OC ●]`
done	done	✅	`[OC ○]`

When an external agent drives the composite status, the session message includes the source: "Running inference (opencode)".

Agent Detail Section

When a multi-agent session is selected, the detail area shows a per-agent breakdown:

Agents
  Composite working (opencode) ⚙️
  CC idle ⏸ — "Awaiting user input"
  OC working ⚙️ 3m ago

How It Works

Status File Format

All agents write to the same session status file at ~/.claude-sessions/<session>.json:

{
  "tmux_session": "api",
  "status": "working",
  "message": "Implementing feature X",
  "cwd": "/home/user/api",
  "timestamp": 1707506400,
  "agents": {
    "opencode": {
      "status": "idle",
      "timestamp": 1707506380
    }
  }
}

Root-level fields (status, message, cwd, timestamp) are Claude Code’s domain
The agents map holds external agent statuses, keyed by agent type
Each agent does read-modify-write, preserving others’ fields

OpenCode Plugin

The navi plugin for OpenCode lives at ~/.config/opencode/plugins/navi.js. It maps OpenCode lifecycle events to navi status strings:

OpenCode Event	Navi Status
`session.created`	`working`
`tool.execute.after`	`working`
`chat.message`	`working`
`session.idle`	`idle`
`session.error`	`error`
`permission.updated`	`permission`
`permission.replied`	`working`

The plugin resolves the tmux session name via tmux display-message, caches it for 30 seconds, and writes status atomically using temp-file-then-rename.

notify.sh Preservation

Claude Code’s notify.sh hook preserves the agents field during its read-modify-write cycle, ensuring external agent status is never overwritten.

Session Sorting

Sessions with any agent (Claude Code team agents or external agents) in waiting or permission status sort to the top of the priority list, ensuring blocked agents are always visible.

Installation

The OpenCode plugin is deployed automatically by ./install.sh:

# Deploys to ~/.config/opencode/plugins/navi.js
./install.sh

No manual configuration is needed. OpenCode automatically loads all plugins in its plugins directory.

Adding New Agent Types

The multi-agent system supports any number of agent types. To add a new agent:

Create a plugin/hook that writes to ~/.claude-sessions/<session>.json
Use read-modify-write to update the agents.<type> entry
Set status and timestamp fields
Navi auto-detects and displays the new agent type

Agent Teams — Claude Code’s built-in team agents (SubagentStart/Stop)
Audio Notifications — Audio alerts for external agent status changes
Session Monitoring — Core session tracking