native-shortcuts-herd 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +153 -109
  2. package/dist/cli.js +1 -1
  3. package/dist/installer.js +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -2,36 +2,47 @@
2
2
 
3
3
  make ghostty navigation feel like a real macos app.
4
4
 
5
- ghostty is fast, powerful, and beautifully native. but if your hands come from chrome, safari, arc, iterm, warp, or cmux-style workflows, the default terminal navigation can still feel a little off. tabs, spaces, split contexts, and terminal multiplexers all speak different shortcut languages.
5
+ ghostty is fast, native, and powerful. herdr gives you workspaces, tabs, panes, and direct indexed jumps. the missing piece is the hand feel: `cmd+t`, `cmd+w`, `cmd+1..9`, `ctrl+tab`, and chrome-style tab cycling should work without thinking about terminal escape sequences.
6
6
 
7
- `native-shortcuts-herd` fixes that by wiring ghostty and herdr together with familiar macos/chrome-style shortcuts, without rewriting your existing config.
7
+ `native-shortcuts-herd` wires ghostty and herdr together with a safe, reusable installer so terminal navigation feels familiar for macos users coming from chrome, safari, arc, iterm, warp, or cmux-style workflows.
8
8
 
9
- <video src="./docs/assets/native-shortcuts-herd-demo.mp4" controls width="100%"></video>
9
+ <video src="https://raw.githubusercontent.com/yigitkonur/native-shortcuts-herd/main/docs/assets/native-shortcuts-herd-demo.mp4" controls width="100%"></video>
10
10
 
11
- > demo file: `docs/assets/native-shortcuts-herd-demo.mp4`
11
+ > demo: `docs/assets/native-shortcuts-herd-demo.mp4`
12
12
 
13
- ## install
13
+ ## quick start
14
+
15
+ guided setup:
16
+
17
+ ```sh
18
+ npx native-shortcuts-herd@latest install
19
+ ```
20
+
21
+ fully scripted setup:
14
22
 
15
23
  ```sh
16
- npx native-shortcuts-herd install
24
+ npx native-shortcuts-herd@latest install --yes --install-herdr --glass-theme
17
25
  ```
18
26
 
19
- the installer is reusable. run it again any time to switch profiles, change what `cmd+1..9` targets, update mappings, repair config drift, or revert cleanly.
27
+ fully scripted uninstall:
20
28
 
21
- if herdr is missing or too old, the wizard offers to install/update it into `~/.local/bin/herdr` before writing the keymap. non-interactive runs can use `--yes` for the same behavior.
29
+ ```sh
30
+ npx native-shortcuts-herd@latest uninstall --yes
31
+ ```
22
32
 
23
- fully scripted install and uninstall are supported too:
33
+ same uninstall through the installer entrypoint:
24
34
 
25
35
  ```sh
26
- npx native-shortcuts-herd install --yes --install-herdr --glass-theme
27
- npx native-shortcuts-herd uninstall --yes
36
+ npx native-shortcuts-herd@latest install --uninstall --yes
28
37
  ```
29
38
 
39
+ the installer is intentionally reusable. run it again to change profiles, retarget `cmd+1..9`, repair config drift, update the glass preset, or remove every managed change.
40
+
30
41
  ## why this exists
31
42
 
32
- terminal power users already know how to build custom keymaps. the problem is that every terminal, multiplexer, and tui app has its own idea of what "tab", "space", and "pane" means.
43
+ terminal power users can always hand-roll keymaps. the problem is that terminals, multiplexers, and tui apps disagree on what a tab, space, workspace, split, pane, or session should mean.
33
44
 
34
- macos users expect this:
45
+ macos users expect this kind of muscle memory:
35
46
 
36
47
  | habit | expected feel |
37
48
  |---|---|
@@ -42,177 +53,196 @@ macos users expect this:
42
53
  | `ctrl+tab` | cycle through the main contexts |
43
54
  | `ctrl+option+tab` | cycle through the secondary contexts |
44
55
 
45
- ghostty already has excellent keybinding support. herdr already has workspaces, tabs, panes, direct keybindings, and indexed jumps. this package connects the two in a safe, repeatable way.
56
+ ghostty already has excellent keybinding support. herdr already has the right model. this package connects them without taking over your whole config.
46
57
 
