ghostty-pane-splitter 0.2.1

CLI tool to split panes on Ghostty Terminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# ghostty-pane-splitter

[![CI](https://github.com/rikeda71/ghostty-pane-splitter/actions/workflows/ci.yml/badge.svg)](https://github.com/rikeda71/ghostty-pane-splitter/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/ghostty-pane-splitter.svg)](https://crates.io/crates/ghostty-pane-splitter)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**[日本語版 README はこちら](README.ja.md)**

CLI tool to split panes on Ghostty Terminal.

Automates Ghostty's pane splitting by simulating keyboard inputs via [enigo](https://github.com/enigo-rs/enigo), enabling cross-platform support (macOS / Linux).

![demo](images/demo-number.gif)

## Use with AI Coding Agents

Ghostty is becoming the terminal of choice for CLI-based AI coding agents like [Claude Code](https://code.claude.com/) and [Codex CLI](https://github.com/openai/codex). Use `ghostty-pane-splitter` to instantly set up multi-pane layouts — run your AI agent in one pane, your editor in another, and a dev server in a third, all with a single command.

```bash
# 3-pane layout: Left: AI agent, Right-top: editor, Right-bottom: terminal
ghostty-pane-splitter 1,2

# 4-pane layout for running multiple agents in parallel with git worktrees
ghostty-pane-splitter 4
```

Running multiple AI agents in parallel with [git worktrees](https://git-scm.com/docs/git-worktree) is a popular productivity pattern. `ghostty-pane-splitter` lets you set up multi-agent layouts instantly — no tmux required.

## Usage

```
ghostty-pane-splitter <LAYOUT>
```

`<LAYOUT>` accepts a pane count, a grid spec (`COLSxROWS`), or a custom column layout (comma-separated row counts per column).

```bash
# Split into 4 panes (2x2 grid)
ghostty-pane-splitter 4

# Split into 6 panes (3x2 grid)
ghostty-pane-splitter 6

# Split into 2 cols x 3 rows
ghostty-pane-splitter 2x3

# Custom layout: left 1 pane, right 3 panes
ghostty-pane-splitter 1,3

# Custom layout: 3 columns with 2, 1, 3 rows
ghostty-pane-splitter 2,1,3

# Show version
ghostty-pane-splitter --version

# Show help
ghostty-pane-splitter --help
```

### Layout examples

| Input   | Result | Description |
|---------|--------|-------------|
| `2`     | 2x1    | 2 columns |
| `4`     | 2x2    | 2x2 grid |
| `6`     | 3x2    | 3 cols x 2 rows |
| `9`     | 3x3    | 3x3 grid |
| `2x3`   | 2x3    | Explicit grid spec |
| `1,3`   | 1+3    | Left: 1 pane, Right: 3 panes |
| `2,1,3` | 2+1+3  | 3 columns with 2, 1, 3 rows |

## Installation

### Homebrew (macOS)

```bash
brew install rikeda71/tap/ghostty-pane-splitter
```

### curl (GitHub Releases)

```bash
# macOS (Apple Silicon)
curl -fsSL https://github.com/rikeda71/ghostty-pane-splitter/releases/latest/download/ghostty-pane-splitter-aarch64-apple-darwin.tar.gz | tar xz
sudo mv ghostty-pane-splitter /usr/local/bin/

# macOS (Intel)
curl -fsSL https://github.com/rikeda71/ghostty-pane-splitter/releases/latest/download/ghostty-pane-splitter-x86_64-apple-darwin.tar.gz | tar xz
sudo mv ghostty-pane-splitter /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/rikeda71/ghostty-pane-splitter/releases/latest/download/ghostty-pane-splitter-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv ghostty-pane-splitter /usr/local/bin/
```

### Cargo

```bash
cargo install ghostty-pane-splitter
```

### From source

```bash
git clone https://github.com/rikeda71/ghostty-pane-splitter.git
cd ghostty-pane-splitter
cargo install --path .
```

> **Note**: Linux requires `libxdo-dev` (`sudo apt install libxdo-dev`)

## Configuration

This tool reads keybindings directly from your Ghostty config file. Add the following keybindings to your Ghostty config:

```
keybind = super+d=new_split:right
keybind = super+shift+d=new_split:down
keybind = super+ctrl+right_bracket=goto_split:next
keybind = super+ctrl+left_bracket=goto_split:previous
keybind = super+ctrl+shift+equal=equalize_splits
```

Ghostty config file locations:
- **macOS**: `~/Library/Application Support/com.mitchellh.ghostty/config`
- **Linux**: `~/.config/ghostty/config`

The tool will show an error if the config file is not found or required keybindings are missing.

> **Important**: After adding or changing keybindings, you must restart Ghostty for the changes to take effect. The tool will work correctly once Ghostty is relaunched with the updated config.

> **Tip** (Ghostty 1.3.0+): By default, new splits inherit the working directory of the current pane. You can control this behavior with the `split-inherit-working-directory` config option. Set it to `false` if you prefer new splits to always start in the home directory.
> ```
> split-inherit-working-directory = false
> ```

## Demo

| Type | Command | Demo |
|------|---------|------|
| Number | `ghostty-pane-splitter 9` | ![number](images/demo-number.gif) |
| Grid | `ghostty-pane-splitter 2x2` | ![grid](images/demo-grid.gif) |
| Custom | `ghostty-pane-splitter 1,4` | ![custom](images/demo-custom.gif) |

## Requirements

- [Ghostty](https://ghostty.org/) terminal
- Linux: `libxdo-dev` (`sudo apt install libxdo-dev`)

## License

[MIT](LICENSE)