Auto-Tundra TUI — Agent Interface Guide

The at-tui crate provides a ratatui terminal dashboard that agents can drive programmatically. Use it to inspect auto-tundra project state, navigate beads/agents/sessions, and automate workflows.

Quick Start

# Interactive mode with demo data
cargo run -p at-tui -- --offline

# Interactive mode connected to running daemon
cargo run -p at-tui -- --api http://localhost:9090

# Headless mode (agent automation — JSON in/out, no rendering)
echo '{"cmd":"query_state"}' | cargo run -p at-tui -- --headless --offline

# Headless with live API
printf '{"cmd":"tab","args":[2]}\n{"cmd":"query_tab"}\n' | cargo run -p at-tui -- --headless

Architecture

Agent (stdin JSON) ──┐
Human (keyboard)  ───┤──► AppCommand dispatcher ──► App state ──► Renderer (or JSON stdout)
API (at-bridge)   ───┘                                              ↑ skipped in --headless

Three input modes:

1. Keyboard — vim-style keys (human)
2. : command mode — type :tab 3 in the status bar
3. --headless stdin pipe — send JSON commands, receive JSON responses

CLI Flags

17 Tabs

Headless JSON Protocol

Sending Commands

Two formats accepted (both work in headless):

JSON format (recommended for agents):

{"cmd":"tab","args":[3]}
{"cmd":"query_state"}
{"cmd":"select","args":[2]}
{"cmd":"query_selected"}
{"cmd":"query_tab"}
{"cmd":"quit"}

Text format (also works):

:tab 3
:query state
:select 2
:query selected
:quit

Command Reference

Response Format

Events (emitted automatically):

{"event":"started","tabs":17,"offline":true}
{"event":"tab_changed","tab":3,"tab_name":"Sessions"}
{"event":"data_refreshed","agents":5,"beads":12}
{"event":"ok"}
{"event":"quit"}
{"event":"error","message":"unknown command: foo"}

Query responses (raw JSON, not wrapped in event):

query_state:

{
  "current_tab": 0,
  "tab_name": "Dashboard",
  "selected_index": 0,
  "api_connected": false,
  "offline": true,
  "counts": {
    "agents": 5, "beads": 10, "sessions": 4, "convoys": 3,
    "costs": 4, "mcp_servers": 4, "worktrees": 3,
    "github_issues": 3, "github_prs": 2, "roadmap_items": 4,
    "ideas": 3, "stacks": 3, "changelog": 2, "memory_entries": 2
  }
}

query_tab (example for Sessions tab):

[
  {"id":"sess-01","agent":"mayor-alpha","cli_type":"Claude","status":"running","duration":"12m 34s","cpu":"2.1%"},
  {"id":"sess-02","agent":"deacon-bravo","cli_type":"Claude","status":"running","duration":"8m 12s","cpu":"1.4%"}
]

query_selected (example for a bead):

{"id":"bd-002","title":"Implement auth module","status":"Slung","lane":"Critical"}

Agent Workflow Examples

Inspect all beads

printf '{"cmd":"tab","args":[2]}\n{"cmd":"query_tab"}\n{"cmd":"quit"}\n' \
  | cargo run -p at-tui -- --headless --offline 2>/dev/null \
  | grep '^\[' | jq .

Check which agents are active

printf '{"cmd":"tab","args":[1]}\n{"cmd":"query_tab"}\n{"cmd":"quit"}\n' \
  | cargo run -p at-tui -- --headless 2>/dev/null \
  | grep '^\[' | jq '[.[] | select(.status == "Active")]'

Get GitHub issues

printf '{"cmd":"tab","args":[12]}\n{"cmd":"query_tab"}\n{"cmd":"quit"}\n' \
  | cargo run -p at-tui -- --headless 2>/dev/null \
  | grep '^\[' | jq '[.[] | select(.state == "open")]'

Multi-step inspection

cat <<'EOF' | cargo run -p at-tui -- --headless --offline 2>/dev/null
{"cmd":"query_state"}
{"cmd":"tab","args":[14]}
{"cmd":"query_tab"}
{"cmd":"tab","args":[2]}
{"cmd":"select","args":[1]}
{"cmd":"query_selected"}
{"cmd":"quit"}
EOF

Key Files

Keyboard Shortcuts (Interactive Mode)

API Data Refresh

When not in --offline mode, a background thread polls the at-bridge API every 5 seconds:

• Endpoints: /api/agents, /api/beads, /api/kpi, /api/sessions, /api/convoys, /api/costs, /api/mcp/servers, /api/worktrees, /api/github/issues, /api/github/prs, /api/roadmap, /api/ideation/ideas, /api/stacks, /api/changelog, /api/memory
• Data flows via flume channel from refresh thread → main thread
• Status bar shows: LIVE (connected), OFFLINE (demo data), ... (connecting)

Development Notes

• Binary crate ([[bin]]), no [lib] — tests use #[path = "..."] includes
• Build: cargo build -p at-tui
• Test: cargo test -p at-tui (114 tests)
• App::new(offline: bool) — pass true for demo data
• Effects: EffectManager wraps tachyonfx, called in ui::render() after widgets
• Toast: app.toasts.push(Toast::new("message", ToastLevel::Success))