OmniPTY documentation

OmniPTY is a native terminal emulator for macOS and Linux, written entirely in Rust — GPU-rendered, with a file-tree drawer you drive like vim and a status bar that knows where your shell is. These pages cover how to install it, how to use it, and every key you can put in its config file.

What OmniPTY is

OmniPTY is one Rust binary. Rendering and window management come from GPUI, Zed's GPU UI framework; the PTY and VT parsing come from alacritty_terminal, the engine behind Alacritty. Everything on top — the drawer, tabs, splits, workspaces, the prompt compiler, the status bar — is OmniPTY's.

The PTY reader and parser run on their own thread and mutate a shared terminal grid; the main thread locks it briefly during paint, copies the visible grid out, and paints batched text runs directly. Directory scans, git queries, and file watching happen on a background pool, so a slow repository never stalls typing.

It runs on macOS and on Linux (Wayland or X11). One codebase, one config file, the same keymap conventions on both — where macOS uses cmd, Linux uses ctrl-shift; the ctrl-w chords and every bare key are identical. The keybindings page lists both spellings side by side.

Requirements

• macOS 12 or later, Apple Silicon or Intel
• Or Linux, Wayland or X11, x86_64, with a Vulkan driver (Mesa's vulkan-radeon / vulkan-intel, or nvidia-utils) and libnotify (notify-send) for desktop notifications.
• No font install needed on either platform — JetBrainsMono Nerd Font Mono is bundled into the binary, so powerline separators and tree icons render on a machine with nothing installed. Set font.family to use your own.
• zsh or bash if you want the built-in prompt and shell integration. Other shells run fine; they just keep their own prompt.

Quick start

1. On macOS, install from the DMG (or brew install --cask omnipty-terminal/tap/omnipty) and open OmniPTY. It is Developer ID signed and notarized, so there is no right-click-to-open dance. On Linux, makepkg -si from the repo's PKGBUILD on Arch, or unpack the release tarball and run its ./install.sh; then run omnipty or pick it from your launcher.
2. A fully commented config file is written to ~/.config/omnipty/config.toml on first run. Open it from inside OmniPTY with cmd-, (ctrl-, on Linux).
3. Press cmd-b (ctrl-shift-b) to toggle the drawer and ctrl-w t to focus the file tree. Inside the tree, bare vim keys work: j k l h, / to filter, c to re-root there (which cds the shell too).
4. Press cmd-alt-t (ctrl-w shift-t) to flip through themes with live preview; enter writes the choice to your config.
5. cmd-t (ctrl-shift-t) for a tab, ctrl-w v for a split, ctrl-w p for the workspaces panel.

Font and color changes apply the moment you save the config file. [shell] and [prompt] changes apply to newly started sessions.

Using OmniPTY

Where OmniPTY keeps things

Getting help

Troubleshooting covers the usual suspects — missing glyphs, config errors, a prompt that didn't change — along with the current known limitations. Beyond that, open an issue on GitHub; Help → Report an Issue in the menu bar (the ☰ menu on Linux), or Report an Issue in the command palette, goes to the same place.

For questions, ideas, or just to see what's coming, join the OmniPTY Discord.