Skip to content

Projects, worktrees, and directories

Projects and worktrees add Git context to Ghosthub's ordinary tmux workflow. They are optional.

Ghosthub delegates repository and worktree identity to kwt. Packaged builds use their revision-pinned bundled kwt locally and a matching managed helper on remote macOS or Linux hosts.

Register a project

Start with an existing Git checkout on the target host.

  1. Expand the local Mac or a remote macOS or Linux host.
  2. Select the + beside Projects.
  3. Enter the checkout's absolute path on that host.
  4. Confirm the registration.

Ghosthub registers that one path through kwt and refreshes inventory. It does not scan the machine or edit kwt configuration itself.

Ghosthub automatically maintains the managed kwt helper on configured remote macOS and Linux hosts. Project registration is not yet available for native Windows hosts.

If the SSH destination changes while the Add Project sheet is open, close the sheet and start again so the confirmation applies to the current host.

Register a plain directory

A hub, notes tree, or other directory that is not a Git checkout can still use the same kwt layouts and Ghosthub terminal flow. Register it on the target host:

kwt workspace add /absolute/path/to/directory

Refresh Ghosthub. The directory appears as one flat row in Projects, after the repository rows. It has no expandable worktree children because one registered directory owns one workspace session.

Select the row to let kwt create or repair its configured layout and attach the ordinary tmux client. Removing the registration with kwt workspace remove does not end a live session; after refresh, that session remains available under Tmux Sessions.

Open a project checkout

Select the project's primary checkout or any linked worktree in the sidebar. Kwt supplies the exact canonical tmux session name. Ghosthub creates or repairs that session when necessary and then attaches an ordinary tmux client. A status glyph on the worktree row indicates when current discovery confirms its tmux session is live, including while Ghosthub is detached. Cached sessions do not remain marked live while the host is unreachable.

By default, a live kwt-managed session appears only on its worktree row instead of being duplicated under Tmux Sessions. Open Settings → Worktrees and turn off Hide kwt-managed sessions from Tmux Sessions if you want both entries visible.

Create a worktree from a branch

  1. Select the project.
  2. Press Shift+Cmd+N or choose the new-worktree action.
  3. Select Branch.
  4. Search local and remote branches that are not already checked out, or type a new branch name.
  5. Confirm the worktree.

Selecting a remote source creates a local tracking branch when needed. The picker distinguishes same-named sources. Input that does not match an existing branch creates a new branch.

Import a GitHub pull request

Pull-request import requires the GitHub CLI on the host that contains the project—not merely on the Mac running Ghosthub.

On that host:

gh auth login

For an HTTPS Git remote, Git authentication must also work there. GitHub CLI can configure itself as the credential helper:

gh auth setup-git

Then select the project, press Shift+Cmd+N, choose Pull Request, and search for an open pull request. Ghosthub asks kwt to import it and selects the resulting worktree session.

Remove a worktree

Hover over a non-primary worktree in the sidebar and choose ×. After you confirm the exact worktree and host, Ghosthub:

  1. ends that worktree's verified live tmux session when necessary; and
  2. asks kwt to remove the checkout.

The Git branch is kept. If the checkout is already absent, Ghosthub skips the redundant filesystem removal but still reconciles the exact live session covered by the confirmation. If the worktree or session changes while the confirmation is open, Ghosthub stops and presents the current removal details for fresh confirmation instead of continuing automatically.

After removal, the owning project remains selected. Ghosthub does not select another worktree or open its tmux session on your behalf.

Rearrange worktrees

Drag worktrees within a project to set their display order. The insertion line shows the destination. This changes Ghosthub's navigation only; it does not rename or reorder anything in Git, kwt, or tmux.