gPTY: A Godot & Rust-Powered PTY Multiplexer

gPTY is a desktop application designed as a foundation for Pseudo-Terminal (PTY) management, blending the UI capabilities of Godot with the performance and safety of Rust.

It offers a flexible tiling grid for various panes—including terminals, file explorers, and code editors—alongside a specialized "concept capture" system. Most notably, it features a JSON-RPC and MCP (Model Context Protocol) interface, allowing AI agents to scrape TUIs interact directly with the workspace by spawning panes and injecting text.

---

🏗️ System Architecture

The following diagram illustrates how the various components of gPTY interact:

---

🚀 Key Features

• Dynamic PTY Management: Launch and control independent shell sessions within a resizable, tiling grid.
• High-Fidelity Rendering: Utilizes alacritty_terminal for full DEC STD 070 compliance, supporting:
  • 16 / 256 / True Color.
  • Regex-based search within scrollback.
  • Wrapped text selection.
• Programmable Interface: A public API consisting of a CLI and a JSON-RPC IPC socket, complemented by an MCP server.
• Concept Engine: Uses $\text{RegEx} \rightarrow \text{Route}$ logic to monitor PTY output. When a trigger is hit, the data is sent to adjacent panes (like an Inspector or Code Viewer).
  • Note: Concepts are read-only; they never send input back to the shell.
• Agent Observability:
  • Reasoning Pane: Displays agent lifecycle events (via OMP).
  • Inspector Pane: A private, tool-free Q&A environment.
• Robust Persistence: Workspaces, profiles, and scrollback history are saved to SQLite/JSON, enabling full-text search across historical pane data upon restart.
• Universal Compatibility: Available as standalone binaries for Windows, macOS, and Linux.

[!WARNING] Development Note: A significant portion of this project—including the Rust gpty-core bridge and Godot UI layouts—was authored using LLMs. Consequently, the code may exhibit non-idiomatic patterns or contain bugs.

---

🛠️ Technical Stack Rationale

---

📦 Installation & Setup

You can download standalone binaries from the GitHub Releases page; no separate Godot installation is required.

Platform Assets

🏁 Getting Started Checklist

• Download the appropriate archive for your OS.
• Verify the download using the provided SHA256SUMS file:
  • Linux: sha256sum -c SHA256SUMS
  • macOS: shasum -a 256 -c SHA256SUMS
  • Windows: certutil -hashfile asset SHA256
• Launch the GUI.
• Test the CLI connection.

Note: Checksums ensure file integrity during transit but are not cryptographic signatures; artifacts are currently unsigned.

---

💻 Command Line Interface (CLI)

The gpty binary communicates with the GUI via a JSON-RPC IPC socket (located at $XDG_RUNTIME_DIR/gpty.sock on Linux or defined by GPTY_SOCKET).

Common Commands

# Basic System Checks
gpty version
gpty daemon status

# Workspace Management
gpty new-pane --pane-type terminal  # Create a new terminal
gpty list-panes                    # Show all active panes
gpty kill-pane T1                  # Close pane labeled 'T1'
gpty inject T1 --text "ls -la"     # Send command to pane T1

# Layout Persistence
gpty layout save my-setup           # Save current configuration
gpty layout load my-setup           # Restore configuration
gpty layout list                    # List saved layouts

# AI & Integration
gpty --skill                       # Print agent skill manifest
gpty schema --format mcp           # Generate MCP tool manifest

---

🤖 MCP Integration

gPTY includes a Model Context Protocol (MCP) server, allowing AI coding assistants to orchestrate the workspace.

Configuration

Add the following to your mcp.json for auto-discovery:

{
  "mcpServers": {
    "gpty": {
      "command": "gpty",
      "args": ["mcp"]
    }
  }
}

Capabilities

When running gpty mcp over stdio, the following tools are exposed to the agent:

• new-pane, list-panes, kill-pane, focus-pane
• inject, pane-read, pane-status, pane-run, pane-wait
• broadcast, layout-*, daemon-*, concept-*, version

You can generate the full JSON Schema for these tools without running the GUI by executing: gpty schema --format mcp