Documentation

Architecture

Fastty is written in Rust using GPUI and the Alacritty terminal parser. It uses a low-level Paint API with strict monospace cell advance (force_width). Block characters (U+2580..=U+259F) and box-drawing lines (U+2500..=U+257F) use geometric synthesis to prevent hairline gaps.

Installation

Install pre-built release binaries for your operating system:

macOS & Linux

curl -fsSL https://raw.githubusercontent.com/diegoleteliers10/fasty/main/instalar.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/diegoleteliers10/fasty/main/instalar.ps1 | iex

Build from source

git clone https://github.com/diegoleteliers10/fasty.git
cd fasty
cargo build --release

CLI Usage & AI Agent Integration

Launch Fastty and automate sessions from scripts or AI coding agents:

fastty [OPTIONS] [-- <CMD>...]

• -d, --dir, --working-directory <DIR>: Set starting directory.
• -t, --title <TITLE>: Set initial tab and window title.
• -e, --exec, --command <CMD...>: Execute command with arguments.
• -- <CMD...>: Pass trailing command directly.
• -v, --version: Print version information.
• -h, --help: Print help options.

Session Control Subcommands

Talk to a running fastty's daemon from scripts and agents:

id=$(fastty spawn --cwd ~/api -- bun run dev)  # headless session, prints id
fastty write $id --enter 'git status'         # type into it (submits the line)
fastty resize $id 120 40                      # resize its PTY
fastty close $id                              # terminate a headless session
fastty list --json                            # alias of `fastty sessions`

write and resize ack with a done event, so exit codes are truthful. GUI panes can't be closed over the protocol (not_closable).

AI Agent Example

fastty --title "Dev Server" -d ~/api -e bun run dev

MCP Server & AI Agents

fastty mcp is a local Model Context Protocol server over stdio that connects AI agents — Claude Code, OpenCode, Codex, Cursor, Zed, Gemini CLI — to fastty's daemon. With the GUI open, agents share its live sessions; without it, the MCP process embeds its own daemon and agents work headless.

Registering into an agent

fastty mcp setup              # list supported agents and config paths
fastty mcp setup opencode     # writes the fastty entry into opencode.json
fastty mcp setup claude-code  # merges into the project's .mcp.json
fastty mcp setup codex        # [mcp_servers.fastty] in config.toml (comments preserved)

Supported agents: claude-code, opencode, codex, gemini, cursor, zed, claude-desktop. Registration is idempotent and uses the resolved fastty binary path. Manual registration also works: run fastty mcp as the server command (stdio transport).

Tools exposed

• fastty_list_sessions: live sessions (id, title, cwd, size, alive).
• fastty_spawn_session: start a session and return its id — by default it also opens as a visible tab in the fastty window (open: false keeps it headless), sharing the exact same terminal: you watch the agent type.
• fastty_write_session: type into a session, enter to submit.
• fastty_read_screen: read the screen as text (optionally with scrollback).
• fastty_resize_session / fastty_close_session: resize a headless grid / terminate a session. Closing a GUI tab needs force: true — those tabs belong to you.
• fastty_run_command: run a shell command in a throwaway session, wait for exit, return the terminal's real rendered output (last 300 lines), close the session. The fast path for builds, git status, and inspection.
• fastty_layout: the full window structure — every tab with its panes (ids, titles, cwds, sizes) — so the agent knows what shares a tab before splitting.
• fastty_split_pane: create a new pane beside any visible pane (same tab, left/right/top/down), running the shell or a custom command; returns its session id.
• fastty_resize_pane: move a pane divider by a fraction of the split axis.
• fastty_focus_pane: bring a pane's tab to the front and make it active, so you see what the agent is working on.
• fastty_resize_window: resize the fastty window itself, approximately to cols × rows.

Screens are read through the compressed binary snapshot protocol (FST1 v2, scrollback included) and rendered to text inside the MCP process. With no fastty window running, agents still work headless — the MCP process embeds its own daemon, and layout tools answer no_gui.

Agent Status Hooks

Fastty can show when Claude Code, Gemini CLI, Codex CLI, OpenCode, and Pi are working, waiting, done, or in an error state. Start the agent from a Fastty terminal so it inherits the session token.

Install or remove a hook

fastty agent-hook install claude --project
fastty agent-hook uninstall claude --project

# Use --user to change the user-level configuration

Replace claude with gemini, codex, opencode, or pi. Project hooks apply to the current project. User hooks apply to the user's configuration. Fastty preserves unrelated settings and removes only its own entries.

These hooks report agent status. They do not read agent messages, approve permissions, or send terminal input.

