https://github.com/yazilim-vip/terminal-setup
Minimal macOS terminal setup — Ghostty + tmux (Catppuccin Mocha), symlink-based with a one-line installer
https://github.com/yazilim-vip/terminal-setup
catppuccin dotfiles ghostty macos terminal tmux
Last synced: 20 days ago
JSON representation
Minimal macOS terminal setup — Ghostty + tmux (Catppuccin Mocha), symlink-based with a one-line installer
- Host: GitHub
- URL: https://github.com/yazilim-vip/terminal-setup
- Owner: yazilim-vip
- License: mit
- Created: 2026-06-09T21:05:47.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-10T11:12:25.000Z (30 days ago)
- Last Synced: 2026-06-10T12:17:16.968Z (30 days ago)
- Topics: catppuccin, dotfiles, ghostty, macos, terminal, tmux
- Language: Shell
- Homepage:
- Size: 24.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# terminal-setup
[](LICENSE)
Minimal macOS terminal setup: [Ghostty](https://ghostty.org) + [tmux](https://github.com/tmux/tmux), Catppuccin Mocha theme. Symlink-based, so you update it with a plain `git pull`.
## Features
- Prefix remapped to `Ctrl+Space`
- Vim-style pane navigation (no prefix needed)
- Option-key shortcuts for window/session management
- **Catppuccin Mocha** theme — Ghostty *and* the tmux status bar
- **Session persistence** (resurrect + continuum) and an **fzf session picker** (sessionx)
- Truecolor, mouse support, clickable URLs
## Requirements
- macOS (the Ghostty config uses `macos-option-as-alt`)
- [Ghostty](https://ghostty.org) and `tmux` installed (e.g. `brew install --cask ghostty` + `brew install tmux`)
- [`fzf`](https://github.com/junegunn/fzf) — for the sessionx session picker (`brew install fzf`)
- tmux plugins install on first launch via `prefix I` (TPM is set up automatically by the installer)
## Installation
One command — clones into `~/.local/share/terminal-setup`, symlinks the configs, and adds a `terminal-setup` command to your shell:
```bash
sh -c "$(curl -fsSL https://raw.githubusercontent.com/yazilim-vip/terminal-setup/main/install.sh)"
```
Prefer to clone manually?
```bash
git clone https://github.com/yazilim-vip/terminal-setup.git ~/.local/share/terminal-setup
~/.local/share/terminal-setup/install.sh
```
What the installer does:
- Clones the repo to `~/.local/share/terminal-setup` (XDG `$XDG_DATA_HOME`; override with `TERMINAL_SETUP_DIR=/path`).
- Symlinks the configs (it does not copy them):
```
ghostty/config → ~/.config/ghostty/config
tmux/.tmux.conf → ~/.tmux.conf
```
- Adds a `terminal-setup` shell command — plus a `k9s` alias that pins k9s to the `xterm-ghostty` terminfo so its menu hints don't gray out under tmux — to `~/.zshrc` (and `~/.bashrc` if present), in a clearly marked block.
Afterward, reload Ghostty (`Cmd+Shift+,`) and tmux (`prefix R`), and restart your shell (or `source ~/.zshrc`) to pick up the `terminal-setup` command.
## Updating
```bash
terminal-setup update
```
Pulls the latest; because the configs are symlinked, your live setup updates in place — no re-install. Reload tmux with `prefix R` afterward.
> Changes to the **shell block** (the `terminal-setup` command and the `k9s` alias) are written into your rc file, not symlinked — re-run the installer to refresh them on an existing install.
> Don't have the command yet? `cd ~/.local/share/terminal-setup && git pull` does the same thing, or just re-run the install one-liner.
## Plugins
Managed by [TPM](https://github.com/tmux-plugins/tpm) (declared in `tmux/.tmux.conf`). Install/update with `prefix I` / `prefix U`.
| Plugin | Purpose |
|--------|---------|
| tpm | Plugin manager |
| tmux-sensible | Sensible defaults |
| tmux-resurrect | Save/restore sessions (`prefix C-s` / `prefix C-r`) |
| tmux-continuum | Auto-save + auto-restore sessions |
| tmux-yank | Clipboard integration |
| catppuccin/tmux | Catppuccin Mocha status bar |
| tmux-sessionx | fzf session picker (`prefix o`) — needs `fzf` |
| vim-tmux-navigator | Seamless vim/tmux pane navigation |
## Keybindings
### Ghostty
| Key | Action |
|-----|--------|
| `Cmd+Shift+,` | Reload config |
| `Cmd+click` | Open URL |
### tmux — Panes, no prefix (Option)
| Key | Action |
|-----|--------|
| `Option+h` / `Option+j` | Focus pane left |
| `Option+k` | Focus pane down |
| `Option+i` | Focus pane up |
| `Option+l` | Focus pane right |
| `Option+d` | Split right |
| `Option+e` / `Option+D` | Split down |
| `Option+Enter` | Toggle zoom |
| `Option+x` | Kill pane (confirm) |
| `Option+m` | Move pane to window |
### tmux — Pane Management (prefix: `Ctrl+Space`)
| Key | Action |
|-----|--------|
| `v` | Split vertical |
| `s` | Split horizontal |
| `z` | Toggle zoom |
| `x` | Kill pane |
| `j/k/i/l` | Swap pane in direction |
| `Ctrl+j/l` | Join pane vertical (left/right) |
| `Ctrl+i/k` | Join pane horizontal (up/down) |
| `m` | Move pane to window |
| `M` | Merge window here |
### tmux — Windows
| Key | Action |
|-----|--------|
| `prefix c` | New window |
| `Option+0` / `Option+t` | New window (no prefix) |
| `prefix 1-5` / `Option+1-9` | Switch to window (`Option+9` = last) |
| `Option+[` / `Option+]` | Previous / next window (no prefix) |
| `prefix p` | Previous window |
| `prefix <` / `>` | Swap window left / right |
| `Option+,` / `Option+.` | Swap window left / right (no prefix) |
| `Option+r` | Rename window (no prefix) |
### tmux — Sessions
| Key | Action |
|-----|--------|
| `prefix n` | New session |
| `prefix o` / `Option+o` | Session picker — sessionx (fzf) |
| `Option+n` / `Option+R` | Rename session (no prefix) |
| `prefix C-s` | Save sessions (resurrect) |
| `prefix C-r` | Restore sessions (resurrect) |
### tmux — Other
| Key | Action |
|-----|--------|
| `Option+c` / `Option+K` | Clear screen + scrollback |
| `prefix R` | Reload tmux config |
| `prefix /` | Search (copy mode) |
| `prefix I` | Install plugins (TPM) |
| `prefix U` | Update plugins (TPM) |
| `Ctrl+h/j/k/l` | Navigate vim/tmux panes (vim-tmux-navigator) |
## Structure
```
ghostty/config → ~/.config/ghostty/config
tmux/.tmux.conf → ~/.tmux.conf
install.sh → clones/links, bootstraps TPM, installs the `terminal-setup` command
```
## License
[MIT](LICENSE) © Yazilim VIP