agentctl-tui

Interactive terminal dashboard for managing supervised Claude agents. Wraps agentctl.sh in a blessed-based TUI with real-time status monitoring, log streaming, and live chat via AgentChat.

┌─ Agents ──────┬─ Logs ──────────────────────┬─ Chat (#general) ──┐
│ ● agent-alpha  │ [14:32:01] Task completed   │ @bob: hey everyone │
│ ● agent-beta   │ [14:32:02] Starting next... │ @alice: hello!     │
│ ○ agent-gamma  │ [14:32:03] Processing...    │ @server: hi there  │
│ ✗ agent-delta  │                             │                    │
│                │                             │ > _                │
└────────────────┴─────────────────────────────┴────────────────────┘

Features

• Agent lifecycle control — start, stop, restart, and kill agents with single keystrokes
• Real-time log streaming — tails supervisor.log using fs.watch, no polling
• Live chat — connects to the AgentChat WebSocket server with auto-reconnect
• Status indicators — ● running / ○ stopped / ✗ dead / ◐ stopping
• Agent detail view — name, PID, mission, uptime at a glance
• Filter agents — quickly search by name with /
• View context — inspect an agent's context.md with c

Install

git clone https://github.com/tjamescouch/agentctl-tui.git
cd agentctl-tui
npm install

Prerequisites

• Node.js >= 10
• agentctl.sh — the supervisor CLI that this TUI wraps. It searches these locations:
  • ~/dev/claude/agentchat/lib/supervisor/agentctl.sh
  • ~/dev/claude/projects/agent5/agentchat/lib/supervisor/agentctl.sh
  • Same directory as index.js
• Agent data directory at ~/.agentchat/agents/

Usage

npm start
# or
node index.js

For global install:

npm install -g .
agentctl-tui

Keybindings

| Key | Action | |---|---| | Tab / Shift+Tab | Cycle focus: agents → logs → chat | | j / k or ↑ / ↓ | Navigate agent list | | s | Start selected agent | | x | Stop selected agent (graceful) | | r | Restart selected agent | | K | Kill selected agent (requires confirmation) | | c | View agent context file | | / | Filter agent list | | Enter | Focus chat input (when chat panel focused) | | Escape | Clear filter / exit chat input / cancel | | q / Ctrl+C | Quit |

Chat commands

| Command | Action | |---|---| | /join #channel | Switch to a different chat channel |

Architecture

Single-file application (index.js) with four subsystems:

| Subsystem | Responsibility | Mechanism | |---|---|---| | Agent Scanner | Reads ~/.agentchat/agents/, resolves PID status | Filesystem polling (3s) | | Log Streamer | Tails the selected agent's supervisor.log | fs.watch + debounce | | Chat Client | Sends/receives messages on AgentChat | WebSocket with auto-reconnect | | UI | Three-column layout, focus management, input | blessed |

Mutations (start/stop/restart/kill) are delegated to agentctl.sh via child_process.execFile. Status is read directly from the filesystem — no shell-out needed for display.

Agent Directory Structure

Each agent lives in ~/.agentchat/agents/<name>/:

supervisor.pid    # PID of running supervisor process
state.json        # Persistent agent state
mission.txt       # Agent's mission/purpose
supervisor.log    # Log output (streamed by TUI)
context.md        # Agent context/documentation
stop              # Signal file (present = stopping)

Dependencies

Just two:

• blessed — terminal UI rendering
• ws — WebSocket client

License

ISC