47
- ## what it does
58
+ ## what gets changed
48
59
 
49
60
  | system | change |
50
61
  |---|---|
51
- | ghostty | adds one managed `config-file` include to your existing config |
52
- | ghostty sidecar | writes only owned keybind routes into `~/.config/native-shortcuts-herd/ghostty.conf` |
62
+ | ghostty | adds one managed `config-file` include to each detected ghostty/cmux config |
63
+ | ghostty sidecar | writes owned key routes to `~/.config/native-shortcuts-herd/ghostty.conf` |
53
64
  | optional glass preset | adds a purple catppuccin + macos liquid-glass visual layer when you opt in |
54
65
  | herdr | updates `[keys]`, `[keys.indexed]`, and `ui.prompt_new_tab_name` |
55
- | herdr installer | prompts to install/update herdr when it is missing or below `0.5.10` |
56
- | state | stores install state in `~/.config/native-shortcuts-herd/state.json` |
66
+ | herdr installer | can install or update herdr into `~/.local/bin/herdr` when missing or below `0.5.10` |
67
+ | state | stores previous herdr values in `~/.config/native-shortcuts-herd/state.json` |
57
68
  | backups | creates timestamped backups before writing |
58
- | uninstall | removes the ghostty sidecar/include, restores tracked herdr values, and clears managed state |
69
+ | uninstall | removes the ghostty include/sidecar, restores tracked herdr values, and clears managed state |
59
70
 
60
71
  ## keybindings
61
72
 
62
- the installer lets you choose what the ambiguous families target. nothing is hardcoded forever.
73
+ the default profile is `chrome-spaces`: command keys target herdr workspaces/spaces, while `ctrl+option+tab` cycles herdr tabs. every ambiguous family can be changed.
63
74
 
64
- | shortcut | default profile behavior | configurable |
75
+ | shortcut | default behavior | configurable |
65
76
  |---|---|---|
66
77
  | `cmd+t` | new herdr tab | yes |
67
78
  | `cmd+n` | new herdr workspace / space | yes |
68
79
  | `cmd+w` | close active herdr tab | yes |
69
80
  | `cmd+k` | rename active herdr workspace | yes |
70
81
  | `cmd+l` | rename active herdr tab | yes |
71
- | `cmd+1..9` | wizard-selected: spaces, tabs, or off | yes |
72
- | `ctrl+tab` | wizard-selected: spaces, tabs, or off | yes |
73
- | `ctrl+shift+tab` | previous item for `ctrl+tab` target | yes |
74
- | `ctrl+option+tab` | wizard-selected: tabs, spaces, or off | yes |
75
- | `ctrl+option+shift+tab` | previous item for `ctrl+option+tab` target | yes |
82
+ | `cmd+1..9` | jump to herdr workspace 1-9 | yes: spaces, tabs, off |
83
+ | `ctrl+tab` | next herdr workspace | yes: spaces, tabs, off |
84
+ | `ctrl+shift+tab` | previous herdr workspace | yes: spaces, tabs, off |
85
+ | `ctrl+option+tab` | next herdr tab | yes: tabs, spaces, off |
86
+ | `ctrl+option+shift+tab` | previous herdr tab | yes: tabs, spaces, off |
76
87
 
77
88
  ## ghostty behavior mappings
78
89
 
79
- ghostty receives macos keys first. this tool routes them into terminal sequences that herdr can understand.
90
+ ghostty receives macos shortcuts first. this package routes those keys into sequences herdr understands.
80
91
 
81
- | ghostty trigger | managed action | herdr receives |
92
+ | ghostty trigger | managed ghostty action | herdr receives |
82
93
  |---|---|---|
