tui

Documentation

Overview

Package tui — orchestrator TUI (Phase 3 of ADR-028). The production "teammate panel" for clawtool: live byte stream from every active dispatch, scrollable per-task viewport, theme-aware adaptive colours, key hints rendered via bubbles/help. Inspired by lazygit / gh-dash / k9s layout conventions: sidebar + detail pane + status bar.

Architecture:

• Left sidebar (sticky 28 col): tasks list with status pills and message counts. Arrow keys select, enter focuses, the stream pane on the right reflects the selected task.
• Right detail pane (flex): bubbles/viewport rendering the selected task's StreamFrame ringbuffer line by line. Auto- scroll-to-bottom when new frames arrive UNLESS the operator scrolled up (tail-follow toggle).
• Header bar: app banner + version + live indicator.
• Footer bar: key bindings (q quit · ↑↓ select · pgup/pgdn scroll · f tail-follow · r reconnect) + at-a-glance counts.

The orchestrator subscribes to the daemon's WatchEnvelope socket; task transitions update sidebar rows, frames append to the per- task ringbuffer. A 5-second post-terminal grace window keeps the task visible after it finishes so the operator catches the final lines.

Package tui — orchestrator's Peers panel. The third sidebar tab (after Active/Done) shows live peers from the daemon's a2a registry plus per-peer inbox state. Replaces the "open another tmux window to spy on what other Claude Code sessions are doing" workflow with one always-on view.

Data model:

• m.peers — last poll result from GET /v1/peers, refreshed every orchPeersPollInterval.
• m.peerInbox — drained-or-peeked messages for the currently- selected peer; rendered in the detail pane when on this tab.
• peersFetchedMsg / peerInboxFetchedMsg are the tea.Msg pumps that ferry results back into Update().

Why polling instead of subscribing: the daemon's watch socket today only ferries BIAM events; adding a second push channel for peer events is a Phase-2 task. Polling at 2s is fine for the local-host operator-facing case (the visible cost is a tiny HTTP hit; the visible win is "I see Bob just finished his task without alt-tabbing").

Index

• func RunOrchestrator() error
• type OrchModel
  • func NewOrchestrator() OrchModel
  • func (m OrchModel) Init() tea.Cmd
  • func (m OrchModel) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (m OrchModel) View() string

Functions

func RunOrchestrator

func RunOrchestrator() error

RunOrchestrator boots the Bubble Tea program. Invoked from the CLI dispatcher.

Types

type OrchModel

type OrchModel struct {
	// contains filtered or unexported fields
}

OrchModel is the orchestrator's Bubble Tea state.

func NewOrchestrator

func NewOrchestrator() OrchModel

NewOrchestrator constructs a fresh orchestrator model.

func (OrchModel) Init

func (m OrchModel) Init() tea.Cmd

func (OrchModel) Update

func (m OrchModel) Update(msg tea.Msg) (tea.Model, tea.Cmd)

func (OrchModel) View

func (m OrchModel) View() string