QuickTTY app icon QuickTTY

All documentation / Setup guide

Setup guide

Getting started

Install the signed app, understand its configuration files, and get to a reliable first workspace.

Getting Started

QuickTTY is a native macOS terminal workspace for Apple Silicon. It keeps tabs, binary splits, and named workspaces inside one physical window. Switching a workspace or changing between normal and Quake presentation does not restart its live shell processes.

Requirements

  • macOS 15 or newer.
  • An Apple Silicon Mac.
  • A downloaded, signed, and notarized QuickTTY DMG.

On first launch QuickTTY creates a Default workspace. Use the menus or default shortcuts to add tabs and split the active tab. Inactive workspaces continue running until the application exits.

Installation & Updates

  1. Download the latest stable release.
  2. Open the DMG and move QuickTTY to Applications.
  3. Launch QuickTTY. macOS can verify its Developer ID signature and notarization ticket.

Update channels

The default stable channel reads the current GitHub latest feed and receives stable releases only. It never receives a prerelease.

The opt-in beta channel reads the versioned feed tracked in the QuickTTY repository. It is a superset of stable and offers the newest public build, whether that build is stable or beta. A newer stable can therefore follow a beta while the app remains subscribed to the beta channel.

quicktty-update-channel = beta

Use QuickTTY → Check for Updates… to request a check. See the release channels page for the current build.

Configuration

The exact user configuration path is:

~/.config/quicktty/config

Keys prefixed with quicktty- configure the workspace shell. Other supported terminal keys pass to Ghostty, except top-level keybind assignments: QuickTTY owns keyboard command routing and clears Ghostty bindings in its generated effective configuration.

Choose QuickTTY → Open Configuration… to edit the file in a terminal tab. Valid changes hot reload without recreating terminal surfaces or shell processes. If parsing fails, the last valid configuration remains active and an inline diagnostic identifies the file and line.

theme = catppuccin-mocha
font-size = 14
copy-on-select = clipboard

quicktty-presentation-mode = normal
quicktty-global-toggle = f12
quicktty-quake-height = 75%
quicktty-restore-workspaces = true
quicktty-restore-agent-sessions = true

Agent restoration requires both restore keys. It relaunches an eligible native agent by an opaque session ID into its original pane; it is not a PTY or process checkpoint. QuickTTY persists no arbitrary command or environment for restoration, and an unverified or invalid binding uses a fresh shell fallback.

The generated sibling file ~/.config/quicktty/.ghostty-effective-config belongs to QuickTTY and should not be edited.

Troubleshooting

A configuration change is ignored

Read the inline diagnostic, correct the reported line in ~/.config/quicktty/config, and save again. QuickTTY keeps the last valid configuration while errors remain.

A shortcut reaches the shell

Confirm its action ID and chord in the full registry. An unassigned or non-performable event intentionally follows the normal terminal input path.

A pane failed to start

Use Retry to create a fresh shell in the saved working directory, or Close Pane to remove the failed leaf without disturbing neighboring sessions.

An update is not offered

Confirm the selected channel. Stable excludes prereleases; beta follows the newest build in its repository feed. QuickTTY 0.1.1 may require a manual download of 0.1.2 because its stable feed was incomplete.