AI Assistant

The built-in agent sidebar streams answers with collapsible reasoning and a live token-usage context ring. Tools (read_file, search, run_command, edit_file) request permission (Allow / Allow Always / Decline) and file edits render as reviewable diff cards before applying.

• Providers (BYOK): Anthropic, OpenAI-compatible endpoints, and local Ollama (default) — configured in Settings → AI Assistant.
• Multimodal chat: paste images with ⌘V (auto-scaled, sent as vision blocks) and attach PDFs (sent as native document blocks).
• Rich answers: Markdown with syntax highlighting, LaTeX math, and copy buttons on messages and code blocks.
• One-shot CLI: ask from any shell without opening the sidebar.
• Learned auto-allow: after you manually approve the same command family three times (cargo test, git status…), fastty offers to auto-allow it from then on. Scoping is subcommand-aware (git status never unlocks git push), shells and interpreters are never suggested, the hardcoded danger layer always runs first, and rules persist across restarts. Disable with [ai] learned_allow = false.
• Attach terminal output: select text in a terminal, open its context menu, and choose Attach to AI panel. Fastty adds the selection, working directory, and a safe process command to the built-in AI draft. It opens the AI panel and keeps the draft unsent so you can review it.
• Focus and alerts: the terminal cursor appears when the terminal has focus, even while the AI panel stays open. Native alerts report agent completion, errors, or requests for input. Fastty suppresses interim alerts while an agent works.

fastty ask "why is this build failing?"

Core Features