83
- | `cmd+key_t` | `text:\x02t` | prefix + `t` |
84
- | `cmd+key_n` | `text:\x02n` | prefix + `n` |
85
- | `cmd+key_w` | `text:\x02W` | prefix + `shift+w` |
86
- | `cmd+key_k` | `text:\x02N` | prefix + `shift+n` |
87
- | `cmd+key_l` | `text:\x02T` | prefix + `shift+t` |
94
+ | `cmd+KeyT` | `text:\x02t` | prefix + `t` |
95
+ | `cmd+KeyN` | `text:\x02n` | prefix + `n` |
96
+ | `cmd+KeyW` | `text:\x02W` | prefix + `shift+w` |
97
+ | `cmd+KeyK` | `text:\x02N` | prefix + `shift+n` |
98
+ | `cmd+KeyL` | `text:\x02T` | prefix + `shift+t` |
88
99
  | `ctrl+tab` | `text:\x1b[9;5u` | enhanced `ctrl+tab` |
89
100
  | `ctrl+shift+tab` | `text:\x1b[9;6u` | enhanced `ctrl+shift+tab` |
90
101
  | `ctrl+option+tab` | `text:\x1b[9;7u` | enhanced `ctrl+alt+tab` |
102
+ | `ctrl+option+shift+tab` | `text:\x1b[9;8u` | enhanced `ctrl+alt+shift+tab` |
91
103
  | `cmd+1..9` | generated per profile | indexed herdr jump |
92
104
 
93
- for macos menu conflicts like `cmd+w`, ghostty gets both a physical-key route and a normal `cmd+w=unbind`, so the terminal app does not close the window before herdr sees the intended action.
94
-
95
- ## purple glass preset
96
-
97
- the wizard can optionally add a visual preset inspired by a polished macos ghostty setup: catppuccin mocha colors, display-p3/native blending, transparent titlebar, `macos-glass-regular`, subtle split dimming, and retina-friendly jetbrains mono thickening.
98
-
99
- | setting family | managed values |
100
- |---|---|
101
- | color | `theme = Catppuccin Mocha`, purple mocha background, matching cursor and selection |
102
- | glass | `background-opacity = 0.85`, `background-blur = macos-glass-regular`, transparent titlebar |
103
- | rendering | `window-colorspace = display-p3`, `alpha-blending = native`, `window-vsync = true` |
104
- | typography | `JetBrains Mono`, 16pt, ligatures, light macos thickening |
105
- | layout | 16x12 padding, balanced padding, dimmed unfocused splits |
106
-
107
- it is opt-in. use the wizard prompt, `--glass-theme`, or `--no-glass-theme`.
105
+ for macos menu conflicts such as `cmd+w`, ghostty gets a physical-key route plus a normal `cmd+w=unbind`. that lets herdr receive the intended action instead of ghostty closing the whole window.
108
106
 
109
107
  ## herdr integration
110
108
 
111
- herdr v0.5.10 added the pieces that make this clean: indexed keybind families and instant generated tab names.
109
+ herdr `0.5.10+` added the clean pieces this project uses: indexed keybind families and instant generated tab names.
112
110
 
113
111
  | herdr config | purpose |
114
112
  |---|---|
113
+ | `[keys].prefix` | keeps the herdr prefix at `ctrl+b` |
115
114
  | `[keys].new_workspace` | target for `cmd+n` |
115
+ | `[keys].rename_workspace` | target for `cmd+k` |
116
116
  | `[keys].new_tab` | target for `cmd+t` |
117
+ | `[keys].rename_tab` | target for `cmd+l` |
117
118
  | `[keys].close_tab` | target for `cmd+w` |
118
- | `[keys].previous_workspace` / `next_workspace` | direct cycle shortcuts |
119
- | `[keys].previous_tab` / `next_tab` | direct tab cycle shortcuts |
119
+ | `[keys].previous_workspace` / `next_workspace` | direct workspace cycling |
120
+ | `[keys].previous_tab` / `next_tab` | direct tab cycling |
120
121
  | `[keys.indexed].workspaces` | direct workspace jumps 1-9 |
121
122
  | `[keys.indexed].tabs` | direct tab jumps 1-9 |
122
- | `[ui].prompt_new_tab_name` | set to `false` for instant tab creation |
123
+ | `[ui].prompt_new_tab_name` | defaults to `false` for instant tab creation |
123
124
 
124
- ## install options
125
+ ## install behavior
125
126
 
126
127
  | command | use it when |
127
128
  |---|---|
