Lite SuiteLite Suite
← Back to Docs

LiteTerminal

Multi-terminal emulator with 4 layout modes, an HTTP PTY bridge, and an MCP server for AI-powered multi-agent orchestration

Overview

LiteTerminal is a multi-terminal emulator with 4 flexible layout modes, an HTTP PTY bridge, and a built-in MCP server. It supports PowerShell, CMD, Git Bash, and WSL, and remembers your layout and open sessions between restarts.

What makes it different: LiteTerminal exposes every terminal session to AI agents. An agent can read terminal output, write commands, register itself to a session, and communicate with other agents -- all through standard MCP tools. This turns a terminal emulator into a multi-agent orchestration backbone.

Features

Terminal

  • 4 layout modes -- grid (auto/2x2/3x3), splitter (horizontal with draggable dividers), window (floating/draggable with edge snapping), and tabs (compact tab bar with preserved scrollback)
  • Configurable shell profiles -- assign names, shells, starting directories, and colors per profile
  • Session persistence -- reopen the same layout and directories on next launch
  • Span all monitors -- stretch the window across every display

AI Agent Integration

  • HTTP PTY Bridge (port 7425) -- external HTTP API for reading, writing, and listing terminal sessions programmatically
  • MCP Server (port 7424) -- single terminal tool with action-routed operations (register, read, write, submit, ctrl, list, notify)
  • Agent registry -- agents register themselves to PTY sessions at ~/.liteterminal/agents/, creating a discoverable fleet
  • TTS notifications -- agents can speak notifications aloud through the system

Multi-Agent Orchestration

LiteTerminal enables a pattern where multiple AI agents (Claude Code, or any MCP-compatible client) each bind to their own terminal session and communicate by reading and writing to each other's sessions.

A typical orchestration session looks like this:

  1. Open 4 terminals in LiteTerminal (4 PTY sessions)
  2. Launch a Claude Code instance in each terminal
  3. Each agent calls list to discover PTY sessions, then register to bind itself
  4. A coordinator agent broadcasts a fleet roster to all others via write
  5. Agents read each other's terminals to stay aware of fleet activity
  6. The coordinator dispatches tasks, relays bug reports, and reviews code by reading worker terminals

This has been tested in production with 4 simultaneous Claude Code agents working on different projects (LiteEditor, LiteCore, litesuite.dev), coordinated through a single LiteTerminal instance.

Installation

Select LiteTerminal during the LiteAISuite install process. Shells are auto-detected from the system at first launch. WSL must already be installed in Windows for WSL sessions to appear.

The MCP server and PTY bridge start automatically with the app. No additional configuration needed for AI agent access.

Usage

Terminal Operations

Opening a new tab: Ctrl+T opens a new tab using the default profile. Click the + button in the tab bar for the same result.

Splitting panes:

| Action | Shortcut | |---|---| | Split pane horizontally | Ctrl+Shift+H | | Split pane vertically | Ctrl+Shift+V | | Close current pane | Ctrl+Shift+W | | Focus pane left/right/up/down | Ctrl+Alt+Arrow |

Switching tabs: Ctrl+Tab / Ctrl+Shift+Tab to cycle, or click a tab directly. Ctrl+1 through Ctrl+9 jump to specific tab positions.

Switching layouts: Click the layout selector in the toolbar. Each mode preserves your terminal sessions -- only the arrangement changes.

Renaming a tab: Double-click the tab label to rename it.

AI Agent Operations

The MCP terminal tool supports these actions:

| Action | Purpose | Key Params | |--------|---------|------------| | list | Show all active PTY sessions with PIDs | -- | | register | Bind an agent ID to a PTY session | agent_id, pty_session_id, meta | | read | Read another agent's terminal output (~32KB buffer) | agent_id | | write | Send text to another agent's terminal | agent_id, data | | submit | Write text + press Enter | agent_id, data | | ctrl | Send a control character (Ctrl+C, Ctrl+D, etc.) | agent_id, data | | create | Create a new terminal session | data (shell), meta.cwd | | destroy | Destroy a terminal session | pty_session_id | | notify | Speak a TTS notification aloud | data | | help | Show full documentation | -- |

Agent registration writes a JSON file to ~/.liteterminal/agents/:

{
  "agent_id": "claude-f2c5b05d",
  "pid": 24792,
  "pty_session_id": "pty-6-1773797932597",
  "meta": {
    "conversation": "f2c5b05d",
    "model": "opus-4.6",
    "role": "liteeditor"
  }
}

Reading another agent's terminal returns the last ~32KB of output, including tool calls, file edits, build output, and errors. The MCP server strips ANSI escape codes for clean AI consumption.

Writing to another agent's terminal injects the text as if the user typed it. The receiving agent sees it as a new message and responds naturally.

Configuration

Shell profiles are managed in Settings > Profiles. Each profile supports:

  • Display name and icon color
  • Shell executable path (e.g., pwsh.exe, bash.exe, wsl.exe)
  • Starting directory
  • Environment variable overrides

Session persistence is toggled in Settings > Startup. When enabled, LiteTerminal restores the last tab and pane layout on launch (directory state is restored, shell history is not).

Architecture

┌──────────────────────────────────────────┐
│  LiteTerminal (Electron)                  │
│                                            │
│  ┌──────────────────────────────┐        │
│  │  PtyManager                   │        │
│  │  ├── node-pty processes       │        │
│  │  ├── 32KB rolling buffers     │        │
│  │  └── Dynamic IPC channels     │        │
│  └──────────────┬───────────────┘        │
│                  │                         │
│     ┌────────────┼────────────┐           │
│     │            │            │           │
│  ┌──┴───┐  ┌────┴────┐  ┌───┴────┐     │
│  │ xterm│  │PTY Bridge│  │  MCP   │     │
│  │ (UI) │  │  :7425   │  │ :7424  │     │
│  └──────┘  └─────────┘  └────────┘     │
│                                            │
└──────────────────────────────────────────┘
  • PtyManager manages PTY session lifecycle with 32KB rolling buffers per session and dynamic IPC channels for real-time output streaming
  • PTY Bridge (HTTP, port 7425) provides REST endpoints for external scripts and tools
  • MCP Server (Python FastMCP, port 7424) provides the terminal tool for AI agents via the Model Context Protocol

Requirements

  • Desired shells (PowerShell, Git Bash, WSL) must be separately installed on the system
  • Python (for the MCP server) is set up by the Lite Suite installer
  • No additional requirements beyond the base Lite Suite install

Troubleshooting

A shell profile doesn't appear in the picker. Open Settings > Profiles and confirm the shell executable path is correct. If Git Bash or WSL isn't detected automatically, add the profile manually with the full path to the executable.

Split panes resize unexpectedly after window resize. Pane sizes are stored as proportional ratios. Very small panes may collapse visually at narrow window widths. Drag the pane divider to reset sizing.

Session restore opens the wrong directories. Persistence captures the working directory at the time LiteTerminal closes. If a session's working directory was deleted or on a disconnected drive, that pane opens in the home directory instead.

Agent registration goes to the wrong PTY. When multiple agents register simultaneously, they can collide on the same PTY session. Verify registrations by checking ~/.liteterminal/agents/*.json and cross-referencing PIDs against list output. Edit the JSON files directly to correct mismatches.

Agent messages going to the wrong agent. The write action routes through the agent's JSON registration file, not directly to a PTY. If the JSON has the wrong pty_session_id, messages land on the wrong terminal. Fix the JSON file and messages will route correctly.