• Mission Control / Tab Peek: ⌘⇧O / Ctrl+Shift+M for interactive visual grid overlay of all tabs, split panes, process icons, and live buffer previews.
• Global Multi-Tab Search: ⌘⇧F / Ctrl+Shift+F powered by fff-search to search scrollback buffers across all active tabs simultaneously.
• Session & Workspace Persistence: Keep supported terminal processes alive when Fastty closes, then reconnect to the same host on launch.
• SSH Host Manager with Mux Semantics: ⌘O / Ctrl+Shift+O with environment tags (#prod, #dev, #aws), active connection badges, and 1-key reconnect (r).
• Deck Process Icons: Dynamic foreground process icons (nvim, cargo, node, git, docker, ssh) on tabs and sidebar.
• Config Importer & Keybinding Presets: 1-click import from Ghostty, Alacritty, Kitty, tmux, and WezTerm, plus presets (Default, Ghostty, tmux, iTerm2).
• Hardware-accelerated Kitty Graphics: Full protocol support (PNG/RGBA/RGB) rendered directly via GPUI on GPU.
• Kitty Clipboard Protocol (OSC 5522): programs can read and write the clipboard including images (as PNG) — the mechanism tools like Claude Code use to paste images into the terminal. Reads are permission-gated (clipboard_read).
• Universal Insert: ⌃⌘, opens one anchored fuzzy picker that inserts workspace files, SSH hosts, git branches, snippets, or running docker containers at the prompt.
• Automatic Contrast Correction: program-requested colors that clash with the theme get their Oklab lightness adjusted (hue preserved) until they read — light themes included.
• 20 Built-in Themes: Catppuccin (×4), Dracula, Nord, Tokyo Night (+ Storm), Gruvbox (dark/light), Rosé Pine (×3), One (dark/light), Solarized (dark/light), Kanagawa — with six light themes and a Settings dropdown.
• MCP Agent Server: fastty mcp connects Claude Code, OpenCode, Codex and friends to your terminals over the Model Context Protocol.
• Command Palette: ⌘P / Ctrl+Shift+P with fuzzy search.
• Project Jumper: ⌘J / Ctrl+Shift+J for quick directory navigation.
• Git Worktree Switcher: ⌘⌥W / Ctrl+Alt+W to switch worktrees instantly.
• Smart Token Detection: Automatic underline and click actions for URLs, file paths, and hex colors.
• Tab Management: Horizontal tabs or vertical tab sidebar (⌘B), drag tear-out into standalone windows.
• Prompt Navigation: Jump between commands with ⌘⇧↑ and ⌘⇧↓ via semantic shell integration.
• Synchronized Output: DEC Mode 2026 support for flicker-free TUI rendering.
• Full IME & Latin Dead Keys: Native composition for international inputs.
• AI Assistant Sidebar: Agentic chat with tools, permission flow, diff cards, image/PDF attachments, and fastty ask CLI.

Project Git Panel

Open the project panel from the bottom bar in a Git repository. Use its tabs to switch between file changes and the commit graph.

Changes

• Review staged and unstaged files, with added and removed line counts.
• Select files with the checkbox at the right of each row. A checkbox controls staging. It does not hide the file from the list.
• Use the Stage All menu to stage or unstage all files, restore changes, stash all or tracked changes, view the stash, discard tracked changes, or trash untracked files.

Graph

Browse commits with colored branch lines and labels for local and remote branches. Each color marks a different branch path through the commit history.

Mission Control & Tab Peek (⌘⇧O)

Press ⌘⇧O (macOS) or Ctrl+Shift+M (Linux/Windows) to open the Mission Control grid view. Fastty renders live miniature visual snapshots of every open tab and directional split pane:

• Live Buffer Snapshots: Preview active code, build output, or TUI sessions in real time.
• Deck Process Icons: Automatically identifies foreground tools like nvim, cargo, node, docker, git, and ssh.
• Keyboard Navigation: Use arrow keys (←, →, ↑, ↓) or H/J/K/L to navigate between tab cards.
• Instant Actions: Press Enter to jump to any tab, D or X to close it, and T or N to open a new tab.

Unified Multi-Tab Global Search (⌘⇧F)

Press ⌘⇧F (macOS) or Ctrl+Shift+F (Linux/Windows) to search across the scrollback buffers of all active tabs and split panes concurrently:

• Powered by fff-search: High-performance fuzzy and exact token search matching.
• Grouped Tab Cards: Results are clustered by tab, showing process badges, tab titles, exact line numbers, and matching snippets.
• Instant Jump: Selecting any search result with Enter immediately switches to that tab, activates the corresponding split pane, and scrolls directly to the matched line.

Session & Workspace Persistence

Fastty keeps supported terminal hosts running when you close the app. On the next launch, it reconnects to the same host and restores its tabs and panes. Agent processes such as Claude Code and OpenCode can keep working while the Fastty window is closed.

• Restore: Fastty reconnects to the existing host. It does not start a replacement process when the original host is available.
• Older sessions: Fastty can restore saved workspaces from older versions. If an older host cannot report process state, Fastty asks before it closes that session.
• Missing host: Fastty opens a new shell when it cannot find the saved session. That shell does not resume the old process.

SSH Host Manager with Mux Semantics (⌘O)

Press ⌘O (macOS) or Ctrl+Shift+O (Linux/Windows) to browse and connect to remote hosts defined in ~/.ssh/config:

• Environment Tags: Automatically tags hosts (#prod, #dev, #aws, #vps, #homelab) or reads custom comments like # tag: staging.
• Active Session Badges: Displays a green ● Active badge for hosts currently connected in an open tab.
• Resilient Keepalive: Built-in TCP keepalive (ServerAliveInterval=15, ServerAliveCountMax=3).
• 1-Key Reconnection: If the connection drops or the network changes, Fastty preserves the buffer and displays an interactive prompt to reconnect instantly with r.

Split Panes

Divide any tab into multiple terminal panes:

• Split Right: ⌘D (macOS) / Ctrl+Shift+E (Linux/Windows)
• Split Down: ⌘⇧D (macOS) / Ctrl+Shift+D (Linux/Windows)
• Navigate Panes: ⌘⌥Left / Right / Up / Down (macOS) / Alt+Left / Right / Up / Down (Linux/Windows)
• Close Active Pane: ⌘W (macOS) / Ctrl+Shift+W (Linux/Windows)
• Close Entire Tab: ⌘⇧W (macOS) / Ctrl+Shift+Q (Linux/Windows)

Config Importer & Keybinding Presets

In the Settings Window (⌘,), Fastty detects existing configurations and offers 1-click adoption:

• Supported Sources: Ghostty, Alacritty, Kitty, tmux (~/.tmux.conf), and WezTerm.
• Keybinding Presets: Switch dynamically between Default, Ghostty, tmux, and iTerm2 shortcut profiles.

Kitty Graphics Protocol

Fastty natively supports the Kitty Graphics protocol (\x1b_G...):

• GPU-Accelerated Rendering: Decodes and displays PNG, RGBA32, and RGB24 graphics directly in the terminal cell grid via GPUI and Metal/Vulkan.
• Scroll & Viewport Aware: Inline images anchor to terminal rows and scroll smoothly with terminal history.

Kitty Clipboard Protocol & Images

Fastty implements kitty's multi-format clipboard protocol (OSC 5522) and answers the CSI ? 5522 $ p probe, so programs can detect and use it:

• Writes: chunked multi-MIME clipboard writes — plain text and images (decoded through image and applied via arboard). Always allowed.
• Reads: text/plain and images (always returned as PNG) in ≤4KB packets. Permission-gated by clipboard_read in fastty.toml (default on; denied reads reply EPERM).
• Why it matters: this is the mechanism Claude Code-style tools use to paste images into the terminal. The classic text-only OSC 52 write path keeps working unchanged.

Bottombar Widgets

Fastty includes an extensible status bar with live widgets:

• git: Active git branch and dirty status.
• git-actions: Status of GitHub Actions runs.
• git-prs: Active open Pull Requests count.
• git-sync: Ahead and behind commit counter.
• kube: Active Kubernetes context and namespace.
• aws: Current AWS profile and region.
• time: Clock with configurable format and timezone.
• command: Custom shell command output with optional on_click handler.

Snippets System

Fastty expands snippets in place when you press Tab at the prompt. Snippets are stored in ~/.config/fastty/snippets.toml and reload automatically on save.

Placeholders support jump indices and default values:

• $1, $2, ...: Jump markers.
• ${1:default}: Placeholder with default text.
• $0: Final cursor destination.

[snippet]
gst = "git status -sb"
gco = "git checkout $1"
gcm = "git commit -m \"${1:commit message}\""
pr = "gh pr create --title \"${1:title}\" --body \"${2:body}\""

Configuration Guide

Fastty searches for configuration in this order:

1. ./fastty.toml (Current directory, portable mode)
2. /etc/fastty/fastty.toml (System-wide)
3. ~/.config/fastty/fastty.toml (macOS/Linux user config) or %APPDATA%\fastty\config\fastty.toml (Windows)

theme = "default"
opacity = 1.0
scrollback = 10000
session_restore = true
copy_on_select = false
notify_on_command_finish = true
tab_layout = "horizontal" # or "vertical"
option_as_meta = false    # true treats Option key as Alt (macOS)
contrast_correction = true  # re-tune clashing program colors (Oklab)
clipboard_read = true       # allow programs to read the clipboard (OSC 5522)

[font]
family = "monospace"
size = 14.0
weight = 400.0
ligatures = true

[cursor]
shape = "beam" # "beam", "block", "underline", or "hollow_block"
blink = true

[bottombar]
widgets = [
  { type = "git", align = "left", interval_ms = 1000 },
  { type = "kube", align = "left" },
  { type = "aws", align = "left" },
  { type = "command", name = "node", command = "node -v", align = "right" },
  { type = "time", align = "right", format = "%H:%M:%S" }
]

[keybindings]
"super+d" = "SplitRight"
"super+shift+d" = "SplitDown"

[ai]
permission_mode = "confirm-writes" # or "confirm-all", "yolo"
learned_allow = true               # offer auto-allow after 3 approvals of a family

Built-in Themes

Fastty ships 20 built-in themes — six of them light, its first — switchable from the command palette (with live preview) or the Settings → Appearance dropdown:

Dark: Fastty Default, Catppuccin Mocha / Frappé / Macchiato, Dracula, Nord, Tokyo Night / Storm, Gruvbox Dark, Rosé Pine / Moon, One Dark, Solarized Dark, Kanagawa Wave, High Contrast. Light: Catppuccin Latte, Gruvbox Light, Rosé Pine Dawn, One Light, Solarized Light.

Chrome (surfaces, borders, hover, selection) is derived from each theme's background lightness, so light themes get light chrome everywhere — tabs, sidebar, settings. Config: theme = "tokyo-night-storm". The config importer maps theme names from all these families when migrating from Ghostty, Kitty, Alacritty, WezTerm or tmux.

Automatic Contrast Correction

Terminal programs bias to dark mode: TUIs request explicit colors tuned for dark backgrounds that turn invisible on light themes (and vice versa). Fastty detects when a program-requested color's WCAG contrast against what it sits on drops below 3:1 and fixes it in Oklab space:

• Hue & chroma preserved: only the lightness channel is binary-searched away from the background, until the pair reads (~4.5:1).
• Theme colors untouched: named ANSI colors belong to the theme; only explicit truecolor and 256-color indexes are candidates. Explicit backgrounds are corrected against the theme foreground.
• Cheap: corrections are cached per (color, background) pair — the render loop pays one hash lookup per colored cell.

# fastty.toml (default on)
contrast_correction = true

Toggle in Settings → Terminal Behavior. Palette and global-search previews are corrected too.

Custom Themes

Add custom themes as JSON files into ~/.config/fastty/themes/<name>.json. Each theme defines 18 hex color slots:

{
  "background": "#080808",
  "foreground": "#e5e2e1",
  "black": "#1c1b1b",
  "red": "#ff5555",
  "green": "#50fa7b",
  "yellow": "#f1fa8c",
  "blue": "#bd93f9",
  "magenta": "#ff79c6",
  "cyan": "#8be9fd",
  "white": "#bfbfbf",
  "bright_black": "#4d4d4d",
  "bright_red": "#ff6e6e",
  "bright_green": "#69ff94",
  "bright_yellow": "#ffffa5",
  "bright_blue": "#d6acff",
  "bright_magenta": "#ff92df",
  "bright_cyan": "#a4ffff",
  "bright_white": "#ffffff"
}

Keyboard Shortcuts Reference

Since 0.14.0 every shortcut below is editable in Settings: click any shortcut and press the new keys. Conflicts ask before reassigning, and each action offers reset and unbind plus a reset-all back to the preset defaults (Default, Ghostty, tmux, iTerm2). The tables show the Default preset.

Default Keybindings

Preset Profiles Matrix

Switch between keybinding presets instantly in Settings (⌘,) or via fastty.toml with preset = "ghostty" | "tmux" | "iterm2" | "default":

Daemon Protocol & IPC Multiplexing

Fastty includes a local daemon that lets scripts and tools observe and control terminal sessions. The Unix socket uses user-only permissions. Access scopes limit each client to observe, interact, or manage. A client can lower its scope, but cannot raise it.

Listing Active Sessions

# List all active tabs and split panes
fastty sessions

# Watch session changes in real time (reactive stream)
fastty sessions --watch

Attaching Interactively

# Interactive attachment (raw PTY streaming, Ctrl+\ to detach)
fastty attach 1

# Read-only preview (monitor builds/servers without sending keystrokes)
fastty attach 1 --read-only

# Wait for a session to appear before attaching
fastty attach 1 --wait=30

Controlling Sessions from Scripts

# Spawn a headless session (prints its id; no command = user's shell)
id=$(fastty spawn --cwd ~/api -- bun run dev)

# Type into it (with --enter to submit), resize it, close it
fastty write $id --enter 'git status'
fastty resize $id 120 40
fastty close $id

Inspecting sessions and events

fastty capture 1       # read the visible screen
fastty focus 1         # show the session in the window
fastty send 1 --enter -- 'git status'
fastty events          # watch session and agent state changes

The event stream sends an initial snapshot and then ordered changes. If a client falls behind, Fastty sends a gap event and a replacement snapshot. Replace local state with that snapshot before reading later events. Screen capture returns visible text only, with a 1 MiB limit.

External text input and session close actions can require approval in the visible Fastty window. A client with interact can send text. A client with manage can close sessions.

JSON Wire Protocol

All communication uses newline-delimited JSON (NDJSON) over the Unix socket. Key commands include hello, list, subscribe_sessions, attach, detach, write, resize, spawn, close, and binary_snapshot. The full wire spec lives in the repo's docs/daemon-protocol.md.

• Opt-in acks: write and resize accept ack: true and reply with a done event (or error) so scripts get truthful exit codes. Clients that omit it keep the silent streaming behavior.
• Error codes: bad_request, no_such_session, invalid_base64, not_attached, read_only, spawn_failed, not_closable (GUI panes are protocol-protected).
• Binary snapshots (FST1 v2): binary_snapshot returns the full terminal state — compressed scrollback + screen + cursor — restored in microseconds by the web client.

Web Gateway & Fastty-Wasm

Access your active Fastty terminal sessions from any web browser, iPad, or remote machine via the native embedded Web Gateway (fastty gateway) and WebAssembly client (fastty-wasm).

Starting the Gateway

# Start on default port 8765 (http://localhost:8765)
fastty gateway

# Bind to custom port and network interface (e.g. Tailscale / LAN)
fastty gateway --port 8765 --host 0.0.0.0

# Enforce read-only access for all browser sessions
fastty gateway --port 8765 --read-only

Pure WebAssembly VT Engine

The web client is powered by crates/fastty-wasm, an optimized VT emulation engine compiled to WebAssembly that renders directly into an HTML5 <canvas>:

• Zero External Dependencies: No heavy JavaScript terminal libraries needed.
• Batched 2D Canvas: Batched font rendering and background quad fills at 60/120 FPS.
• Interactive Controls: Zoom font in/out, draggable scrollbar, mouse wheel, and touch/trackpad navigation.
• RFC 6455 WebSockets: Low-latency streaming bridge directly to the Fastty daemon socket.
• Binary Snapshot Restore: on reconnect the client restores the full terminal state — including scrollback — from a compressed binary snapshot (FST1 v2) in microseconds, not by re-parsing ANSI.