Documentation — QuickTTY

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

Download the latest stable release.
Open the DMG and move QuickTTY to Applications.
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

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

Keyboard Shortcuts

Primary shortcut

Toggle Normal ↔ Quake presentation

Switches the same live workspace between presentations without restarting shells. This is different from global F12, which shows or hides Quake.

Cmd+Opt+P toggle-presentation

Application/global

Action	Default shortcut	Action ID
Toggle Normal ↔ Quake	`Cmd+Opt+P`	`toggle-presentation`
Show/hide Quake globally	`F12`	`quicktty-global-toggle`Config key, outside local action registry
Open configuration	`Cmd+Comma`	`open-config`
Quit QuickTTY	`Cmd+Q`	`quit`

Tabs/panes

Action	Default shortcut	Action ID
New tab	`Cmd+T`	`new-tab`
Close pane	`Cmd+W`	`close-pane`
Close tab	`Cmd+Opt+W`	`close-tab`
Split right	`Cmd+D`	`split-right`
Split down	`Cmd+Shift+D`	`split-down`
Previous pane	`Cmd+Left-Bracket`	`previous-pane`
Next pane	`Cmd+Right-Bracket`	`next-pane`
Focus left	`Cmd+Shift+Left`	`focus-left`
Focus right	`Cmd+Shift+Right`	`focus-right`
Focus up	`Cmd+Shift+Up`	`focus-up`
Focus down	`Cmd+Shift+Down`	`focus-down`
Select tab 1	`Cmd+1`	`select-tab-1`
Select tab 2	`Cmd+2`	`select-tab-2`
Select tab 3	`Cmd+3`	`select-tab-3`
Select tab 4	`Cmd+4`	`select-tab-4`
Select tab 5	`Cmd+5`	`select-tab-5`
Select tab 6	`Cmd+6`	`select-tab-6`
Select tab 7	`Cmd+7`	`select-tab-7`
Select tab 8	`Cmd+8`	`select-tab-8`
Select tab 9	`Cmd+9`	`select-tab-9`
Toggle broadcast	`Cmd+B`	`toggle-broadcast`

Workspaces

Action	Default shortcut	Action ID
Select workspace 1	`Cmd+Opt+1`	`select-workspace-1`
Select workspace 2	`Cmd+Opt+2`	`select-workspace-2`
Select workspace 3	`Cmd+Opt+3`	`select-workspace-3`
Select workspace 4	`Cmd+Opt+4`	`select-workspace-4`
Select workspace 5	`Cmd+Opt+5`	`select-workspace-5`
Select workspace 6	`Cmd+Opt+6`	`select-workspace-6`
Select workspace 7	`Cmd+Opt+7`	`select-workspace-7`
Select workspace 8	`Cmd+Opt+8`	`select-workspace-8`
Select workspace 9	`Cmd+Opt+9`	`select-workspace-9`

Search/terminal

Action	Default shortcut	Action ID
Find	`Cmd+F`	`find`
Find next	`Cmd+G`	`find-next`
Find previous	`Cmd+Shift+G`	`find-previous`
Copy	`Cmd+C`	`copy`
Paste	`Cmd+V`	`paste`
Paste selection	`Cmd+Shift+V`	`paste-selection`
Select all	`Cmd+A`	`select-all`
Clear screen	`Cmd+K`	`clear-screen`
Increase font size	`Cmd+Equal`	`font-increase`
Decrease font size	`Cmd+Minus`	`font-decrease`
Reset font size	`Cmd+0`	`font-reset`
Scroll to top	`Cmd+Home`	`scroll-top`
Scroll to bottom	`Cmd+End`	`scroll-bottom`
Scroll page up	`Cmd+Page-Up`	`scroll-page-up`
Scroll page down	`Cmd+Page-Down`	`scroll-page-down`
Scroll to selection	`Cmd+J`	`scroll-to-selection`
Extend selection left	`Shift+Left`	`selection-left`
Extend selection right	`Shift+Right`	`selection-right`
Extend selection up	`Shift+Up`	`selection-up`
Extend selection down	`Shift+Down`	`selection-down`
Extend selection page up	`Shift+Page-Up`	`selection-page-up`
Extend selection page down	`Shift+Page-Down`	`selection-page-down`
Extend selection to home	`Shift+Home`	`selection-home`
Extend selection to end	`Shift+End`	`selection-end`

No default shortcut

These typed actions are available for customization but are unassigned by default.

Action	Action ID
New workspace	`new-workspace`
Rename workspace	`rename-workspace`
Delete workspace	`delete-workspace`
Copy URL	`copy-url`
Reset terminal	`reset-terminal`
Previous prompt	`previous-prompt`
Next prompt	`next-prompt`

Customize shortcuts

Local commands use repeatable assignments. An action receives a chord or the literal value disabled:

quicktty-shortcut = action-id=cmd+key
quicktty-shortcut = action-id=disabled

A chord has optional modifiers and exactly one key separated by +. Modifiers are cmd, opt, ctrl, and shift; canonical order is cmd+opt+ctrl+shift+key. Supported keys include letters, digits, F1–F20, arrows, navigation and named punctuation such as left-bracket, minus, and slash. A single key such as f12 is valid.