128
- | `npx native-shortcuts-herd install` | guided setup, best first run |
129
- | `npx native-shortcuts-herd install --yes --install-herdr --glass-theme` | full non-interactive install |
130
- | `npx native-shortcuts-herd install --uninstall --yes` | uninstall through the same install entrypoint |
131
- | `npx native-shortcuts-herd apply --profile chrome-spaces --yes` | repeatable non-interactive setup |
132
- | `npx native-shortcuts-herd apply --no-install-herdr --yes` | apply config without downloading herdr |
133
- | `npx native-shortcuts-herd apply --glass-theme --yes` | apply shortcuts plus the purple glass preset |
134
- | `npx native-shortcuts-herd diff` | inspect changes before writing |
135
- | `npx native-shortcuts-herd doctor` | see detected ghostty/herdr state |
136
- | `npx native-shortcuts-herd uninstall --yes` | remove managed changes without prompts |
137
- | `npx native-shortcuts-herd revert` | alias-style legacy removal command |
138
- | `npx native-shortcuts-herd profiles` | list built-in profiles |
139
- | `npx native-shortcuts-herd generate-installer` | print a tiny shell installer |
129
+ | `npx native-shortcuts-herd@latest install` | guided first run |
130
+ | `npx native-shortcuts-herd@latest install --yes` | non-interactive install with safe defaults |
131
+ | `npx native-shortcuts-herd@latest install --yes --install-herdr` | non-interactive install and install/update herdr if needed |
132
+ | `npx native-shortcuts-herd@latest install --yes --no-install-herdr` | non-interactive install without downloading herdr |
133
+ | `npx native-shortcuts-herd@latest install --yes --glass-theme` | install shortcuts plus the glass preset |
134
+ | `npx native-shortcuts-herd@latest install --uninstall --yes` | uninstall through the install command |
135
+ | `npx native-shortcuts-herd@latest uninstall --yes` | remove managed changes without prompts |
136
+ | `npx native-shortcuts-herd@latest uninstall --dry-run --json` | machine-readable uninstall preview |
137
+ | `npx native-shortcuts-herd@latest apply --profile chrome-tabs --yes` | repeatable profile application |
138
+ | `npx native-shortcuts-herd@latest diff --profile chrome-spaces` | inspect planned writes |
139
+ | `npx native-shortcuts-herd@latest doctor --json` | inspect ghostty, herdr, and state |
140
+ | `npx native-shortcuts-herd@latest generate-installer` | print a tiny shell installer |
141
+
142
+ ## herdr install options
143
+
144
+ | flag | behavior |
145
+ |---|---|
146
+ | no flag in guided mode | prompt to install/update herdr when needed |
147
+ | `--yes` | allow herdr install/update without prompts |
148
+ | `--install-herdr` | explicitly install/update herdr when needed |
149
+ | `--no-install-herdr` | never download herdr |
150
+ | `--skip-herdr-install` | legacy spelling for not offering automatic install/update |
151
+ | `--skip-herdr` | do not write herdr config at all |
140
152
 
141
- ## supported workflows
153
+ automatic herdr install downloads the latest matching release asset from `ogulcancelik/herdr` into `~/.local/bin/herdr`. if the release asset exposes a sha256 digest, the binary is verified before it is written.
142
154
 
143
- | workflow | status | notes |
144
- |---|---|---|
145
- | ghostty on macos | supported | primary target |
146
- | cmux ghostty config | supported | detected when the config file exists |
147
- | herdr 0.5.10+ | supported | required for indexed jumps |
148
- | re-running installer | supported | updates managed files idempotently |
149
- | uninstall/revert | supported | uses saved state, best-effort cleanup, and clears managed state |
150
- | scripted automation | supported | use `--yes`, `--install-herdr`, `--no-install-herdr`, `--uninstall`, and `--json` |
151
- | custom keymaps | supported | use profile choices and `--ghostty-key` / `--herdr-key` |
152
- | linux ghostty | best effort | key routing may vary by desktop environment |
153
- | windows | not supported | ghostty/herdr target here is macos-first |
155
+ ## profiles
154
156
 
155
- ## examples
157
+ | profile | `cmd+1..9` | `ctrl+tab` | `ctrl+option+tab` | best for |
158
+ |---|---|---|---|---|
159
+ | `chrome-spaces` | workspaces | workspaces | tabs | cmux-like spaces with browser-ish secondary tab cycling |
160
+ | `chrome-tabs` | tabs | tabs | workspaces | literal chrome tab muscle memory |
161
+ | `minimal` | off | workspaces | tabs | keep core shortcuts, skip indexed jumps |
156
162
 
