gPTY

gPTY - a desktop workspace built on Rust and Godot. It provides a tiling grid for panes (terminals, code viewers, file trees, wikis, media, and more), 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. Every pane can be driven from a shell, a script, or an agent over one public API. It is a side project in active development and a vast majority of this codebase, including most of the Godot UI layout and the Rust (gpty-core) GDExtension bridge, was generated using various LLMs under human review; and as such, the underlying code may contain unidiomatic patterns and/or bugs. It *does not* follow the core UNIX philosophy very well, as in, it does aim to do several things; though it does also intend to do them all well.

Features

Panes

Watch: the pane grid split and reflow

• Tiling grid - split, resize, and rearrange independent shell sessions; save and reload named layouts, workspaces (tab sets), and profiles.
• Emulation - alacritty_terminal grid with 16/256/true color, scrollback with regex search, and wrapped text selection.
• Memory - scrollback, settings, and workspaces restore on restart, with full-text search across each pane's history.
• File Tree - Native Godot OS file tree browser.
• Code Viewer - Text and Markdown rendered in a pane.
• Wiki - a vault of plain Markdown notes with full-text search, a live-preview editor, [[wikilinks]], backlinks, and a link graph, reopened where you left off. The shipped Knowledge Base profile opens the bundled wiki inside a release.
• Media - play local audio and video in a pane through a pinned, minimal FFmpeg backend (v0.7).
• `cli_view` - stream any command's output into a pane, so a plugin can add UI without a Godot SDK.
• Interface - one design system across every pane, overlay and dialog: a dark theme and a light theme that follows the desktop, a UI scale, keyboard rings on the pane chrome, the Wiki pane and the vault graph, and accessible names for screen readers (v0.8).

Watch: the wiki vault, its link graph and a CLI search

Watch: audio and video in a pane

Watch: a command streamed into its own pane

Agents & Automation

Watch: tagged panes, one broadcast and agent state badges

Watch: a concept routing output into the adjacent pane

• One API, three doors - the same operations are available as a JSON-RPC socket, the gpty CLI, and an MCP server: spawn panes, inject input, read output, run a command and wait for a pattern, broadcast to tagged panes. The server is listed in the official MCP registry as io.github.godot-pty/gpty.
• Agent state badges - an agent declares working or needs attention from its own pane and the tab shows it. Display only.
• Observability panes - Reasoning passively shows documented agent lifecycle events (OMP today, adapter-neutral vocabulary); Inspector is a private, tool-free Q&A session. gPTY never orchestrates agent state.
• Concepts - regex triggers on terminal output capture the reply and route it into an adjacent pane. Write your own in Settings, by hand or in the visual graph editor. Concepts display only; they never type into a shell.

Limited Extensibility

• Plugins - manifest-based, reviewed in the GUI before install, with a public registry.

Status

• Documentation & Blogs: https://gpty.dev
• Releases ship SHA256SUMS and build-provenance attestations; the control socket is owner-only.
• The repository tracks OpenSSF recommendations; registered as OpenSSF Project 16201, scorecard: securityscorecards.dev.
• Release assets carry SLSA Build Level 2 provenance.
• The project has been added to the Linux Foundation & health will be tracked via LFX Insights.

---

Installation & Usage

Standalone binaries (no Godot install required) are published on GitHub Releases for Linux, macOS, and Windows.

Every release also bundles the gPTY knowledge base; the Knowledge Base profile in the sidebar opens the bundled wiki from your user data.

In the file names, is the release tag you downloaded (for example v0.7.0).

Verifying releases

Each release publishes a SHA256SUMS listing every asset. Check the file you downloaded before running it:

sha256sum -c SHA256SUMS            # Linux

shasum -a 256 -c SHA256SUMS # macOS certutil -hashfile SHA256 # Windows

Checksums catch a corrupted or tampered download in transit. Each asset also carries a build-provenance attestation binding it to the workflow run that built it:

gh attestation verify <asset> --repo godot-pty/gpty

The binaries are not code-signed (see SECURITY.md).

CLI

The gpty binary controls a running GUI over JSON-RPC IPC, and every release bundle ships it next to the GUI. It is also on crates.io - cargo install gpty puts the same binary on PATH (a Rust toolchain and a C compiler are required, for its bundled SQLite), and that copy is what an MCP client launches for gpty mcp. The CLI starts one on demand only for commands a fresh workspace can satisfy - new-pane and layout load - while gpty daemon start starts one explicitly and --no-daemon never starts one. Every other command needs a workspace that already exists, so it fails with no gpty GUI is running (start one with \gpty daemon start\) instead of opening a window it cannot use. Building from source (cargo build -p gpty, or cargo build --workspace) is only needed when working on the CLI itself; if you install it that way, reinstall it after a version bump (cargo install --path crates/gpty-cli --force). A stale gpty earlier on PATH shadows the release's CLI and fails opaquely (a subcommand it lacks dies in clap before any IPC), which is why the CLI warns once, on stderr, when it sees that the running GUI's version or IPC protocol differs from its own - the warning names both sides, but the reinstall is the fix.

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 (exit 1 when it is not)

gpty daemon status

Print the bundled agent skill (for coding agents running inside a pane)

gpty --skill

Declare this pane's agent state, from inside the pane (display only)

gpty state working

Spawn a new terminal pane

gpty new-pane --pane-type terminal

List all active panes

gpty list-panes

Target a pane by id (what list-panes reports) or by a label that is unique

across workspaces; a label two workspaces share is refused, not guessed

gpty inject T1 --text "echo hello"

Read a pane's screen and scrollback; run a command in a new pane and wait for its output

gpty pane-read T1 --lines 200 gpty pane-run --command "cargo test" gpty pane-wait T1 --pattern "tests passed" --timeout-ms 30000

Search and read a wiki vault

gpty vault search gpty vault read

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

Install a plugin (reviewed in the GUI - its actions run as you)

gpty plugin install godot-pty/gpty-omp gpty plugin list

Manage the GUI daemon

gpty daemon start 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 mcp

See gpty --help for all subcommands and flags.

MCP integration

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 mcp over 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, vault-search, vault-read, vault-weight, layout-*, daemon-*, concept-*, version).
• Manifest: `gpty schema --form