Assignment and conflict behavior

Parsing starts from the built-in defaults and processes repeated quicktty-shortcut lines from top to bottom. For each action, the last valid assignment wins; disabled is a valid assignment.

An unknown action or malformed assignment reports a diagnostic without blocking other valid lines. During hot reload, an invalid assignment for a known action preserves that action’s last active value. Deleting every assignment for an action restores its built-in default.

If two local actions use the same chord, the last valid owner wins and the previous owner becomes disabled. The separately registered global Quake chord takes priority over any conflicting local action.

Tabs, Splits & Workspaces

Tabs

Create a tab with Cmd+T, select tabs 1–9 with Cmd+1 through Cmd+9, and close the active pane with Cmd+W. Closing the last pane also closes its tab.

Splits

Split right with Cmd+D or down with Cmd+Shift+D. Move between panes using previous/next or directional focus commands. Splits form a resizable binary tree inside each tab.

Workspaces

Workspaces group tabs under a required, case-insensitively unique name. Only one is visible, but processes in the others remain active. Select workspaces 1–9 with Cmd+Opt+1 through Cmd+Opt+9.

QuickTTY can restore workspace descriptions, tabs, split layout, current working directories, and focus after restart. It starts new processes; it does not preserve live processes across application termination.

Quake Mode

Press Cmd+Opt+P to switch the existing window between Normal and Quake presentations. QuickTTY reuses the same panes and live processes; no shell is restarted.

While Quake presentation is active, F12 globally shows or hides it on the display under the pointer.

Configure startup mode, global chord, height, animation duration, padding, focus-loss behavior, and screen pinning with quicktty-presentation-mode, quicktty-global-toggle, and the related quicktty-quake-* keys.

Focus behaviorQuake mode hides after focus loss by default, except while a menu, sheet, or system dialog is active.

Broadcast Input

Toggle broadcast for the active tab with Cmd+B. The tab and workspace chrome show when it is active.

QuickTTY routes the original logical keyboard event to every pane in that tab, allowing each terminal to encode it for its own keyboard mode. Paste asks for confirmation once and then targets those panes. Mouse events, scrolling, resizing, and interface commands are never broadcast.

Broadcast automatically turns off when you change tab or workspace, restore the app, or encounter a target surface error.

Search

Start native terminal search with Cmd+F. Use Cmd+G for the next result and Cmd+Shift+G for the previous result. The overlay reports the current selection and total match count from Ghostty runtime callbacks.

Search is scoped to its terminal surface. Escape always closes search, regardless of whether the query is empty. Closing the pane clears its search state.

Coding Agent Integrations

QuickTTY shows standard OSC 9;4 progress as tab and workspace status. It does not infer agent identity from output, titles, prompts, or process trees.

Setup is manual: QuickTTY never installs hooks or changes agent configuration. Bundled integration files are located at:

/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/

Custom installation pathIf QuickTTY is installed elsewhere, replace /Applications/QuickTTY.app in the commands below. Always merge these examples into your existing configuration; never replace the whole configuration file.

Pi 0.82

Open /settings and enable Terminal progress (terminal.showTerminalProgress). It is off by default. No helper, hooks, or extensions are required.

Pi emits OSC 9;4 directly: working at agent_start, keepalive updates while working, and completed at agent_end.

Claude Code 2.1.141+

Claude Code command hooks have no controlling TTY. In claude mode, the helper emits one JSON object containing the universal terminalSequence field and writes nothing else to stdout.

Configuration

Merge the top-level hooks object from the bundled claude-settings.example.json into your existing Claude Code settings:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude working"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude waiting"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt|agent_needs_input",
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude waiting"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude working"
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude working"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude completed"
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude failed"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" claude completed"
          }
        ]
      }
    ]
  }
}

Event mapping

UserPromptSubmit → working.
PermissionRequest → waiting.
Notification matching permission_prompt|idle_prompt|agent_needs_input → waiting.
PostToolUse and PostToolUseFailure → working.
Stop and SessionEnd → completed.
StopFailure → failed.

The hook reads no stdin, prompt, transcript, or environment secrets.

Codex

Codex keeps its controlling TTY. In codex mode, the helper writes OSC directly to /dev/tty and writes exactly {} to stdout. If /dev/tty is unavailable, it still writes {} and exits successfully.

Configuration

Merge the top-level hooks object from the bundled codex-hooks.example.json into your existing hooks.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex working"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex waiting"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex working"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex completed"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"/Applications/QuickTTY.app/Contents/Resources/AgentIntegrations/quicktty-progress\" codex completed"
          }
        ]
      }
    ]
  }
}

Event mapping

UserPromptSubmit → working.
PermissionRequest → waiting.
PostToolUse → working.
Stop and SessionEnd → completed.

The hook reads no stdin, prompt, transcript, or environment secrets.

Helper contract

The bundled helper supports exactly these invocation forms:

quicktty-progress claude working|waiting|failed|completed
quicktty-progress codex working|waiting|failed|completed

States map to OSC 9;4 values as follows: working → 3, waiting → 4, failed → 2, and completed → 0.

An unknown mode, unknown state, or extra argument returns nonzero. The helper adds no new dependencies.

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.