157
- chrome-ish spaces:
163
+ ## customization
158
164
 
159
- ```sh
160
- npx native-shortcuts-herd apply --profile chrome-spaces --yes
161
- ```
162
-
163
- scripted install, including herdr and glass:
165
+ change the target families:
164
166
 
165
167
  ```sh
166
- npx native-shortcuts-herd install --yes --install-herdr --glass-theme
168
+ npx native-shortcuts-herd@latest apply \
169
+ --cmd-numbers tabs \
170
+ --ctrl-tab tabs \
171
+ --ctrl-opt-tab workspaces \
172
+ --yes
167
173
  ```
168
174
 
169
- literal chrome tabs:
175
+ turn off indexed jumps:
170
176
 
171
177
  ```sh
172
- npx native-shortcuts-herd apply --profile chrome-tabs --yes
178
+ npx native-shortcuts-herd@latest apply \
179
+ --cmd-numbers off \
180
+ --ctrl-tab workspaces \
181
+ --ctrl-opt-tab tabs \
182
+ --yes
173
183
  ```
174
184
 
175
- turn off indexed `cmd+1..9` but keep cycling:
185
+ add a ghostty route:
176
186
 
177
187
  ```sh
178
- npx native-shortcuts-herd apply --cmd-numbers off --ctrl-tab workspaces --ctrl-opt-tab tabs --yes
188
+ npx native-shortcuts-herd@latest apply \
189
+ --ghostty-key 'cmd+slash=text:\x02?' \
190
+ --yes
179
191
  ```
180
192
 
181
- add a custom herdr action:
193
+ add a herdr action:
182
194
 
183
195
  ```sh
184
- npx native-shortcuts-herd apply --herdr-key reload_config=shift+r --yes
196
+ npx native-shortcuts-herd@latest apply \
197
+ --herdr-key reload_config=shift+r \
198
+ --yes
185
199
  ```
186
200
 
187
- patch a specific ghostty config:
201
+ patch one config explicitly:
188
202
 
189
203
  ```sh
190
- npx native-shortcuts-herd apply --ghostty-config ~/.config/ghostty/config --yes
204
+ npx native-shortcuts-herd@latest apply \
205
+ --ghostty-config ~/.config/ghostty/config \
206
+ --yes
191
207
  ```
192
208
 
193
- apply the purple glass look:
209
+ ## purple glass preset
194
210
 
195
- ```sh
196
- npx native-shortcuts-herd apply --glass-theme --yes
197
- ```
211
+ the glass preset is opt-in. it gives ghostty a richer macos look without making it the default behavior.
212
+
213
+ | setting family | managed values |
214
+ |---|---|
215
+ | color | `theme = Catppuccin Mocha`, purple mocha background, matching cursor and selection |
216
+ | glass | `background-opacity = 0.85`, `background-blur = macos-glass-regular`, transparent titlebar |
217
+ | rendering | `window-colorspace = display-p3`, `alpha-blending = native`, `window-vsync = true` |
218
+ | typography | `JetBrains Mono`, 16pt, ligatures, light macos thickening |
219
+ | layout | 16x12 padding, balanced padding, dimmed unfocused splits |
198
220
 
199
- preview everything:
221
+ apply it:
200
222
 
201
223
  ```sh
202
- npx native-shortcuts-herd diff --profile chrome-spaces
224
+ npx native-shortcuts-herd@latest apply --glass-theme --yes
203
225
  ```
204
226
 
205
- revert:
227
+ remove only the package-managed include and state:
206
228
 
207
229
  ```sh
208
- npx native-shortcuts-herd uninstall --yes
230
+ npx native-shortcuts-herd@latest uninstall --yes
209
231
  ```
210
232
 
211
- uninstall through the installer entrypoint:
233
+ ## supported workflows
212
234
 
