TUI
The terminal interface where you see and interact with all your agents.
Grid Layout
The TUI renders all agent panes simultaneously in a grid. Grid dimensions are auto-calculated from the number of panes to minimize wasted space:
| Panes | Grid | Waste |
|---|---|---|
| 1-2 | 2x1 | 0-1 cells |
| 3-4 | 2x2 | 0-1 cells |
| 5-6 | 3x2 | 0-1 cells |
| 7-8 | 4x2 | 0-1 cells |
| 9 | 3x3 | 0 cells |
When the last row has fewer panes than the rows above, those panes expand to fill the width. If 7 panes fill a 4x2 grid, row 1 has 4 panes and row 2 has 3 wider panes. No empty cells.
You can override the auto-calculated grid with the command modal: press ` then type grid 3x3. Use layout reset to return to auto-calculated defaults. You can also pass --reset-layout on startup.
Pane Title Bars
Each pane has a 1-row title bar at the top showing:
- Agent name badge (gray background when unfocused, blue when focused)
- Activity indicator: green dot = agent is actively working, gray dot = idle
- Bead ID badge when an agent has a bead assigned via
initech bead [R]indicator for remote agents connected via cross-machine coordination
The title bar fill uses --- in dark cyan, giving the grid a visual structure similar to a terminal multiplexer.
Keybindings
Navigation
| Key | Action |
|---|---|
| Alt+Left / Alt+Right | Cycle focus between panes |
| Mouse click | Focus the clicked pane |
Layout presets
| Key | Action |
|---|---|
| Alt+1 | Focus mode: full-screen on the focused pane |
| Alt+2 | 2x2 grid |
| Alt+3 | 3x3 grid |
| Alt+4 | Main + stacked: one large pane with the rest stacked alongside |
Actions
| Key | Action |
|---|---|
| Alt+z | Zoom/unzoom the focused pane (toggle full-screen) |
| Alt+s | Toggle agent status overlay panel |
| Alt+q | Quit (graceful shutdown) |
| ` | Open command modal |
Mouse
| Action | Effect |
|---|---|
| Click | Focus the clicked pane |
| Click + drag | Select text (highlighted in yellow). Text is copied to clipboard on mouse release. |
Command Modal
Press ` (backtick) to open the command bar at the bottom of the screen. Type a command and press Enter.
| Command | Action |
|---|---|
| grid CxR | Set grid layout (e.g., grid 3x3, grid 4x2) |
| focus [name] | Full-screen the focused pane, or a named agent (focus eng1) |
| zoom | Toggle zoom on the focused pane |
| panel | Toggle the agent status overlay |
| main | Main + stacked layout (one large, rest stacked) |
| layout reset | Reset to auto-calculated grid defaults |
| restart / r | Kill and relaunch the focused agent's process |
| quit / q | Exit the TUI (graceful shutdown) |
Press Escape to close the command modal without executing.
Agent Overlay
Press Alt+s or use the command modal (panel) to toggle the agent overlay. This panel shows all agents with their current state at a glance:
- Agent name
- Activity state (running, idle, stopped, stalled)
- Current bead assignment (if any)
- Whether the agent is local or remote (
[R])
The overlay is useful when you have many agents and want a quick summary without peeking into individual panes. It updates in real-time as agents change state.
Input Routing
All keyboard input goes to the focused pane. The focused pane is indicated by a blue title bar badge. Everything you type (except the keybindings above) is injected into that pane's PTY, exactly as if you were typing directly into the terminal.
To switch which pane receives input, use Alt+Left / Alt+Right or click a different pane.
You can also send messages from outside the TUI using initech send. This works from any terminal window while the TUI is running.
Activity Detection
The TUI detects agent activity by tailing Claude Code's JSONL session logs. It polls every 500ms and maps the last log entry to a state:
| Log Entry | State | Indicator |
|---|---|---|
user or progress | Running | green dot |
assistant (less than 5s old) | Running | green dot |
assistant (more than 5s old) | Idle (decayed) | gray dot |
| Everything else | Idle | gray dot |
The 5-second decay handles the gap between Claude finishing a response and the session log being updated. Activity detection works by reading Claude's own conversation log, not by measuring terminal output rate.
Bottom-Anchored Content
Claude Code renders inline like a REPL, not using the terminal's alternate screen buffer. The TUI scans each pane's emulator buffer from the bottom up to find the last non-empty row, then pushes content down so the active area sits flush at the bottom of the pane. This means you always see the most recent output without needing to scroll.
Last updated: April 2026