AI Integration

teru is designed from the ground up for AI coding agents. It implements three complementary layers of AI integration: the CustomPaneBackend protocol for Claude Code agent teams, an MCP server for cross-agent communication, and the OSC 9999 agent self-declaration protocol.

Why Native AI Integration?

Standard terminal multiplexers (tmux, screen) break when Claude Code spawns agent teams. When Claude spawns 4-5 subprocesses, tmux splits into unusable fragments. You end up managing three config layers (tmux.conf + shell scripts + WM keybindings) just to keep panes organized.

teru solves this at the terminal level. Agent teams auto-organize into workspaces, pane borders reflect agent status in real time, and multiple Claude instances can query each other’s output via MCP tools.

Layer 1: CustomPaneBackend Protocol

teru implements the CustomPaneBackend protocol (Claude Code issue #26572). When Claude Code detects teru, it uses teru directly for pane management instead of shelling out to tmux.

teru sets the socket path automatically:

CLAUDE_PANE_BACKEND_SOCKET=/run/user/1000/teru-pane-backend.sock

Claude Code sends JSON-RPC to this socket:

{
  "method": "spawn",
  "params": {
    "argv": ["claude", "--agent", "backend-dev"],
    "metadata": {"group": "team-temporal"}
  }
}

teru creates a pane, adds it to the ProcessGraph, and auto-assigns it to a workspace based on the group name. The 7 supported operations are: spawn, close, focus, resize, list, write, and read.

Layer 2: MCP Server

teru exposes itself as an MCP server over a Unix socket. Multiple Claude Code instances can connect and query each other’s terminal state.

Configuration

Add to ~/.claude/claude_desktop_config.json (or your project’s .claude/settings.json):

{
  "mcpServers": {
    "teru": {
      "command": "socat",
      "args": ["UNIX-CONNECT:/run/user/1000/teru-PID.sock", "STDIO"]
    }
  }
}

Replace PID with the teru process ID (echo $TERU_MCP_SOCKET inside a teru pane).

MCP Tools

Tool	Description
`teru_list_panes`	List all panes with id, workspace, status, and agent metadata
`teru_read_output`	Get recent N lines of output from any pane by id
`teru_get_graph`	Full process graph as JSON — all processes, agents, parent-child relationships
`teru_send_input`	Type text into any pane’s PTY
`teru_create_pane`	Spawn a new pane (optionally in a specific workspace)
`teru_broadcast`	Send text to all panes in a workspace

Example: Reading Another Agent’s Output

One Claude Code instance can read what another is doing:

// In Claude Code, via MCP
const panes = await mcp.call('teru_list_panes', {});
const backendPane = panes.find(p => p.agent?.name === 'backend-dev');
const output = await mcp.call('teru_read_output', {pane_id: backendPane.id, lines: 50});

Layer 3: OSC 9999 Agent Protocol

Any process can self-declare as an AI agent by emitting OSC 9999 escape sequences. teru parses these and updates the ProcessGraph and pane border rendering.

Self-Declaration

# Declare as an agent (on startup)
printf '\e]9999;agent:start;name=backend-dev;group=team-temporal\a'

# Update status with progress
printf '\e]9999;agent:status;progress=0.6;task=Building API endpoints\a'

# Signal completion
printf '\e]9999;agent:stop;exit=success\a'

Protocol Fields

Event	Fields	Description
`agent:start`	`name`, `group`	Agent joins the process graph
`agent:status`	`progress` (0.0–1.0), `task`	Update progress and current task
`agent:stop`	`exit` (`success`\|`failure`\|`cancelled`)	Agent exits

Visual Feedback

teru colors pane borders based on agent status:

Cyan — agent running
Green — agent completed successfully
Red — agent failed
Dim — no agent in pane (idle)

The status bar shows live agent counts: [3 running] [1 done] [0 failed].

Layer 4: Claude Code Hook Listener

teru runs a Unix socket HTTP server that accepts Claude Code lifecycle events. Configure Claude Code to send hooks to teru:

{
  "hooks": {
    "PreToolUse": [{"type": "command", "command": "curl -s http://unix:/run/user/1000/teru-hooks.sock:/hook -d @-"}],
    "PostToolUse": [{"type": "command", "command": "curl -s http://unix:/run/user/1000/teru-hooks.sock:/hook -d @-"}]
  }
}

teru handles 16 event types: PreToolUse, PostToolUse, SessionStart, SessionEnd, Stop, Notification, PreCompact, PostCompact, and agent lifecycle events. Each event updates the ProcessGraph and can trigger visual indicators on pane borders.

Process Graph

Every process spawned inside teru is tracked in a directed acyclic graph (DAG). The graph records:

Process ID and parent PID
Start time and exit code
Agent metadata (name, group, status, progress)
Tool activity (from hook events)

Query the graph via MCP (teru_get_graph) or via the OSC 9999 protocol. Future versions will include a visual DAG view (Ctrl+Space, g).