213
- ```sh
214
- npx native-shortcuts-herd install --uninstall --yes
215
- ```
235
+ | workflow | status | notes |
236
+ |---|---|---|
237
+ | ghostty on macos | supported | primary target |
238
+ | cmux ghostty config | supported | detected when the config file exists |
239
+ | herdr `0.5.10+` | supported | required for indexed jumps |
240
+ | re-running installer | supported | updates managed files idempotently |
241
+ | uninstall/reinstall | supported | uses saved state, best-effort cleanup, and clears managed state |
242
+ | scripted automation | supported | use `--yes`, `--install-herdr`, `--no-install-herdr`, `--uninstall`, and `--json` |
243
+ | custom keymaps | supported | use profile choices and `--ghostty-key` / `--herdr-key` |
244
+ | linux ghostty | best effort | key routing and global shortcuts vary by desktop environment |
245
+ | windows | not supported | this project is macos-first |
216
246
 
217
247
  ## safety model
218
248
 
@@ -220,14 +250,28 @@ this package is intentionally boring about file writes.
220
250
 
221
251
  | safety feature | behavior |
222
252
  |---|---|
223
- | sidecar include | ghostty gets one include; owned keybinds live elsewhere |
253
+ | sidecar include | ghostty gets one include; owned lines live in a separate file |
224
254
  | backups | files are copied before writes |
225
- | state file | previous herdr values are tracked for uninstall, then removed |
226
- | dry run | `diff` and `--dry-run` show planned changes first |
255
+ | state file | previous herdr values are tracked for uninstall |
256
+ | dry run | `diff` and `--dry-run` preview planned changes |
257
+ | json output | `--json` writes machine-readable output to stdout |
227
258
  | validation | ghostty config validation runs when the binary is available |
228
259
  | reload | herdr reload is attempted when a server is running |
229
260
  | no secret handling | npm/github tokens are never written into config |
230
261
 
262
+ uninstall only removes package-owned config. it does not delete manually written ghostty keybinds, custom shaders, or theme settings that already live in your main config files.
263
+
264
+ ## troubleshooting
265
+
266
+ | symptom | check |
267
+ |---|---|
268
+ | ghostty still uses the old keymap | run `cmd+shift+,` in ghostty or restart ghostty |
269
+ | herdr shortcuts do not react | run `herdr --version` and make sure it is `0.5.10+` |
270
+ | `cmd+w` closes the window | run `native-shortcuts-herd doctor --json` and confirm the ghostty sidecar exists |
271
+ | install should not download herdr | use `--no-install-herdr` |
272
+ | automation needs stable output | add `--json` |
273
+ | you want to inspect first | run `diff` or add `--dry-run` |
274
+
231
275
  ## development
232
276
 
233
277
  ```sh
package/dist/cli.js CHANGED
@@ -10,7 +10,7 @@ const program = new Command();
10
10
  program
11
11
  .name("native-shortcuts-herd")
12
12
  .description("make ghostty + herdr navigation feel native to macos")
13
- .version("0.1.3");
13
+ .version("0.1.4");
14
14
  addSharedOptions(program.command("install").option("--uninstall", "remove managed changes instead of installing"))
15
15
  .description("run the guided installer")
16
16
  .action(async (options) => {
package/dist/installer.js CHANGED
@@ -3,7 +3,7 @@ import { generateConfig } from "./profiles.js";
3
3
  import { applyGhosttyPatch, applyGhosttyRevert, discoverGhosttyConfigs, ghosttySidecarPath, planGhosttyPatch, planGhosttyRevert, reloadGhosttyIfRunning, validateGhosttyConfigs } from "./ghostty.js";
4
4
  import { applyHerdrPatch, applyHerdrRevert, detectHerdr, discoverHerdrConfig, installOrUpdateHerdr, minimumHerdrVersion, planHerdrPatch, planHerdrRevert, reloadHerdr } from "./herdr.js";
5
5
  import { deleteState, readState, writeState } from "./state.js";
6
- const packageVersion = "0.1.3";
6
+ const packageVersion = "0.1.4";
7
7
  export async function applyConfig(request) {
8
8
  const generated = generateConfig(request.choices);
9
9
  const warnings = [];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "native-shortcuts-herd",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "make ghostty + herdr navigation feel native to macos and chrome-style tab workflows",
5
5
  "type": "module",
6
6
  "bin": {