gPTY - a PTY foundation built on Godot and Rust. Provides a tiling grid for panes (terminal, code, file-tree, etc.), a concept capture engine, and a JSON-RPC/MCP control surface so AI agents and automation tools can spawn panes, inject text, and observe output on terminals without scraping a TUI.
- PTY - Spawn and manage independent shell sessions in a resizable tiling grid. Full
DEC STD 070viaalacritty_terminal:16/256/true color, scrollback with regex search, wrapped text selection. - Public API - JSON-RPC IPC socket + CLI (
gpty new-pane,gpty inject, …) + MCP server. AI agents, scripts, and orchestrators drive the workspace over a documented, versioned protocol. - Concept engine - RegEx triggers on PTY output capture the reply and route it into adjacent panes (code viewer, Inspector). Write your own or ship the defaults. Concepts capture and display only - they never inject input into a shell.
- Agent observability - Reasoning pane passively projects documented agent lifecycle events (OMP, extensible); Inspector pane runs a private, tool-free Q&A session. Observability only - gpty never orchestrates agent state.
- Persistence - Scrollback, settings, workspaces (named tab sets), and profiles auto-save to SQLite/JSON and restore on restart; full-text search across each pane's persisted history.
- Cross-platform - Standalone binaries for Linux, macOS, and Windows. No Godot or Rust toolchain required to run.
- Documentation - https://godot-pty.github.io/gpty/
- The vast majority of this codebase, including most of the Godot UI layout and the Rust (
gpty-core) GDExtension bridge, was generated using LLMs; and as such, the underlying code may contain unidiomatic patterns and/or bugs.
| Component | Choice | Rationale |
|---|---|---|
| PTY library | portable-pty |
Cross-platform (Linux /dev/ptmx + Windows ConPTY) with a single API |
| ANSI parsing | vte crate |
Fast Rust ANSI state machine |
| Async runtime | tokio |
Per-terminal tasks; channel-driven capture state machine |
| I/O threading | Dedicated std::thread per PTY |
Predictable blocking reads; bridges to tokio via mpsc |
| Concept capture | Rust regex over parsed LineParser output |
Linear-time matching (ReDoS-safe); captures buffer raw bytes for grid-faithful replay |
| Grid rendering | alacritty_terminal |
Full DEC STD 070 grid state machine; pass arrays to Godot _draw() |
| Godot bridge | gdext 0.5 |
Native GDExtension for Godot 4.7+ |
| Rust edition | 2024 | Requires Rust >= 1.85 |
Standalone binaries (no Godot install required) are published on GitHub Releases for Linux, macOS, and Windows.
| Platform | Package |
|---|---|
| Linux | gpty-v0.5.3-linux-x86_64.tar.gz - extract and run ./gpty |
| macOS | gpty-v0.5.3-macos.zip - unzip, right-click the .app → Open |
| Windows | gpty-v0.5.3-windows-x86_64.zip - unzip and run gpty.exe |
The gpty binary controls a running GUI over JSON-RPC IPC. Build it with cargo build -p gpty (or cargo build --workspace).
Once the GUI is running (launched from Godot or a release binary), the CLI connects over a Unix socket ($XDG_RUNTIME_DIR/gpty.sock on Linux, or GPTY_SOCKET env var):
# Check if the GUI is running
gpty version
# Print the bundled agent skill (for coding agents running inside a pane)
gpty --skill
# Spawn a new terminal pane
gpty new-pane --pane-type terminal
# List all active panes
gpty list-panes
# Send text to a pane (by label, e.g. T1)
gpty inject T1 --text "echo hello"
# Close a pane
gpty kill-pane T1
# Save and load named layouts
gpty layout save my-setup
gpty layout load my-setup
gpty layout list
# Manage the GUI daemon
gpty daemon status
gpty daemon stop
# Generate AI tool manifests (no GUI needed)
gpty schema
gpty schema --format mcp
# Run as MCP server over stdio (no GUI needed)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | gpty mcpSee gpty --help for all subcommands and flags.
gpty ships an MCP (Model Context Protocol) server so AI agents and coding harnesses can control the workspace. The repo-root mcp.json declares it for auto-discovery:
{"mcpServers": {"gpty": {"command": "gpty", "args": ["mcp"]}}}- Direct: run
gpty mcpover stdio - exposes a tool per CLI subcommand (new-pane,list-panes,kill-pane,focus-pane,inject,pane-read,pane-status,pane-run,pane-wait,broadcast,layout-*,daemon-*,concept-*,version). - Manifest:
gpty schema --format mcpprints the MCP tool manifest (JSON Schema, works without a running GUI) for hand-off to agent configurations.
Tool schemas are generated from the same clap definitions as the CLI (crates/gpty-cli/src/commands/schema.rs), so they cannot drift from gpty --help.
See ROADMAP.md for the full feature inventory.
See SECURITY.md for the threat model, reporting process, and what gpty does not defend against. Implementation rules - the Concept Engine's ReDoS stance, PTY environment sanitization, IPC hardening, OSC 52 restrictions - live in AGENTS.md.
See CONTRIBUTING.md for setup instructions, build commands, testing, code style, and the pull request process.
See CHANGELOG.md for the complete versioned changes and history.
gPTY is free software, licensed under the GNU General Public License, version 3 or later — see LICENSE for the full text.
LICENSE-EXCEPTIONS.md adds two permissions under section 7 of that license, so the ecosystem side stays permissive:
- Plugins, extensions, and adapters are not required to be GPLv3. Anything that works with gPTY over its CLI, JSON-RPC, MCP, or event interfaces — including native pane types — may be licensed under Apache-2.0, MIT, or any other terms you choose, and shipped alongside gPTY without obligation.
- Configuration and data files carry no copyleft. Profiles, workspaces, layouts, concepts, and settings are yours to license however you like; the default
*.jsonfiles shipped with gPTY are Apache-2.0.
Copyright (C) 2026 Neil Pathare.
gPTY is distributed in the hope that it will be useful, but absolutely without any warranty and assumes no liability for any usage by end-users; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.