Ghosthub

https://ghosthub.ai/docs
Admin
Ghosthub is a native macOS terminal application that connects to and manages local and remote tmux,...
Tokens:13,604
Snippets:159
Trust Score:5.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Zellij

Source: https://ghosthub.ai/docs/getting-started

Install Zellij locally to enable support for Zellij sessions.

```sh
brew install zellij
```

--------------------------------

### Install tmux

Source: https://ghosthub.ai/docs/getting-started

Install tmux locally if it is not already present on your system.

```sh
brew install tmux
```

--------------------------------

### Install Ghosthub via Homebrew

Source: https://ghosthub.ai/docs/getting-started

Install the signed, notarized Ghosthub application using the Kenn Homebrew tap.

```sh
brew install kenn-io/tap/ghosthub
```

--------------------------------

### Check Zellij installation and list sessions

Source: https://ghosthub.ai/docs/troubleshooting

Run these commands on a local Mac or remote macOS/Linux host to verify Zellij is installed and list active sessions. Ghosthub only lists active Zellij sessions; if the command is missing, the host remains usable but Zellij Sessions are omitted.

```sh
command -v zellij
zellij list-sessions --no-formatting
```

--------------------------------

### Verify tmux installation and sessions

Source: https://ghosthub.ai/docs/troubleshooting

Confirm that tmux is installed on the remote host and list active sessions.

```sh
tmux -V
tmux list-sessions
```

--------------------------------

### Verify tmux installation

Source: https://ghosthub.ai/docs/getting-started

Check the installed version of tmux to ensure compatibility.

```sh
tmux -V
```

--------------------------------

### Verify Herdr installation and session status

Source: https://ghosthub.ai/docs/troubleshooting

Check if the herdr command is available and list sessions in JSON format to debug missing Herdr sessions in Ghosthub.

```sh
command -v herdr
herdr session list --json
```

--------------------------------

### Configure keyboard shortcuts in config.toml

Source: https://ghosthub.ai/docs/keyboard-shortcuts

Example TOML configuration for overriding keyboard shortcuts. Set an action to "none" to leave it unbound. Names are case-insensitive and normalized when Settings writes them. Supported modifiers are cmd, ctrl, opt, and shift; supported keys include letters, digits, punctuation, arrows, tab, return, escape, delete, and f1-f12. Validation is atomic; malformed or duplicate bindings reject the complete edit.

```toml
[keyboard.shortcuts]
next-sibling = "ctrl+tab"
previous-sibling = "ctrl+shift+tab"
select-sibling-1 = "cmd+opt+1"
split-right = "none"

```

--------------------------------

### Configure background opacity and blur in ghostty.conf

Source: https://ghosthub.ai/docs/terminal-configuration

Sets background transparency and blur for the terminal. Ghosthub reads these values from ghostty.conf at startup and on every reload. When opacity is below 1, workspace windows and chrome become translucent and blur is applied behind the window. Increased contrast forces an opaque window, and native fullscreen always stays opaque. A project terminal.conf or a file loaded with config-file can override these values.

```text
background-opacity = 0.85
background-blur = 20
```

--------------------------------

### Authenticate with GitHub CLI

Source: https://ghosthub.ai/docs/projects-worktrees

Run this command on the project host to authenticate the GitHub CLI.

```sh
gh auth login
```

--------------------------------

### Configure Git Credential Helper

Source: https://ghosthub.ai/docs/projects-worktrees

Use this command to configure the GitHub CLI as the credential helper for HTTPS Git remotes.

```sh
gh auth setup-git
```

--------------------------------

### Inspect kwt tmux server sessions

Source: https://ghosthub.ai/docs/troubleshooting

List sessions for worktrees and registered directories managed by kwt.

```sh
tmux -L kwt list-sessions
```

--------------------------------

### Register a directory with kwt workspace add

Source: https://ghosthub.ai/docs/projects-worktrees

Registers a directory that is not a Git checkout to use Ghosthub terminal flows. The path must be an absolute path.

```sh
kwt workspace add /absolute/path/to/directory
```

--------------------------------

### Set Ghostty theme to Catppuccin Macchiato

Source: https://ghosthub.ai/docs/terminal-configuration

Sets the terminal theme to a built-in Ghostty color scheme. Ghostty's built-in color schemes ship with Ghosthub, so any of their names can be used directly. Conditional light and dark themes and paths to custom theme files work the same way.

```text
theme = Catppuccin Macchiato
```

--------------------------------

### Test SSH connection

Source: https://ghosthub.ai/docs/remote-hosts

Use this command in your terminal to verify that your OpenSSH configuration can resolve and authenticate with the remote host.

```sh
ssh devbox
```

--------------------------------

### Ghosthub terminal configuration file path

Source: https://ghosthub.ai/docs/terminal-configuration

The configuration file for Ghosthub's terminal is located at ~/.config/ghosthub/ghostty.conf. It uses Ghostty's configuration format but is owned and loaded independently by Ghosthub; global Ghostty.app configuration does not affect it.

```text
~/.config/ghosthub/ghostty.conf
```

--------------------------------

### Diagnose pull-request import with gh auth status, git remote -v, and git fetch --dry-run

Source: https://ghosthub.ai/docs/troubleshooting

Run these checks on the machine that contains the project to diagnose pull-request import failures. For HTTPS GitHub remotes, `gh auth setup-git` can configure GitHub CLI as the Git credential helper.

```sh
gh auth status
git remote -v
git fetch --dry-run

```
Tokens:
Raw