Getting Started

System Requirements

Install

1. Download the latest Zentty DMG.
2. Open the DMG and drag Zentty into Applications.
3. Launch Zentty and approve macOS prompts if they appear.
4. In a Zentty pane, run zentty version to confirm the bundled CLI is on the session path.

Zentty updates itself through Sparkle after installation. Builds are signed and notarized by Zenjoy BV. The app currently requires macOS 14 Sonoma or later.

Verify Your Install

Open a fresh Zentty pane and check that the bundled CLI is available. The exact version changes by release, but the command should print a version and commit-like build identifier.

zentty version
zentty list windows --json

If zentty is not found in a normal macOS Terminal window, that is expected unless you created your own symlink or alias. Inside Zentty panes, ZENTTY_CLI_BIN points at the bundled binary.

First Session

1. Start in the first pane like any terminal.
2. Press Cmd+D to add a pane to the right.
3. Press Shift+Cmd+D to add a pane below.
4. Press Shift+Cmd+P to open the command palette.
5. Press Cmd+T when a task deserves its own worklane.

The default layout adapts to display size. On wider screens, adding a pane to the right can create a new visible column; on smaller screens Zentty can add the pane further along the horizontal worklane so the focused pane stays readable.

Agent Prerequisites

Zentty wraps agent CLIs; it does not install the agents themselves. Install and authenticate the tool you plan to run before using the launch command inside Zentty.

Launch An Agent

Open a normal Zentty pane and run the CLI you already use, such as claude or codex. Zentty keeps the command itself unchanged; it only adds the routing environment and hooks needed to show agent state in the app.

After launch, check the sidebar. It should show the tool name and whether the agent is running, idle, or waiting for you. Approval prompts, questions, and sign-in requests are marked as needing input so they stay visible from the sidebar and window chrome.

Restore

Workspace restore is on by default. On launch, Zentty restores meaningful windows, worklanes, columns, panes, working directories, labels, colors, and known agent context. If you close a pane, Shift+Cmd+T restores the most recent closed pane when enough context is available.

Updates

Zentty uses Sparkle for in-app updates. Stable builds stay on the stable channel by default; beta builds can be enabled from Settings when you want earlier fixes. Update prompts are user-visible, release notes are linked from GitHub Releases, and failed update attempts should leave the existing app in place.

To roll back, quit Zentty, install an older signed DMG from GitHub Releases, and keep your ~/.config/zentty folder unchanged.

Uninstall

Quit Zentty, move the app from Applications to the Trash, then remove local settings only if you want a clean slate.

# Optional clean state
trash ~/.config/zentty
trash ~/Library/Application\\ Support/zentty
trash ~/Library/Caches/zentty

Useful First Settings

• Open settings with Cmd+,.
• Choose a left-hand or right-hand shortcut preset if the defaults do not match your muscle memory.
• Pick your Ghostty theme and adjust background opacity.
• Choose which editors and tools appear in the Open With control.
• Decide whether clean copy should be automatic for all copies.

First Troubleshooting