How to use Ghosthub

Open a tmux session

Launch Ghosthub and expand your Mac under Hosts. Existing tmux sessions appear automatically alongside projects and worktrees. Select one to attach with an ordinary tmux client.

Use the + menu to create a named session or add an existing project. The command palette offers the same actions, plus commands to open any discovered session.

To keep tool-owned standalone sessions out of navigation, open Settings → Worktrees and add hidden tmux session patterns, one per line. Patterns are case-sensitive and support * for any number of characters and ? for one character. Ghosthub stores them in ~/.config/ghosthub/config.toml; matching kwt workspaces remain visible under their projects.

Closing the Ghosthub window only detaches. Your work keeps running in tmux. To end a standalone session Ghosthub knows is running, hover its row and click the subtle ×. A worktree-backed session keeps Kill Session… in its action menu, beside the separate worktree-removal control. Ghosthub confirms the host and exact tmux instance before terminating its windows, panes, and processes. It cancels the action if that host’s connection changes or if the session disappears and is replaced under the same name, and keeps an active attachment open if the kill fails. Switching to another session while the command completes does not navigate away from the new selection. The same command is available in the command palette.

Add an SSH host

Open Settings → Hosts and add any destination accepted by your SSH configuration, such as devbox or alice@build-server. Importing from Tailscale uses the user resolved by your OpenSSH configuration (falling back to your local username) and preserves each host’s full MagicDNS name.

Remote hosts need tmux. Ghosthub follows your OpenSSH configuration for users, ports, keys, and routing. If OpenSSH encounters an unseen key under an interactive trust policy, Ghosthub shows the exact destination and fingerprint for approval. Passwords and other interactive challenges use a native secure-entry sheet that names the host requesting the response. Responses are kept only for the app session, and Continue can deliberately send an empty response when a challenge requires one.

ProxyJump routes are handled one host at a time, with every trust and credential prompt naming the hop that controls it. Ghosthub refuses opaque ProxyCommand routes and jump hosts that themselves use another proxy because it cannot safely review those intermediate policies. An unreachable machine never blocks the rest of your fleet.

Native Windows support is experimental. Choose Windows (psmux) for a Windows OpenSSH host with PowerShell and psmux installed, including its tmux.exe alias. After testing the connection, Install Bundled kwt uploads Ghosthub’s matching AMD64 or ARM64 helper for that user. The Windows helper is currently unsigned, so this path is intended for development machines and power users until Authenticode signing is available.

To add project and worktree context without installing kwt, a Git worktree manager, system-wide, test the connection and choose Install kwt Worktree Helper. Ghosthub asks through that explicit action, then copies its pinned build for the host’s OS and CPU, verifies it, and keeps it under ~/.ghosthub/. On a fresh macOS or Linux host, open the + menu beside it, choose Add Project, and enter each existing checkout’s absolute path. Ghosthub delegates registration to kwt and refreshes inventory without scanning the machine. Project registration is not yet available for Windows hosts. If the host’s SSH address changes while Add Project is open, close the sheet and try again against the updated host. Tmux-only hosts do not need either step.

If a host shows a caution icon, click it to review trust, authenticate, or retry the connection. Ghosthub confirms success before dismissing the sheet and retries inventory automatically. Reachable hosts keep any separate inventory diagnostic visible so you can retry it without repeating SSH setup. An expanded host with no projects or tmux sessions says so in the sidebar.

Add project and worktree context

Open the + menu beside your local Mac or a remote macOS or Linux host, choose Add Project, and enter the absolute path to an existing checkout. Ghosthub registers that repository through its bundled or managed kwt helper without scanning the machine. Windows project registration is not yet supported.

Pull-request import requires the GitHub CLI (gh) on the host containing the project: your Mac for a local project or the SSH machine for a remote one. Install it there and run gh auth login on that same host before importing. For an HTTPS Git remote, ordinary Git authentication must also work on that host; gh auth setup-git configures GitHub CLI as a Git credential helper.

Select a project and press ⌘⇧N. UseBranch to search local and remote branches that are not already checked out. Pick one to create its worktree, including a local tracking branch when the source is remote, or type a new branch name. UsePull Request to find and import an open GitHub pull request. You do not need to install or run kwt separately. Selecting a listed worktree creates or repairs its canonical tmux session when needed, then attaches an ordinary tmux client. Kwt remains optional if you only want a local and remote tmux session switcher. Remote tmux copy-mode can write copied text to the Mac clipboard through OSC 52, while paste follows the configured terminal shortcut and libghostty’s safe paste path.

To remove a non-primary worktree, hover its sidebar row and click the ×. After confirmation, Ghosthub terminates that worktree’s live tmux session if necessary and asks kwt to remove the checkout. If the checkout is already gone, Ghosthub skips the redundant kwt removal but still reconciles the exact live tmux session covered by the confirmation. The Git branch is kept.

Move through the fleet without the mouse

Press ⌘⇧P for the Command Palette. Search across hosts, projects, worktrees, appearance, settings, and common actions, then press Return to go. When an attached tmux session is active,Apply Theme to Current Session rethemes it without detaching or enabling the persistent shared-session override.

Build your command center

Ghosthub supports native macOS tabs alongside independent windows. Press ⌘T to open a workspace tab in the current window, or ⌘N to open a separate window. Each one can attach to a different tmux session.

These tabs group complete Ghosthub workspaces; tmux still owns the windows and panes inside each attached session. Use the macOSWindow menu to move a tab into its own window or merge separate windows into one tab group.

Press ⌘B in any window to hide its sidebar and give the terminal the full frame. Press it again whenever you need fleet navigation back. Drag worktrees within a project or standalone tmux sessions within a host to arrange them; the insertion line previews the destination. Ghosthub remembers these display orders without changing anything in kwt, git, or tmux.

Make the terminal yours

Terminal preferences live in Ghosthub Settings. For the full configuration surface, edit ~/.config/ghosthub/ghostty.conf.

Quit confirmation is on by default. Change it at Settings → Terminal → Confirm before quitting Ghosthub. Closing the final workspace leaves Ghosthub running; use Command-Q to quit. Quitting or closing windows only detaches and leaves every tmux session running.

The file uses Ghostty’s configuration format, but is isolated from Ghostty.app. The Tmux Theme picker supplies colors for new sessions created by Ghosthub. Existing sessions keep their own appearance by default; Ghosthub does not place a local palette over them. An explicitApply theme to shared tmux sessions opt-in applies the selected colors before future attachments. Follow ghostty.conf uses the effective foreground and background for the current light or dark appearance, just like the built-in themes. To update only the connected active session immediately, choose Session → Apply Theme to Current Session or the matching Command Palette action. Both choices update the session’s existing windows and chrome for every attached terminal; they do not target the Console Panel and are unavailable for native Windows sessions. Ghosthub reloads terminal configuration when it changes.