@awebai/oats 0.67.1 → 0.68.1

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 (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
package/docs/tui.md CHANGED
@@ -63,7 +63,7 @@ a path that is in no deployment: the `E_NO_DEPLOYMENT` line that names
63
63
  where you are or from `--dir`, is added to this computer's list once, as the
64
64
  TUI's (`oats deployments add <path> --via tui --json`), also when you had
65
65
  removed it from the list. It is best effort: a failure opens nothing less,
66
- and is said once, in the line under the title, in the kernel's words. When
66
+ and is said once, in the line under the list of workspaces, in the kernel's words. When
67
67
  it comes while the switcher, the help, a confirmation, the palette, the
68
68
  spawn prompt, a detail or a terminal has the screen or the focus, it is said
69
69
  once a view's list has the focus again, so no screen that covers the
@@ -95,13 +95,13 @@ runs.
95
95
  ## What it shows
96
96
 
97
97
  ```
98
- acme-platform │ dev
98
+ acme-platform │ dev
99
99
  │ soul dev
100
100
  Instances 1 │ state running
101
- > ● dev │ harness claude, claude-opus-5-5 (so…
101
+ > ● Dev │ harness claude, claude-opus-5-5 (so…
102
102
  │ work worktree, agents/dev
103
- ● reviewer Needs input │ team eng
104
- ○ helper │ started 11:00
103
+ ! Reviewer │ team eng
104
+ ○ Helper │ started 11:00
105
105
  ──────────────────────────────────────│ home …oy/agents/dev/instances/dev
106
106
  Souls 2 │
107
107
  Capabilities 3 │
@@ -121,24 +121,25 @@ a rule between them over every row. There is no header and no footer. From
121
121
  80 columns the sidebar takes about half the width (36 to 60 columns, 30
122
122
  while a terminal is open); under 80 columns it has the whole width.
123
123
 
124
- - **The title** is the sidebar's first row: the workspace's name, then what
125
- the view holds of other machines. Beside a deployment of this machine the
126
- other machines are counted: `+1 machine`, `+2 machines`. A view that holds
127
- no deployment of this machine names its one machine, `on garnet`, or
128
- counts them when there are two or more, `2 machines`. While
129
- [the switcher](#the-switcher) is shown the title is `workspaces`.
130
- - **Under the title** stands what the view needs to say first, wrapped to
124
+ - **[The list of workspaces](#the-list-of-workspaces)** is the sidebar's
125
+ first rows, five at most: every workspace this run can show, one line
126
+ each with its name, the open one in reverse video. Its machines are the
127
+ workspace's own pages' to say: the headings of its list of instances and
128
+ the detail's `machine` line. While [the switcher](#the-switcher) is
129
+ shown the list gives way to the title `workspaces`.
130
+ - **Under the list** stands what the view needs to say first, wrapped to
131
131
  the sidebar's width: a deployment's state when it is not live, with
132
132
  `since …` and its reason on rows of its own; the note of a view of one
133
133
  deployment; and the line that says what happened after an open, an act or
134
- a spawn. Then an empty row.
134
+ a spawn. Then an empty row. A line that goes at the next key and fits one
135
+ row (`No workspace above this one.`) stands in that empty row instead, so
136
+ nothing under it moves.
135
137
  - **The views** follow as an accordion, always in this order: `Instances`,
136
138
  `Souls`, `Capabilities`, each with its key dim at the right edge. The open
137
139
  view's heading is bold and its list stands under it, with a rule between
138
140
  it and the views before and after it. `1`, `2` and `3` open them in the
139
141
  list, and [the leader](#the-leader) then `1`, `2` or `3` from anywhere;
140
- the leader's hint, [the palette](#the-palette) and the help name those
141
- keys. [The Souls view](#the-souls-view) lists the open workspace's souls,
142
+ [the palette](#the-palette) and the help name those keys. [The Souls view](#the-souls-view) lists the open workspace's souls,
142
143
  and [the Capabilities view](#the-capabilities-view) its capabilities. A
143
144
  workspace with no instances reads `No agents yet: n spawns one`, with the
144
145
  key `spawn` has (`No agents yet.` when it has none).
@@ -149,14 +150,14 @@ while a terminal is open); under 80 columns it has the whole width.
149
150
  `Ctrl+K palette`. In a view's list it names what `Enter` does now
150
151
  (`open`, `focus terminal` on the row whose terminal is open, `detail`
151
152
  in the Souls and Capabilities views), then `n spawn` where it spawns,
152
- `w workspaces` (the [switcher](#the-switcher)) in the Instances view,
153
+ `w workspaces` ([the list of workspaces](#the-list-of-workspaces)) in the Instances view,
153
154
  and `? help` and `q quit` last; with the detail's focus `Tab back`
154
155
  comes before `Enter`. The other keys (the acts, `/`, `Tab`, `r`,
155
156
  and a terminal's `z`, `c`, `[` and `]`) are not listed there:
156
- the leader's hint, the palette and the help name them. While the
157
+ the palette and the help name them. While the
157
158
  terminal has the focus, in an overlay and in the filter field it names
158
- the keys that work them. While the leader waits for its key the rows are
159
- the leader's hint.
159
+ the keys that work them. While the leader waits for its key the rows do
160
+ not change.
160
161
  Everything flows from the top, so empty rows are at the bottom. On a
161
162
  short screen the list keeps its rows first: the cheat sheet gives up rows
162
163
  from its end, down to the leader alone, then the empty row under the
@@ -182,21 +183,32 @@ while a terminal is open); under 80 columns it has the whole width.
182
183
  indent alone says which instance is under which: no mark is drawn for
183
184
  it. A row whose instances are folded away (`h`) says how many after its
184
185
  name: `+1`.
185
- - **Each row** is the mark of its state and the name, then, when it needs
186
- input, a tag at its right edge in the Desktop's words: `Needs input`. A
186
+ - **Each row** is the mark of its state and the name. A row that needs
187
+ input has the needs-input mark in place of its state mark: `!`, bold,
188
+ in reverse video in the waiting colour, a yellow cell with the `!` cut
189
+ out (the Desktop's mark in one cell), whatever the row's state and its
190
+ instance colour. On the selected row, which is in reverse video already,
191
+ it is the waiting colour not reversed, a gap in the selection's bar;
192
+ under `NO_COLOR` the reverse video and the `!` carry it, and in ASCII it
193
+ is the same `!`. The detail says it in words (its `needs` line, the
194
+ reason and how long it has waited), and so does the help. The row shows the name as words, as the Desktop's sidebar does: each `-`
195
+ a space and the first letter upper-case, so `oats-expert-lead` reads
196
+ `Oats expert lead`. Only the row does: the detail, the filter (`/` with
197
+ `oats-expert` still finds the row), the palette, the tabs, the
198
+ confirmations and everything sent to OATS keep the instance's name. A
187
199
  folded row with waiting instances among those it folds away says how
188
- many: `3 below`, and `99+ below` past 99. A row that needs input itself
189
- and folds waiting ones away says `Needs input`, as the Desktop's row
190
- does: the detail's `below` line names the others. The tag is in reverse
191
- video in the waiting colour, and on the selected row, which is in reverse
192
- video already, it is the waiting colour not reversed, a gap in the
200
+ many in a tag at its right edge, in the Desktop's words: `3 below`, and
201
+ `99+ below` past 99, whether or not the row needs input itself: its mark
202
+ says its own claim, the tag the rest, and the detail's `below` line names
203
+ them. The tag is in reverse video in the waiting colour, and on the
204
+ selected row it is the waiting colour not reversed, a gap in the
193
205
  selection's bar; under `NO_COLOR` the reverse video alone carries it. On
194
206
  a narrow row the tag gives way first: it says its words only where the
195
207
  whole name, its `+1` and the row's word in its column all fit beside them,
196
- and else shrinks to `!`, or the count alone (`3`, `99+`), still in
197
- reverse video, in the cells every row keeps at its right edge. So the
198
- tag never cuts a name, a word or a mark: those give way as on a row
199
- that does not wait. The harness and the state in words are in
208
+ and else shrinks to the count alone (`3`, `99+`), still in reverse video,
209
+ in the cells every row keeps at its right edge. So the tag never cuts a
210
+ name, a word or a mark: those give way as on a row whose instances do
211
+ not wait. The harness and the state in words are in
200
212
  the detail. A row has a word, dim, only where its mark cannot say it: the
201
213
  state of a home a spawn or a retire holds (`Retire didn't finish`), or
202
214
  the shared words for why an instance cannot be reached or opened:
@@ -260,16 +272,17 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
260
272
  deployment, such as `garnet now reports workspace other.` for a machine
261
273
  that reported another workspace before, or that a deployment's teams are
262
274
  local only. It stands under the deployment's heading. In a view of one
263
- deployment, which has no heading, it stands under the title.
275
+ deployment, which has no heading, it stands under the list of workspaces.
264
276
  - **The detail has a `machine` line**, the machine the selected instance is
265
277
  on. When that deployment is not live, the whole sentence that says why
266
278
  follows it.
279
+ - **In a view of one deployment of another machine**, which has no heading,
280
+ the detail has the `machine` line too: nothing else names the machine.
267
281
 
268
- **A view that holds no deployment of this machine** says so in its title:
269
- `other on garnet` for one machine, `2 machines` after the name for
270
- two or more. The time on the help's top row is then the time the machines'
271
- rows were read. A view of one machine has no heading, so its state, when it
272
- is not live, is said under the title with the reason, as for a deployment
282
+ **A view that holds no deployment of this machine** names its machines in
283
+ its headings, or, with one machine, in the detail's `machine` line. The time
284
+ on the help's top row is then the time the machines' rows were read. A view of one machine has no heading, so its state, when it
285
+ is not live, is said under the list of workspaces with the reason, as for a deployment
273
286
  of this machine. When no row of that machine is kept either, nothing is drawn
274
287
  under the reason: no list and no detail.
275
288
 
@@ -289,20 +302,23 @@ in its workspace for the rest of the run, also while it is not reached.
289
302
  | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
290
303
  | `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
291
304
  | `+n` | `+n` | after a name: n instances folded away below it |
292
- | `Needs input` | `Needs input` | needs input: a tag in reverse video at the row's right edge, `!` where the whole name does not fit beside the words |
293
- | `N below` | `N below` | N instances folded away below it need input, `N` where the whole name does not fit beside the words |
305
+ | `!` | `!` | needs input: in place of the state mark, in yellow and reverse video (not reversed on the selected row) |
306
+ | `N below` | `N below` | N instances folded away below it need input: a tag in reverse video at the row's right edge, `N` where the whole name does not fit beside the words |
294
307
  | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
295
308
  | `*` | `*` | in the switcher: the workspace that is open |
296
309
 
297
- Every state has a mark of its own shape, so nothing is told by colour alone.
310
+ Every state has a mark of its own shape, and so does needs input, so
311
+ nothing is told by colour alone.
298
312
 
299
313
  **An instance's colour** (feature `instance-color`; set with
300
314
  `oats instance color <instance> <colour>`, [desktop-cli-api.md](desktop-cli-api.md#an-instances-colour-oats-instance-color))
301
315
  colours its mark, in the list and in a soul's detail: a running mark in it, a
302
316
  stopped one and one with a shell left in it dim in it. `?` and `◆` keep their
303
317
  own look whatever the colour, and an instance with no colour looks as above.
304
- The six colours are the terminal's: `sand` yellow, `sage` green, `slate` blue,
305
- `mauve` magenta, `clay` red, `olive` cyan, the souls' own map. Which colour a
318
+ The six colours are the terminal's: `sand` its own foreground colour, `sage`
319
+ green, `slate` blue, `mauve` magenta, `clay` red, `olive` cyan, the souls' own
320
+ map. `sand` is not yellow, which says needs input and nothing else, and in the
321
+ foreground colour it is seen on a light theme as on a dark one. Which colour a
306
322
  row shows is the Desktop's rule (`instanceColor` in `packages/client`); an
307
323
  older kernel reports none. Setting a colour from the TUI is not in this
308
324
  version.
@@ -332,7 +348,7 @@ last rows stay as they were; or they stay and are marked `stale`, with the
332
348
  time of the last read that succeeded (a remote that could not be read
333
349
  again); or the
334
350
  deployment is `not observed` and no row is drawn. A state that is not live
335
- is said in words under the title, with the reason on rows of its own. When
351
+ is said in words under the list of workspaces, with the reason on rows of its own. When
336
352
  the kernel refused the read and no rows are kept, the reason says so and
337
353
  quotes it: `OATS answered with an error (<code>). It says: <message>`. When
338
354
  the last rows are kept as `stale`, the reason says so and then quotes the
@@ -358,7 +374,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
358
374
  ## Open an agent's terminal
359
375
 
360
376
  ```
361
- acme-platform │[backend-lead]
377
+ acme-platform │[backend-lead 1]
362
378
  │$ make docs
363
379
  Instances 1 │Building the reference...
364
380
  > ● backend-lead │
@@ -367,6 +383,10 @@ fit; the detail shows them whole. The TUI's own words end the same way:
367
383
  Souls 2 │
368
384
  Capabilities 3 │
369
385
  ──────────────────────────────│
386
+ Alt+K palette │
387
+ Alt+Shift+Up/Down agent │
388
+ Alt+W close │
389
+ Alt+Z zoom │
370
390
  Ctrl+X commands │
371
391
  Ctrl+X Esc the list │
372
392
  Ctrl+X Ctrl+X types Ctrl+X │
@@ -374,8 +394,8 @@ fit; the detail shows them whole. The TUI's own words end the same way:
374
394
 
375
395
  - **`Enter` on an instance that runs** opens its terminal on the right of
376
396
  the sidebar, where the detail was, over every row. Its top row is the
377
- [tab bar](#tabs), here one tab: the agent's name in brackets (and
378
- ` · <machine>` for one of another machine); under it is the
397
+ [tab bar](#tabs), here one tab: the agent's name and the tab's number in
398
+ brackets (no number on macOS; and ` · <machine>` for one of another machine); under it is the
379
399
  agent's screen, as the agent draws it, in its own colours. While a
380
400
  terminal is open the sidebar keeps 30 columns at most, also while the
381
401
  detail stands in the terminal's place, and a name longer than its row is
@@ -385,25 +405,28 @@ fit; the detail shows them whole. The TUI's own words end the same way:
385
405
  among them, but for **[the leader](#the-leader)** (`Ctrl+X`, unless
386
406
  [`tui.json`](#change-the-keys-tuijson) names another), the
387
407
  one key the TUI takes from the agent, and the [chords](#chords) (the
388
- Ctrl+Alt ones, or the Ctrl+Shift ones under
389
- [the option](#switch-to-ctrlshift), while your terminal sends them). Under the kitty keyboard protocol every key reaches
408
+ Alt ones by default, or the Ctrl+Alt or Ctrl+Shift ones when
409
+ [keys.json chooses them](#switch-family), while your terminal sends them). Under the kitty keyboard protocol every key reaches
390
410
  the agent as the bytes it sends without it. The leader then `Esc` gives the
391
411
  focus to the list; the leader twice types the leader into the agent; the
392
412
  leader then another key does what that key does from anywhere. While the
393
413
  terminal has the focus the cheat sheet names those three:
394
414
  `Ctrl+X commands`, `Ctrl+X Esc the list`, `Ctrl+X Ctrl+X types Ctrl+X`.
395
- While the terminal confirms the kitty keyboard protocol
396
- ([Chords](#chords)) the chords come first: `Ctrl+Alt+K palette`,
397
- `Alt+Shift+Up/Down agent`, `Alt+Shift+Left/Right tab` (with two tabs or
398
- more), `Ctrl+Alt+W close`, `Ctrl+Alt+Z zoom` (`Ctrl+Shift+K`,
399
- `Ctrl+Shift+W` and `Ctrl+Shift+M` under the option), then the leader's three.
400
- Without it the leader's three lead, and the Alt+Shift arrows follow them.
415
+ While every chord of the family in force is read ([Chords](#chords)),
416
+ which in the Alt family is in every terminal, the chords come first:
417
+ `Alt+K palette`, `Alt+Shift+Up/Down agent`, `Alt+Left/Right tab` (with
418
+ two tabs or more), `Alt+W close`, `Alt+Z zoom`, then the leader's three.
419
+ In the Ctrl+Alt family they are `Ctrl+Alt+K`, `Alt+Shift+Left/Right`,
420
+ `Ctrl+Alt+W` and `Ctrl+Alt+Z`, and in the Ctrl+Shift family
421
+ `Ctrl+Shift+K`, `Ctrl+Shift+W` and `Ctrl+Shift+M`, which lead only while
422
+ the terminal confirms the kitty keyboard protocol. Without it the
423
+ leader's three lead, and the Alt+Shift arrows follow them.
401
424
  On a short screen the sheet gives up rows from its end, and the leader's
402
425
  `commands` last of all. A leader inside a bracketed paste is pasted, not
403
426
  taken.
404
427
  - **With the list focused** the terminal stays open, and the agent's screen
405
428
  is still drawn as it changes. The cheat sheet names `Enter focus terminal`
406
- on its row; the leader's hint names `z zoom` and `w close terminal`.
429
+ on its row; the help names the leader's `z` (zoom) and `w` (close terminal).
407
430
  - `Enter` on the shown terminal's row gives it the focus again.
408
431
  - `z` gives it the focus and the whole screen: the sidebar is hidden. The
409
432
  leader then `Esc` brings the sidebar back beside it, and the leader then
@@ -424,10 +447,9 @@ fit; the detail shows them whole. The TUI's own words end the same way:
424
447
  than 40 columns: with less room it has the whole screen too.
425
448
  - **With the whole screen** (zoomed, or a narrow terminal) no cheat sheet is
426
449
  drawn. The terminal's tab bar carries the keys at its right, dim:
427
- `Ctrl+X commands Ctrl+X Esc the list`, after the chords under the kitty
428
- keyboard protocol, as many as fit, and while the leader waits, the
429
- leader's hint, as many keys as fit, `Esc the list` last. The agent's
430
- screen keeps every row under it.
450
+ `Ctrl+X commands Ctrl+X Esc the list`, after the chords while they
451
+ lead the cheat sheet (above), as many as fit, the same while the leader waits. The
452
+ agent's screen keeps every row under it.
431
453
  - **A terminal also closes by itself** when its viewer ends, shown or
432
454
  hidden ([which tab is shown then](#tabs)): the agent's
433
455
  window ended, its session went away, or the link to its machine dropped.
@@ -438,7 +460,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
438
460
  terminal without it when it has not come. A tmux built with libutempter
439
461
  (Ubuntu's and Debian's are) can lose that status: while it waits,
440
462
  `oats tui` has tmux look for it again once a second, so the terminal
441
- still closes within a second or two with the line its status calls for. The instances are then read again at once, and the line under the title
463
+ still closes within a second or two with the line its status calls for. The instances are then read again at once, and the line under the list of workspaces
442
464
  says what happened: that it could not be opened, that the connection to
443
465
  its machine ended, or that the viewer ended without saying why. What the
444
466
  viewer printed on its error output stands under that line in quotation
@@ -467,7 +489,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
467
489
  ## Tabs
468
490
 
469
491
  ```
470
- acme-platform │[backend-lead]│ docs-writer• │ qa-runner
492
+ acme-platform │[backend-lead 1]│ docs-writer• 2 │ qa-runner 3
471
493
  │$ make test
472
494
  Instances 1 │ok 41 of 41
473
495
  > ● backend-lead │
@@ -477,6 +499,11 @@ fit; the detail shows them whole. The TUI's own words end the same way:
477
499
  Souls 2 │
478
500
  Capabilities 3 │
479
501
  ──────────────────────────────│
502
+ Alt+K palette │
503
+ Alt+Shift+Up/Down agent │
504
+ Alt+Left/Right tab │
505
+ Alt+W close │
506
+ Alt+Z zoom │
480
507
  Ctrl+X commands │
481
508
  Ctrl+X Esc the list │
482
509
  Ctrl+X Ctrl+X types Ctrl+X │
@@ -488,7 +515,7 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
488
515
  one tab or many, as a terminal's own tabs read: each tab's agent, in the
489
516
  order the tabs were opened, a dim `│` (`|` in ASCII) between two tabs.
490
517
  - **The shown tab** is the one whose screen the panel draws, the front
491
- tab. It stands in brackets, `[backend-lead]`, a mark that needs no
518
+ tab. It stands in brackets, `[backend-lead 1]`, a mark that needs no
492
519
  style, so it reads the same under `NO_COLOR` and in ASCII. Its name is
493
520
  bold, and the whole tab is in reverse video while the terminal has the
494
521
  focus.
@@ -497,7 +524,26 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
497
524
  name (`*` in ASCII), not dim; the mark goes when the tab is shown. A
498
525
  hidden tab's screen is not read: only that its agent wrote.
499
526
  - **An agent of another machine** reads `<name> · <machine>` inside its
500
- tab, the machine dim (`-` for `·` in ASCII): `[billing-lead · garnet]`.
527
+ tab, the machine dim (`-` for `·` in ASCII): `[billing-lead · garnet 1]`.
528
+ - **Each tab ends with its number:** its position in its group's strip,
529
+ the N that `Alt+N` (`tab-N`) shows. It stands after the name, the
530
+ activity mark and the machine, one blank cell before the tab's closing
531
+ side (`[backend-lead 1]`, ` docs-writer• 2 `). It is dim, and dim in the
532
+ reverse video of the shown tab while its terminal has the focus. In a
533
+ [split](#splits) each group numbers its own tabs from 1. The first eight
534
+ tabs are numbered 1 to 8. In a strip of nine or more, the last tab
535
+ shows 9 (`tab-9` shows the last tab) and the others past the eighth
536
+ show none; with four tabs at most today, that is never reached. The
537
+ number is a position, not a key label: it is the same in every chord
538
+ family, and the same in ASCII. On macOS no tab has one: `⌥⌘1` to `⌥⌘9`,
539
+ the Desktop's keys for them, never reach a terminal, so no key would
540
+ reach the numbers.
541
+ - **The numbers go first, and all together.** They are drawn only while
542
+ every tab fits whole with them, every name and every machine.
543
+ Otherwise no tab shows a number, and the row is cut as below. A number
544
+ never takes a cell from a name. At 80 columns, with the sidebar beside
545
+ the panel, the numbers usually go at the third or fourth tab; at 120
546
+ all four fit.
501
547
  - **A bar longer than its row is cut** in this order: the hidden tabs'
502
548
  machines, then the hidden tabs' names, each to an equal share of what
503
549
  the shown tab leaves, with `…` (`...` in ASCII), then the shown tab's
@@ -506,7 +552,7 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
506
552
  stays whole while the row can hold it, and is cut last.
507
553
  - The TUI takes no mouse input: a tab is shown with the keys below.
508
554
  - **Opening.** `Enter` on a row, an instance in
509
- [the palette](#the-palette), the leader then `Up` or `Down`, and a
555
+ [the palette](#the-palette), `Alt+Shift+Up` or `Alt+Shift+Down`, and a
510
556
  [spawn](#spawning-an-agent)'s new agent open a terminal the same way:
511
557
  - an instance that has a tab: that tab is shown, with the focus in it;
512
558
  - any other: a new tab, after the shown one, is shown with the focus in
@@ -515,17 +561,20 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
515
561
  machine is asked whether it can be opened, another open does nothing,
516
562
  and neither does a key that shows another tab.
517
563
  - **At four tabs nothing closes by itself.** The open does nothing, and
518
- the line under the title says `4 terminals are open; close one with Ctrl+X w.`
564
+ the line under the list of workspaces says `4 terminals are open; close one with Ctrl+X w.`
519
565
  (with your leader, when [`tui.json`](#change-the-keys-tuijson) names
520
566
  another). A tab still starting, and an agent of another machine while
521
567
  it is asked, hold a place among the four. An instance that cannot be
522
568
  opened says why, as it does with no tab open.
523
569
  - **Switching.** `[` and `]` in the Instances view, from the list or the
524
570
  detail, show the tab before or after the shown one; the help names them,
525
- and the leader's hint names the leader's own while two tabs or more are
526
- open. The leader then
571
+ and the leader's own. The leader then
527
572
  `Left` or `Right` does the same from any focus, and from another view
528
- goes to the Instances view first.
573
+ goes to the Instances view first, and so do the [chords](#chords)
574
+ `Alt+Left` and `Alt+Right` (`Alt+Shift+Left` and `Alt+Shift+Right` in the
575
+ Ctrl+Alt and Ctrl+Shift families). `Alt+1` to `Alt+8` show the focused
576
+ group's first to eighth tab, and `Alt+9` its last (`Ctrl+Alt+1` to
577
+ `Ctrl+Alt+9` in the other families).
529
578
  - The bar does not wrap: on the first tab `[` does nothing, and on the
530
579
  last `]`; the leader then `Left` or `Right` there leaves even the focus
531
580
  where it was.
@@ -548,19 +597,44 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
548
597
  - Closing the last tab closes the panel: the right side is the detail
549
598
  again, and the list has the focus.
550
599
  - **A tab that closes by itself**, when its viewer ends, says so on the line
551
- under the title in the words [above](#open-an-agents-terminal), for that
600
+ under the list of workspaces in the words [above](#open-an-agents-terminal), for that
552
601
  tab's agent (no line when it ended cleanly).
553
602
  - The shown tab: the tab to its right is shown, else the one to its left,
554
603
  and the list takes the focus.
555
604
  - A hidden tab: the shown tab and the focus stay as they were.
556
605
  - **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole
557
606
  screen. The tab bar stays its top row, and the other tabs stay open.
558
- - **The tabs are the open workspace's.** Opening another workspace in
559
- [the switcher](#the-switcher) closes them all, and so does the open
560
- workspace no longer being listed; their agents keep running. Coming back
561
- opens none of them again. Opening the same workspace again, with its
562
- deployment of this machine now opened beside another machine's, keeps
563
- them.
607
+ - **The tabs are the open workspace's, and it keeps them while the run
608
+ lasts.** Opening another workspace in [the switcher](#the-switcher)
609
+ closes their viewers; their agents keep running, and nothing of a hidden
610
+ workspace's terminals runs meanwhile. Coming back opens them again, one
611
+ at a time as an open goes, once the workspace's rows are read; a tab of
612
+ one of its deployments whose last read failed waits, with the tabs after
613
+ it, until that deployment is read again:
614
+ - the tabs in their order and their groups, the split, each group's
615
+ shown tab, and the focus (the terminal's, zoomed or not, or the list's)
616
+ as the workspace was left. The shown tab is the most recent for
617
+ [the palette](#the-palette).
618
+ - A tab whose instance is gone or cannot be opened now (retired,
619
+ stopped) is dropped, and nothing is said of it. A group the drops
620
+ leave with no tab goes, as when its last tab is closed; a group that
621
+ was empty when the workspace was left is empty again. A shown tab
622
+ dropped gives its place to the next, else the one before.
623
+ - Another machine's tab is asked first again, as an open is; when that
624
+ fails, the line says why and the tab is dropped. Suspending the TUI
625
+ while it is asked asks it again once the TUI is back.
626
+ - A key pressed while the tabs open again leaves the focus where it is:
627
+ the tabs still open, and the list keeps it. Opening an agent yourself
628
+ meanwhile stops it: the tabs not open yet are dropped. Opening another
629
+ workspace meanwhile closes what was opened, and keeps the rest for the
630
+ next time.
631
+
632
+ A workspace no longer being listed forgets them, open (its tabs close)
633
+ or not; one listed again later starts with none. A read that failed is
634
+ not the workspace gone: it forgets nothing.
635
+ Opening the same workspace again, with its deployment of this machine
636
+ now opened beside another machine's, keeps them as they are. Nothing is
637
+ kept after the run ends.
564
638
 
565
639
  ## Splits
566
640
 
@@ -590,7 +664,7 @@ tab and the marks of its hidden ones.
590
664
  (left, or top). The second group starts empty and is the focused group.
591
665
  - A split needs a tab open, and none starting.
592
666
  - **There are at most two groups.** With two, the split keys do nothing,
593
- and the line under the title says `The panel has two groups already.`
667
+ and the line under the list of workspaces says `The panel has two groups already.`
594
668
  - **Each group needs 40 columns side by side, and 8 rows one above the
595
669
  other**, its tab bar counted. The panel beside the sidebar then needs 81
596
670
  columns (a terminal of 112), or 17 rows. A split that would leave a
@@ -616,7 +690,7 @@ tab and the marks of its hidden ones.
616
690
  - **Zoom** (`z`, or the leader then `z`) gives the focused group's shown
617
691
  terminal the whole screen, and the same key brings the split back. With
618
692
  the empty group focused it does nothing.
619
- - **Opening.** `Enter`, the palette, the leader then `Up`/`Down` and a
693
+ - **Opening.** `Enter`, the palette, `Alt+Shift+Up`/`Alt+Shift+Down` and a
620
694
  spawn open as with one group:
621
695
  - an instance that has a tab, in either group: that tab is shown in its
622
696
  group, and that group takes the focus;
@@ -809,9 +883,95 @@ them, from the same code.
809
883
  each with where it comes from; choosing one shows this view with it
810
884
  selected.
811
885
 
886
+ ## The list of workspaces
887
+
888
+ ```
889
+ acme-platform │ dev
890
+ acme-billing ● │ soul dev
891
+ lfx │ state running
892
+ garnet │ harness claude, claude-opus-5-5 (so…
893
+ +2 │ work worktree, agents/dev
894
+ │ team eng
895
+ Instances 1 │ started 11:00
896
+ ```
897
+
898
+ The sidebar's first rows list the workspaces this run can show, one row a
899
+ workspace, whatever machines it is on, in [the switcher](#the-switcher)'s
900
+ order: `lfx` is one row however many machines hold it, and a machine the
901
+ rules shared with the Desktop matched to no workspace is a row by its own
902
+ name, in the same flat list. A row is one line: the name. With one
903
+ workspace the list is its row.
904
+
905
+ - **Not in the list:** this computer's deployments that this run has not
906
+ opened (a workspace only they make), and the rows that cannot be opened
907
+ (missing, not a deployment, unreadable, a machine with nothing to open).
908
+ The switcher keeps them: `w` twice.
909
+ - **The open workspace's row** is in reverse video, and while the list has
910
+ the focus its name is underlined instead (the cursor has the reverse
911
+ video). Its state, when it is not live, is said under the list.
912
+ - **The dot**, `●` in yellow one cell after the name, says that an instance
913
+ of that workspace needs input, the claim the list of instances shows, the
914
+ open workspace's included. On a row in reverse video its cell is a gap in
915
+ the bar: the dot is on the normal background. With colour off
916
+ (`NO_COLOR`) or in ASCII it is `!`, and the help's Marks name it. It
917
+ comes from what this run observes alone, its reads of the deployments it
918
+ serves and of other machines: a workspace whose instances are not known
919
+ (never read, stale, not reached) has no dot, never a false one. The dot
920
+ never moves a row.
921
+ - **A long name** is cut with `…` (`...` in ASCII), the dot one cell after
922
+ what is drawn of it, as it is after a name drawn in `?` where the locale
923
+ is not UTF-8.
924
+ - **Five rows at most.** With more, four stand around the open row (around
925
+ the cursor's while the list has the focus), and `+N` says how many
926
+ workspaces are not shown, with the dot one cell after it when an instance
927
+ of one of them needs input (`+3 ●`; the help's Marks say so too). Under 80 columns or beside a terminal (30
928
+ columns) the names are cut as the list of instances cuts them.
929
+
930
+ **The keys:**
931
+
932
+ - **The leader then `Up` or `Down`**, or the [chords](#chords) `Alt+Up` and
933
+ `Alt+Down` (in the Alt family and on macOS; the Ctrl+Alt and Ctrl+Shift
934
+ families leave them to the programs, and the leader does it), opens the
935
+ workspace before or after the open one, as the list draws them. It does not wrap: at an end nothing
936
+ moves, and the line under the list says `No workspace above this one.` or
937
+ `No workspace below this one.` until the next key, of any kind (one typed
938
+ to an agent too), or a resize. The line stands in the empty row under the
939
+ list, so the list of instances does not move while it shows; only when
940
+ that list fills the sidebar, which then has no such row, does the line
941
+ take a row, the list giving up its last. With the list's focus (`w`) the
942
+ focus stays there, the cursor where it was. A workspace with a deployment of this
943
+ machine not opened yet (lfx, with `~/Work/lfx` on this computer's list)
944
+ opens it first, as the switcher's `Enter` does. What the workspace left
945
+ had open is kept for it, as for a switch from the
946
+ switcher ([Tabs](#tabs)), and from a terminal's focus the focus is kept
947
+ too.
948
+ With no workspace open (a run started outside a deployment, or the open
949
+ one gone), the switcher is shown, and the leader then `Down` opens the
950
+ first row the list would hold and `Up` its last; with no such row
951
+ nothing happens.
952
+ - **`w`**, the leader then `o`, and `Alt+O` (`Ctrl+Alt+O` or
953
+ `Ctrl+Shift+S` in the [other families](#switch-family)) give the list the focus, on the open workspace's row. The row
954
+ under the cursor carries `>` and the reverse video, and the open
955
+ workspace's name is underlined until `Enter` opens another; the list of
956
+ instances keeps its selection in reverse video, without its `>`. `Up`/`k`,
957
+ `Down`/`j`, `g`/`Home` and `G`/`End` move the cursor over the rows that
958
+ open; `Enter` opens its row and gives the list of instances the focus;
959
+ `Esc` gives that focus back with nothing opened; `w` again opens the
960
+ switcher, for what the list does not hold. Any other key gives the list
961
+ of instances the focus, then does what it does there. The cheat sheet
962
+ says `Enter open`, `Up/Down move`, `Esc back`, `w all workspaces`, with
963
+ the keys `tui.json` gives those actions; one with no key has no hint.
964
+ A row whose deployment an identity read places in a workspace (or takes
965
+ out of one) keeps the cursor: it moves to the row that now holds it.
966
+ - The list is no stop of `Tab`, and the TUI takes no mouse input.
967
+
812
968
  ## The switcher
813
969
 
814
- `w` opens the switcher: what this run can show, over the main area. The
970
+ `w` from [the list of workspaces](#the-list-of-workspaces)' focus (`w` twice
971
+ from the list of instances) opens the switcher: what this run can show, over
972
+ the main area, with what the list does not hold: each deployment's line,
973
+ this computer's deployments not opened, the rows that cannot be opened, the
974
+ filter, and Remove. With no workspace open, `w` opens it at once. The
815
975
  sidebar's title says `workspaces` and no view is open; under 80 columns the
816
976
  switcher covers the whole screen.
817
977
 
@@ -940,10 +1100,12 @@ A workspace this run has open has no Remove here.
940
1100
  would make the file refused at the start. To use another key, give it to
941
1101
  `remove` there, for example `{ "keys": { "remove": ["x"] } }`.
942
1102
 
943
- **Each view keeps its place while the run lasts:** the selected instance,
944
- where its list and its detail were scrolled, and what was folded away are
945
- found again when the view is opened again. A filter is not kept from one
946
- view to another, and nothing is kept after the run ends.
1103
+ **Each workspace keeps its place while the run lasts:** the selected
1104
+ instance, where its list and its detail were scrolled, the filter, and what
1105
+ was folded away are found again when the workspace is opened again, through
1106
+ any of its deployments. A filter still being typed in is kept as `Enter`
1107
+ keeps it. Another workspace starts with no filter, or with its own. Nothing
1108
+ is kept after the run ends.
947
1109
 
948
1110
  **When the open workspace stops being listed** (it was a machine, and the
949
1111
  kernel's answer stopped naming it), the switcher is shown with
@@ -975,7 +1137,7 @@ confirmation, which is needed only when the first retire's holder can't be
975
1137
  read, since the kernel refuses a second retire while one runs. The
976
1138
  palette offers the acts the selected instance offers now, and the leader's
977
1139
  hint and the help name their keys. A key for an act
978
- the instance does not offer opens nothing, and the line under the title
1140
+ the instance does not offer opens nothing, and the line under the list of workspaces
979
1141
  says why. The keys are yours to change in
980
1142
  [`tui.json`](#change-the-keys-tuijson): the actions are `stop`, `retire`,
981
1143
  `start` and `restart`.
@@ -1127,48 +1289,61 @@ The line after leaving says so and names `oats status` to see it.
1127
1289
  The keys come in three layers:
1128
1290
 
1129
1291
  1. **In the list:** plain keys, such as `n` to spawn, `w` for the switcher, `/` to filter ([In the list](#in-the-list)).
1130
- 2. **Anywhere, an agent's terminal included:** the [chords](#chords), `Ctrl+Alt+K` and the rest by default, `Ctrl+Shift+K` and the rest [as the option](#switch-to-ctrlshift). Not plain `Ctrl+K`: that is the agent's, kill to the end of the line in Claude Code, Codex, pi and the shell.
1292
+ 2. **Anywhere, an agent's terminal included:** the [chords](#chords), `Alt+K` and the rest by default, `Ctrl+Alt+K` or `Ctrl+Shift+K` and the rest [in the other families](#switch-family). Not plain `Ctrl+K`: that is the agent's, kill to the end of the line in Claude Code, Codex, pi and the shell.
1131
1293
  3. **Always:** [the leader](#the-leader), `Ctrl+X` then a key, in every terminal.
1132
1294
 
1133
1295
  ### Every action's keys
1134
1296
 
1135
1297
  The same keys in `oats tui` and in OATS Desktop. A column per way in: the
1136
1298
  list's key (the Desktop's sidebar has the same, but `Ctrl+K`), the chord in
1137
- each family on Linux and Windows, the Desktop's chord on macOS (where
1138
- `oats tui` has no chords), and the key after the leader. `–` is no key of
1299
+ each family on Linux and Windows, the chord on macOS (the Desktop's;
1300
+ `oats tui` has those without ⌘, the ⌥ arrows: [Chords on
1301
+ macOS](#chords-on-macos)), and the key after the leader. `–` is no key of
1139
1302
  that kind.
1140
1303
 
1141
- | Action | In the list | Ctrl+Alt (default) | Ctrl+Shift (the option) | macOS Desktop | The leader then |
1142
- |---|---|---|---|---|---|
1143
- | the palette | `Ctrl+K` | `Ctrl+Alt+K` | `Ctrl+Shift+K` | `⌘K` | `k`, `Space` |
1144
- | spawn an agent (the Desktop's Quick Open) | `n` | `Ctrl+Alt+P` | `Ctrl+Shift+P` | `⌘P` | `n` |
1145
- | the switcher | `w` | `Ctrl+Alt+O` | `Ctrl+Shift+S` | `⌥⌘O` | `o` |
1146
- | zoom the shown terminal | `z` | `Ctrl+Alt+Z` | `Ctrl+Shift+M` | `⌥⌘Z` | `z` |
1147
- | close the shown terminal's tab | `c` | `Ctrl+Alt+W` | `Ctrl+Shift+W` | `⌘W` | `w` |
1148
- | split side by side | `\|` | `Ctrl+Alt+E` | `Ctrl+Shift+E` | `⌘\` | `\|` |
1149
- | split one above the other | `-` | `Ctrl+Alt+Shift+E` | `Ctrl+Shift+D` | `⌘⇧\` | `-` |
1150
- | the other group | – | `Ctrl+Alt+A` | `Ctrl+Alt+A` (kept) | `⌥⌘A` | `Tab` |
1151
- | the filter | `/` | `Ctrl+Alt+F` | `Ctrl+Alt+F` (kept) | `⌘F` | `/` |
1152
- | the terminal of the instance before, after | – | `Alt+Shift+Up`, `Alt+Shift+Down` | `Alt+Shift+Up`, `Alt+Shift+Down` (kept) | `⌥⌘↑`, `⌥⌘↓` | `Up`, `Down` |
1153
- | the tab before, after | `[`, `]` | `Alt+Shift+Left`, `Alt+Shift+Right` | `Alt+Shift+Left`, `Alt+Shift+Right` (kept) | `⌥⌘←`, `⌥⌘→` | `Left`, `Right` |
1154
- | the first to eighth tab, the last | – | `Ctrl+Alt+1` to `Ctrl+Alt+9` | `Ctrl+Alt+1` to `Ctrl+Alt+9` (kept) | `⌥⌘1` to `⌥⌘9` | – |
1155
- | an instance's name and colour (OATS Desktop only) | – | `Ctrl+Alt+R` | `Ctrl+Alt+R` (kept) | `⌥⌘R` | – |
1156
- | move the tab to the other group | – | – | – | – | `m` |
1157
- | close the empty group | – | – | – | – | `x` |
1158
- | stop, restart, start, retire | `X`, `R`, `S`, `D` | – | – | – | `X`, `R`, `S`, `D` |
1159
- | spawn another of the soul | `N` | – | – | – | `N` |
1160
- | the Instances, Souls, Capabilities views | `1`, `2`, `3` | – | – | – | `1`, `2`, `3` |
1161
- | the help | `?` | – | – | – | `?` |
1162
- | the list | `Esc` | – | – | – | `Esc` |
1163
-
1164
- The option moves seven chords to Ctrl+Shift. The others keep their key in
1165
- both families, marked kept: Ctrl+Shift with an arrow selects text in inputs
1166
- and editors, Ctrl+Shift with a digit is a shifted symbol on most layouts,
1167
- and Ctrl+Shift+A and Ctrl+Shift+F are taken by terminals (kitty, Ghostty,
1168
- and for F Alacritty and GNOME Terminal too) and by agents (Codex's
1169
- Ctrl+Shift+A, pi's Ctrl+Shift+F). `Ctrl+Alt+R` is the Desktop's alone, not
1170
- one of the seven: `oats tui` has no such action and binds no key for it. The list's own keys for moving and
1171
- reading are in [In the list](#in-the-list). The tables come from
1304
+ | Action | In the list | Alt (default) | Ctrl+Alt | Ctrl+Shift | macOS | The leader then |
1305
+ |---|---|---|---|---|---|---|
1306
+ | the palette | `Ctrl+K` | `Alt+K` | `Ctrl+Alt+K` | `Ctrl+Shift+K` | `⌘K` | `k`, `Space` |
1307
+ | spawn an agent (the Desktop's Quick Open) | `n` | `Alt+P` | `Ctrl+Alt+P` | `Ctrl+Shift+P` | `⌘P` | `n` |
1308
+ | the list of workspaces (`w` there: the switcher) | `w` | `Alt+O` | `Ctrl+Alt+O` | `Ctrl+Shift+S` | `⌥⌘O` | `o` |
1309
+ | the workspace before, after | – | `Alt+Up`, `Alt+Down` | – | – | `⌥↑`, `⌥↓` | `Up`, `Down` |
1310
+ | zoom the shown terminal | `z` | `Alt+Z` | `Ctrl+Alt+Z` | `Ctrl+Shift+M` | `⌥⌘Z` | `z` |
1311
+ | close the shown terminal's tab | `c` | `Alt+W` | `Ctrl+Alt+W` | `Ctrl+Shift+W` | `⌘W` | `w` |
1312
+ | split side by side | `\|` | `Alt+E` | `Ctrl+Alt+E` | `Ctrl+Shift+E` | `⌘\` | `\|` |
1313
+ | split one above the other | `-` | `Alt+Shift+E` | `Ctrl+Alt+Shift+E` | `Ctrl+Shift+D` | `⌘⇧\` | `-` |
1314
+ | the next group | – | `Alt+Shift+Right` | `Ctrl+Alt+A` | `Ctrl+Alt+A` | `⌥⇧→` | `Tab` |
1315
+ | the previous group | – | `Alt+Shift+Left` | `Ctrl+Alt+Shift+A` | `Ctrl+Alt+Shift+A` | `⌥⇧←` | `Shift+Tab` |
1316
+ | the filter | `/` | `Alt+F` | `Ctrl+Alt+F` | `Ctrl+Alt+F` | `⌘F` | `/` |
1317
+ | the terminal of the instance before, after | – | `Alt+Shift+Up`, `Alt+Shift+Down` | `Alt+Shift+Up`, `Alt+Shift+Down` | `Alt+Shift+Up`, `Alt+Shift+Down` | `⌥⌘↑`, `⌥⌘↓` | – |
1318
+ | the tab before, after | `[`, `]` | `Alt+Left`, `Alt+Right` | `Alt+Shift+Left`, `Alt+Shift+Right` | `Alt+Shift+Left`, `Alt+Shift+Right` | `⌥←`, `⌥→` | `Left`, `Right` |
1319
+ | the first to eighth tab, the last | – | `Alt+1` to `Alt+9` | `Ctrl+Alt+1` to `Ctrl+Alt+9` | `Ctrl+Alt+1` to `Ctrl+Alt+9` | `⌥⌘1` to `⌥⌘9` | – |
1320
+ | an instance's name and colour (OATS Desktop only) | – | `Alt+R` | `Ctrl+Alt+R` | `Ctrl+Alt+R` | `⌥⌘R` | – |
1321
+ | move the tab to the other group | – | – | – | – | – | `m` |
1322
+ | close the empty group | – | – | – | – | – | `x` |
1323
+ | stop, restart, start, retire | `X`, `R`, `S`, `D` | – | – | – | – | `X`, `R`, `S`, `D` |
1324
+ | spawn another of the soul | `N` | – | – | – | – | `N` |
1325
+ | the Instances, Souls, Capabilities views | `1`, `2`, `3` | – | – | – | – | `1`, `2`, `3` |
1326
+ | the help | `?` | – | – | – | – | `?` |
1327
+ | the list | `Esc` | – | – | – | – | `Esc` |
1328
+
1329
+ The Ctrl+Shift family moves seven of the Ctrl+Alt family's chords to
1330
+ Ctrl+Shift. The others keep their Ctrl+Alt key: Ctrl+Shift with an arrow
1331
+ selects text in inputs and editors, Ctrl+Shift with a digit is a shifted
1332
+ symbol on most layouts, and Ctrl+Shift+A and Ctrl+Shift+F are taken by
1333
+ terminals (kitty, Ghostty, and for F Alacritty and GNOME Terminal too) and
1334
+ by agents (Codex's Ctrl+Shift+A, pi's Ctrl+Shift+F). The workspace moves
1335
+ and the previous group are new in this version. The workspace moves are
1336
+ `Alt+Up` and `Alt+Down` in the Alt family alone: the Ctrl+Alt and
1337
+ Ctrl+Shift families are for whoever needs Alt in their programs, so they
1338
+ leave those keys to them, and the leader's `Up` and `Down` move between
1339
+ workspaces there. The previous group is `Alt+Shift+Left` in the Alt
1340
+ family, beside `Alt+Shift+Right` for the next, and `Ctrl+Alt+Shift+A` in
1341
+ the other two, beside `Ctrl+Alt+A`. On macOS the moves between tabs,
1342
+ groups and workspaces are ⌥ with an arrow, in both clients; the letters
1343
+ and digits keep ⌘, since ⌥ with one types a character.
1344
+ `Alt+R` (`Ctrl+Alt+R` in the other families) is the Desktop's alone:
1345
+ `oats tui` has no such action and binds no key for it. The list's own keys for moving and reading are in
1346
+ [In the list](#in-the-list). The tables come from
1172
1347
  `packages/client/keymap.mjs` (`CHORDS`, `PLAIN_KEYS`, `LEADER_TABLE`), which
1173
1348
  both clients read.
1174
1349
 
@@ -1176,70 +1351,182 @@ both clients read.
1176
1351
 
1177
1352
  For `oats tui`, on Linux and Windows. `✓` is a family whose chords reach
1178
1353
  `oats tui` in that terminal, `✗` one whose chords do not, with the reason.
1179
- The leader works in all of them. In OATS Desktop both families work.
1180
-
1181
- | Terminal | Ctrl+Alt (default) | Ctrl+Shift (the option) |
1182
- |---|---|---|
1183
- | foot | ✓ | ✓ |
1184
- | Alacritty | ✓ | ✓ |
1185
- | Ghostty | ✓ | ✗ Ghostty closes its own tab on Ctrl+Shift+W, taking oats tui with it |
1186
- | kitty | ✓ | ✗ kitty takes Ctrl+Shift+K, P, S, W and E for itself; W closes its window, `oats tui` with it |
1187
- | WezTerm | ✓ with `enable_kitty_keyboard`; without it only the Alt+Shift arrows | ✗ WezTerm takes Ctrl+Shift+K, P, M and W for itself: clear the scrollback, its command palette, hide the window, close the tab |
1188
- | GNOME Terminal | ✗ no kitty keyboard protocol (VTE has none): only the Alt+Shift arrows arrive | ✗ no kitty keyboard protocol: a Ctrl+Shift letter reaches a program as the Ctrl letter |
1189
- | Konsole | ✓ since 26.08 | ✗ Konsole takes all seven for itself; Ctrl+Shift+W closes the tab |
1190
- | Windows Terminal | ✓, but `Ctrl+Alt+1` to `9` are its tabs, and the Alt+Shift arrows resize its split panes | ✗ Windows Terminal takes Ctrl+Shift+K, P, M, W and D for itself; W closes the pane |
1191
-
1192
- Each terminal's defaults at the release
1354
+ The leader works in all of them. In OATS Desktop every family works. The
1355
+ Alt family needs no kitty keyboard protocol: `Alt` with a letter or a digit
1356
+ is `Esc` and the key, and the Alt arrows have sequences of their own, in
1357
+ every terminal below.
1358
+
1359
+ | Terminal | Alt (default) | Ctrl+Alt | Ctrl+Shift |
1360
+ |---|---|---|---|
1361
+ | foot | ✓ | ✓ | ✓ |
1362
+ | Alacritty | ✓ | ✓ | ✓ |
1363
+ | Ghostty | ✓, but on Linux `Alt+1` to `8` are its tabs and `Alt+9` its last, when the tab changes | ✓ | ✗ Ghostty closes its own tab on Ctrl+Shift+W, taking oats tui with it |
1364
+ | kitty | ✓ | ✓ | ✗ kitty takes Ctrl+Shift+K, P, S, W and E for itself; W closes its window, `oats tui` with it |
1365
+ | WezTerm | ✓ | ✓ with `enable_kitty_keyboard`; without it only the Alt+Shift arrows | ✗ WezTerm takes Ctrl+Shift+K, P, M and W for itself: clear the scrollback, its command palette, hide the window, close the tab |
1366
+ | GNOME Terminal | ✓, but with two tabs or more `Alt+1` to `9` are its tabs | ✗ no kitty keyboard protocol (VTE has none): only the Alt+Shift arrows arrive | ✗ no kitty keyboard protocol: a Ctrl+Shift letter reaches a program as the Ctrl letter |
1367
+ | Konsole | ✓, but with two tabs or more `Alt+1` to `9` are its tabs | ✓ since 26.08 | ✗ Konsole takes all seven for itself; Ctrl+Shift+W closes the tab |
1368
+ | Windows Terminal | ✓, but with split panes the Alt arrows move between them and the Alt+Shift arrows resize them | ✓, but `Ctrl+Alt+1` to `9` are its tabs, and the Alt+Shift arrows resize its split panes | ✗ Windows Terminal takes Ctrl+Shift+K, P, M, W and D for itself; W closes the pane |
1369
+
1370
+ Where a terminal takes `Alt` with a digit, the leader then `Left` or
1371
+ `Right` and `Alt+Left`, `Alt+Right` still go from tab to tab, or choose
1372
+ Ctrl+Alt. On macOS `oats tui` has the ⌥ arrows alone, and which macOS
1373
+ terminals send them is in [Chords on macOS](#chords-on-macos); a macOS
1374
+ terminal sends Option with a letter as a character (`Option+K` is `˚`)
1375
+ unless it is set to send Option as Meta (Terminal.app's "Use Option as
1376
+ Meta key", iTerm2's Option key "Esc+"), and then the program in the
1377
+ terminal gets it. Each terminal's defaults at the release
1193
1378
  [the full matrix](#which-terminals-let-the-chords-through) names.
1194
1379
 
1195
- ### Switch to Ctrl+Shift
1380
+ <a id="switch-to-ctrlshift"></a>
1196
1381
 
1197
- On Linux and Windows. macOS has no option: the Desktop keeps its ⌘ chords
1198
- there, and `oats tui` the leader.
1382
+ ### Switch family
1383
+
1384
+ On Linux and Windows. macOS has no choice: the Desktop keeps its ⌘ chords
1385
+ and its ⌥ arrows there, and `oats tui` the ⌥ arrows ([Chords on
1386
+ macOS](#chords-on-macos)) and the leader.
1199
1387
 
1200
1388
  - **In OATS Desktop:** the Shortcuts page (`Ctrl+,`), at its top, **Shortcut
1201
- family, shared with oats tui**: choose **Ctrl+Shift (foot, Alacritty)**. The Desktop writes the
1202
- file below and switches its keys at once. **Ctrl+Alt (default)** switches
1203
- back. A change by hand reaches the Desktop when it next gets the focus.
1389
+ family, shared with oats tui**: **Alt (default)**, **Ctrl+Alt (for
1390
+ programs that read Alt)** or **Ctrl+Shift (foot, Alacritty)**. The
1391
+ Desktop writes the file below and switches its keys at once. A change by
1392
+ hand reaches the Desktop when it next gets the focus.
1204
1393
  - **Or by hand:** write `$OATS_HOME_DIR/config/keys.json`, else
1205
1394
  `~/.oats/config/keys.json`, beside [`tui.json`](#change-the-keys-tuijson):
1206
1395
 
1207
1396
  ```json
1208
- { "chords": "ctrl+shift" }
1397
+ { "chords": "ctrl+alt" }
1209
1398
  ```
1210
1399
 
1211
- `"ctrl+alt"` is the default.
1400
+ or `"ctrl+shift"`. `"alt"` is the default, and no file, or a file with no
1401
+ `chords`, is the default too.
1402
+ - **A choice is kept.** A keys.json that says `"ctrl+alt"`, written by the
1403
+ Desktop or by hand before this version, when Ctrl+Alt was the default,
1404
+ keeps the Ctrl+Alt family with the keys it had. Only a user who never
1405
+ chose moves to Alt. An older client that does not know the Alt family
1406
+ reads `"chords": "alt"` as a value it cannot take, so it binds its own
1407
+ default and says so.
1212
1408
  - **`oats tui` reads it at its start:** restart it after a change, from the
1213
1409
  Desktop or by hand.
1214
- - **Nothing to fix when it is wrong.** A missing file, one that cannot be
1215
- read or is larger than 16 KiB, one that is not a JSON object, one with no
1216
- `chords` or another value: each means Ctrl+Alt, and the help says why
1217
- (`keys.json: unknown chords value, using Ctrl+Alt`). The Desktop changes
1218
- only `chords` and keeps every other key in the file; a file it cannot
1219
- keep whole it leaves as it is, and says so.
1410
+ - **Nothing to fix when it is wrong.** A file that cannot be read or is
1411
+ larger than 16 KiB, one that is not a JSON object, one with another
1412
+ value: each means Alt, and the help says why (`keys.json: unknown chords
1413
+ value, using Alt`). A missing file is the default with nothing to say. The
1414
+ Desktop changes only `chords` and keeps every other key in the file; a
1415
+ file it cannot keep whole it leaves as it is, and says so.
1220
1416
  - **It is the clients' file.** The kernel never reads it, and `tui.json`
1221
1417
  does not hold it.
1222
1418
  - **Your own keys still win, row by row.** A key you give an action in
1223
1419
  `tui.json`'s `keys` is not bound as a chord, and an action you rebind in
1224
- the Desktop's shortcuts editor keeps your key in either family; the
1225
- editor shows a clash with a key the option takes.
1226
- - **In `oats tui` the option needs the kitty keyboard protocol**
1227
- ([Chords](#chords)). Without it a Ctrl+Shift letter is the Ctrl letter,
1228
- so the TUI binds none: only the Alt+Shift arrows are chords, and the
1229
- leader does the rest.
1420
+ the Desktop's shortcuts editor keeps your key in every family; the
1421
+ editor shows a clash with a key a family takes.
1422
+ - **In `oats tui` the Ctrl+Alt and Ctrl+Shift families need the kitty
1423
+ keyboard protocol** ([Chords](#chords)). Without it `Ctrl+Alt+K` is `Esc`
1424
+ then `Ctrl+K`, and a Ctrl+Shift letter is the Ctrl letter, so the TUI
1425
+ binds none of them: only the Alt+Shift arrows, `Alt+Up` and `Alt+Down`
1426
+ are chords, and the leader does the rest. The Alt family needs nothing.
1230
1427
  - **The help says which family is in force.** In `oats tui` the help (`?`)
1231
- opens its chords with a line: `Shortcuts: Ctrl+Alt. For Ctrl+Shift (foot,
1232
- Alacritty), set "chords": "ctrl+shift" in keys.json and restart.`, or
1233
- `Shortcuts: Ctrl+Shift, from keys.json.`, or, in a terminal that does not
1234
- confirm the protocol, `Shortcuts: Ctrl+Shift, from keys.json, but this
1235
- terminal does not confirm the kitty keyboard protocol: use the leader.`
1236
- The Desktop's Shortcuts page shows the choice, `oats tui uses it from its
1237
- next start.` under it, and the same note when the file was not taken.
1238
-
1239
- ### What the option takes from an agent
1428
+ opens its chords with a line: `Shortcuts: Alt. To leave Alt to the
1429
+ programs in your terminals, set "chords": "ctrl+alt" in keys.json (or
1430
+ "ctrl+shift", for foot and Alacritty) and restart.`, or `Shortcuts:
1431
+ Ctrl+Alt, from keys.json.` (`Ctrl+Shift`, the same way), or, in a terminal
1432
+ that does not confirm the protocol, `Shortcuts: Ctrl+Alt, from keys.json,
1433
+ but this terminal does not confirm the kitty keyboard protocol: use the
1434
+ leader.` The Desktop's Shortcuts page shows the choice, `oats tui uses it
1435
+ from its next start.` under it, and the same note when the file was not
1436
+ taken.
1240
1437
 
1241
- With the option on, both clients take the seven Ctrl+Shift chords from
1242
- every focus, an agent's terminal included: the agent never gets them.
1438
+ ### What the Alt family takes
1439
+
1440
+ The Alt family's chords are keys that programs in a terminal read: the
1441
+ TUI takes them from every focus, an agent's terminal included, and the
1442
+ program never gets them. These are the keys it takes, by the programs' own
1443
+ key documentation (researched 2026-10-23; sources below). "Esc, then the
1444
+ key" works where the program says an `Esc` prefix is Meta: readline, zsh,
1445
+ Emacs and irssi do. Typed as two keys apart (more than 10 ms), `Esc` then
1446
+ the key reaches the program as those two bytes ([Chords](#chords)). Where a
1447
+ program's docs don't say, the way is marked unknown, and the Ctrl+Alt
1448
+ family gives the key back ([Switch family](#switch-family)). An Alt key no
1449
+ chord holds (`Alt+B`, `Alt+D`, `Alt+T`, `Alt+.`) is still the program's.
1450
+
1451
+ Unlike the Desktop's terminal, which sends an Alt arrow as the Ctrl arrow,
1452
+ the terminal you run `oats tui` in sends the Alt arrows as `CSI 1;3` (`Esc
1453
+ [1;3C` for `Alt+Right`), which programs read. So the TUI takes the Alt
1454
+ arrows from them too, in the Alt family. All four go back to the programs
1455
+ in the Ctrl+Alt and Ctrl+Shift families: `Alt+Up` and `Alt+Down`, the
1456
+ workspace moves, are the Alt family's alone.
1457
+
1458
+ | Program | Key the Alt family takes | What the program does with it | How it still gets it |
1459
+ |---|---|---|---|
1460
+ | Claude Code | `Alt+P` | the model picker | unknown: its docs don't say whether `Esc`, then `P` is Meta+P, and `Esc` alone interrupts; switch to Ctrl+Alt |
1461
+ | Claude Code | `Alt+O` | fast mode on or off | as `Alt+P` |
1462
+ | Claude Code | `Alt+F` | forward a word | as `Alt+P` |
1463
+ | Claude Code | `Alt+Up`, `Alt+Down` | in the `/diff` panel, the file list; in the agents view (`claude agents`), the group before or after | in the `/diff` panel `Ctrl+Up`, `Ctrl+Down`; in the agents view unknown |
1464
+ | Codex | `Alt+F` | a word right | `Ctrl+Right`, its other key for it |
1465
+ | Codex | `Alt+Left`, `Alt+Right` | the agent thread before or after, while the composer is empty; else a word left or right | the word moves: `Ctrl+Left`, `Ctrl+Right`; the threads: unknown, switch to Ctrl+Alt |
1466
+ | Codex | `Alt+Up` | edit the queued message | `Shift+Left` |
1467
+ | Codex | `Alt+Down` | back through the prompt stack | `Shift+Right` |
1468
+ | pi | `Alt+F` | a word right | `Esc`, then `f`: pi reads `ESC f` as a word right |
1469
+ | pi | `Alt+Left`, `Alt+Right` | a word left or right; in the session tree, fold or unfold | `Esc`, then `b` or `f`, which pi reads as `Alt+Left` and `Alt+Right` |
1470
+ | pi | `Alt+Up` | restore the queued messages to the editor; in the model selector, move a model up | `Esc`, then `p`, which pi reads as `Alt+Up` |
1471
+ | pi | `Alt+Down` | in the model selector, move a model down | `Esc`, then `n`, which pi reads as `Alt+Down` |
1472
+ | bash (readline) | `Alt+P`, `Alt+F` | search history back; forward a word | `Esc`, then `p` or `f` |
1473
+ | bash (readline) | `Alt+1` to `Alt+9` | a numeric argument | `Esc`, then the digit |
1474
+ | bash (readline) | `Alt+Left`, `Alt+Right` | a word back or forward | `Esc`, then `b` or `f` |
1475
+ | zsh (emacs keymap) | `Alt+P`, `Alt+Z`, `Alt+W`, `Alt+F` | history search back; run the last named command; copy the region; forward a word | `Esc`, then the letter |
1476
+ | zsh (emacs keymap) | `Alt+1` to `Alt+9` | a numeric argument | `Esc`, then the digit |
1477
+ | irssi | `Alt+1` to `Alt+9`; `Alt+W`, `E`, `O` | go to window 1 to 9; to window 12, 13, 19 | `Esc`, then the key |
1478
+ | irssi | `Alt+K`, `P`, `F` | erase completion; page back; forward a word | `Esc`, then the key |
1479
+ | irssi | `Alt+Left`, `Alt+Right`; `Alt+Up`, `Alt+Down` | the window before or after in the split; the split window above or below | its `/window` commands; for `Alt+Left`, `Alt+Right`, switch to Ctrl+Alt |
1480
+ | WeeChat | `Alt+1` to `Alt+9` | go to buffer 1 to 9 | unknown; switch to Ctrl+Alt |
1481
+ | WeeChat | `Alt+K`, `F`, `P`, `Z`, `W` | grab a key; next word; previous highlight; zoom; `Alt+W` starts the window keys | unknown; switch to Ctrl+Alt |
1482
+ | WeeChat | `Alt+Left`, `Alt+Up`; `Alt+Right`, `Alt+Down` | the buffer before; after | `F5`, `F6` |
1483
+ | tmux | nothing without the prefix (the root table binds only the mouse) | after the prefix: `Alt+1` to `Alt+7` the preset layouts, `Alt+O`, `P`, `N` rotate the panes and go to a window with an alert, the Alt arrows resize the pane | its commands (`select-layout`, `resize-pane`), or switch to Ctrl+Alt: `Esc`, then the key is read as Alt only within `escape-time` (below), so not by hand |
1484
+ | Emacs (`emacs -nw`) | `Alt+K`, `E`, `Shift+E`, `Z`, `W`, `F` | kill-sentence, forward-sentence (with Shift too), zap-to-char, kill-ring-save, forward-word | `Esc`, then the letter |
1485
+ | Emacs | `Alt+1` to `Alt+9` | a numeric argument | `Esc`, then the digit |
1486
+ | Emacs | `Alt+Left`, `Alt+Right` | a word left or right | `Esc`, then `b` or `f` |
1487
+
1488
+ Not taken from these programs, by their docs: `Alt+K`, `Z`, `W`, `E` and `R`
1489
+ in Claude Code; the Alt+Shift arrows everywhere above but in WeeChat's
1490
+ cursor mode; `Alt+O` in Emacs since 28; `Alt+A` from every one of them,
1491
+ since the Alt family leaves it alone (the next group is `Alt+Shift+Right`
1492
+ there); and `Alt+R` from every one of them in `oats tui`, which binds no
1493
+ key for the Desktop's `edit-instance` ([Chords](#chords)): Codex's raw
1494
+ output, readline's revert-line, WeeChat's delete-line and Emacs's
1495
+ move-to-window-line keep it here, though the Desktop takes it. On macOS only
1496
+ the arrow rows apply: there `oats tui` takes the ⌥ arrows alone, where the
1497
+ terminal sends them as such ([Chords on macOS](#chords-on-macos)).
1498
+
1499
+ **Inside tmux.** `oats tui` run in a tmux pane gets its keys through tmux,
1500
+ which reads an `Esc` followed by a key within its `escape-time` (10 ms by
1501
+ default in tmux 3.7c) as that key with Alt, and passes it on as one. With
1502
+ a large `escape-time` (some configurations set 500 ms), `Esc` then `k`
1503
+ typed quickly is `Alt+K` and opens the palette, and an `Esc` pressed alone
1504
+ reaches `oats tui` only when that time is over. With the default, as
1505
+ outside tmux, only one keypress is a chord.
1506
+
1507
+ Sources: Claude Code [interactive mode](https://code.claude.com/docs/en/interactive-mode)
1508
+ and [keybindings](https://code.claude.com/docs/en/keybindings); Codex
1509
+ [`keymap.rs`](https://github.com/openai/codex/blob/d6817454d76885e9d0e118bbf82e507aed6f715a/codex-rs/tui/src/keymap.rs)
1510
+ and [`app/input.rs`](https://github.com/openai/codex/blob/d6817454d76885e9d0e118bbf82e507aed6f715a/codex-rs/tui/src/app/input.rs);
1511
+ pi [`keybindings.md`](https://github.com/badlogic/pi-mono/blob/42cb822f1c5d3153069dd0661bfd297424666cf1/packages/coding-agent/docs/keybindings.md)
1512
+ and [`keys.ts`](https://github.com/badlogic/pi-mono/blob/42cb822f1c5d3153069dd0661bfd297424666cf1/packages/tui/src/keys.ts);
1513
+ the [Readline manual](https://tiswww.case.edu/php/chet/readline/readline.html)
1514
+ ("Typing 'ESC f' is equivalent to typing M-f") and readline 8.3's `readline.c`
1515
+ for the Alt arrows; the [zsh line editor](https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html);
1516
+ irssi's [startup HOWTO](https://github.com/irssi/irssi/blob/43f1727ef9fe1cb51d5031ee2dd0e1965217e4cb/docs/startup-HOWTO.txt)
1517
+ and [`gui-readline.c`](https://github.com/irssi/irssi/blob/43f1727ef9fe1cb51d5031ee2dd0e1965217e4cb/src/fe-text/gui-readline.c);
1518
+ the [WeeChat user guide](https://weechat.org/files/doc/weechat/stable/weechat_user.en.html#key_bindings) (4.10.1);
1519
+ [tmux(1)](https://man7.org/linux/man-pages/man1/tmux.1.html); the
1520
+ [Emacs manual](https://www.gnu.org/software/emacs/manual/html_node/emacs/User-Input.html)
1521
+ (ESC as Meta) and its Sentences, Words, Moving Point, Other Kill Commands and
1522
+ Arguments nodes.
1523
+
1524
+ <a id="what-the-option-takes-from-an-agent"></a>
1525
+
1526
+ ### What the Ctrl+Shift family takes from an agent
1527
+
1528
+ With the Ctrl+Shift family, both clients take its seven Ctrl+Shift chords
1529
+ from every focus, an agent's terminal included: the agent never gets them.
1243
1530
 
1244
1531
  - **Of the agents' own keys, that is one:** pi's Ctrl+Shift+P (previous
1245
1532
  model, [pi's keys](https://github.com/earendil-works/pi/blob/26293e74f664c2cfb731b22a653cccf852830e00/packages/coding-agent/docs/keybindings.md#L154))
@@ -1271,7 +1558,7 @@ every focus, an agent's terminal included: the agent never gets them.
1271
1558
  | `1` | the Instances view |
1272
1559
  | `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
1273
1560
  | `3` | [the Capabilities view](#the-capabilities-view); `Esc` or `1` goes back |
1274
- | `w` | opens [the switcher](#the-switcher) |
1561
+ | `w` | gives [the list of workspaces](#the-list-of-workspaces) the focus; `w` there opens [the switcher](#the-switcher) |
1275
1562
  | `Delete` | in the switcher, asks whether to remove the selected row from this computer's list of deployments; `Enter` removes it |
1276
1563
  | `Enter` | in the list of instances, opens the selected agent's terminal in a new [tab](#tabs) beside the sidebar, or shows its tab when it has one, with the focus in it; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
1277
1564
  | `z` | gives the shown terminal the focus and the whole screen |
@@ -1280,7 +1567,7 @@ every focus, an agent's terminal included: the agent never gets them.
1280
1567
  | `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
1281
1568
  | `Ctrl+X` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
1282
1569
  | `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
1283
- | `Ctrl+Alt+K`, `Alt+Shift+Up` and the other [chords](#chords) (`Ctrl+Shift+K` and the rest [with the option](#switch-to-ctrlshift)) | what the leader then a key does, from every focus; the Ctrl+Alt and Ctrl+Shift ones where your terminal sends them. While [the palette](#the-palette) is open, `Alt+Shift+Up` and `Alt+Shift+Down` are its own |
1570
+ | `Alt+K`, `Alt+Shift+Up` and the other [chords](#chords) (`Ctrl+Alt+K` or `Ctrl+Shift+K` and the rest [in the other families](#switch-family)) | what the leader then a key does, from every focus (`Alt+Shift+Up`, `Alt+Shift+Down`: the instance before or after, which the leader has no key for); the Ctrl+Alt and Ctrl+Shift ones where your terminal sends them. While [the palette](#the-palette) is open, `Alt+Shift+Up` and `Alt+Shift+Down` are its own |
1284
1571
  | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
1285
1572
  | `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
1286
1573
  | `N` | spawns another of the selected instance's soul: its preview |
@@ -1303,8 +1590,9 @@ where it is, and the list returns to it at the next key that moves it.
1303
1590
 
1304
1591
  The help screen is generated from the table the program acts on, so it
1305
1592
  always lists the keys that work, the leader's among them, the
1306
- [chords](#chords) (first of all while your terminal confirms the kitty
1307
- keyboard protocol), the palette's and the spawn prompt's, with the
1593
+ [chords](#chords) (first of all while every chord of the family in force
1594
+ is read: always in the Alt family, and in the others while your terminal
1595
+ confirms the kitty keyboard protocol), the palette's and the spawn prompt's, with the
1308
1596
  marks and with what this version does not do. Its top row has the time of the read and the count of withheld rows
1309
1597
  ([What it shows](#what-it-shows)). The movement keys scroll it. While
1310
1598
  a terminal has the focus the table's keys are the agent's: the leader and
@@ -1331,37 +1619,35 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
1331
1619
  |---|---|
1332
1620
  | `k` or `Space` | opens [the palette](#the-palette) |
1333
1621
  | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
1334
- | `Up`, `Down` | opens the terminal of the instance before or after, in the list as it is drawn, the focus in it: from the shown terminal's instance, or from the selection when none is open. It shows the instance's tab when it has one, else opens a new [tab](#tabs). Rows that cannot be opened are passed over, and the list does not wrap |
1622
+ | `Up`, `Down` | opens the workspace before or after the open one, in [the list of workspaces](#the-list-of-workspaces) as it is drawn (the chords `Alt+Up`, `Alt+Down`). Every row opens, and the list does not wrap. The terminal of the instance before or after is `Alt+Shift+Up`, `Alt+Shift+Down` ([Chords](#chords)) |
1335
1623
  | `Left`, `Right` | shows the tab before or after the shown one; the tab bar does not wrap, and the focus stays where it was |
1336
1624
  | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
1337
1625
  | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
1338
1626
  | `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
1339
1627
  | `Tab` | goes to the other group's terminal (or to the other group, when it is empty); from the list, to the focused group's |
1628
+ | `Shift+Tab` | goes to the previous group, as `Tab` goes to the next: with two groups at most, the same as `Tab` |
1340
1629
  | `m` | with two groups, moves the shown tab to the other group, and goes there |
1341
1630
  | `x` | closes the focused group while it is empty |
1342
1631
  | `X`, `R`, `S`, `D` | stop, restart, start, retire, [after a confirmation](#stopping-starting-restarting-and-retiring): from a terminal's focus on that terminal's instance, which has the focus again when the confirmation closes |
1343
1632
  | `n`, `N` | [spawns an agent](#spawning-an-agent); `N` of the shown terminal's soul from its focus |
1344
1633
  | `/` | the filter |
1345
- | `o` | [the switcher](#the-switcher) |
1634
+ | `o` | gives [the list of workspaces](#the-list-of-workspaces) the focus |
1346
1635
  | `?` | the help |
1347
1636
  | `Esc` | gives the list the focus |
1348
- | the leader again | types the leader into the terminal that has the focus, which keeps it; with the list focused, only closes the hint |
1349
-
1350
- - **While the leader waits** for its key the cheat sheet's rows are its
1351
- hint: `Ctrl+X then`, then a row per key, `Esc the list` last. It names
1352
- these keys but `n` and `N` (`z` and `w` only while a terminal is open,
1353
- `Left` and `Right` only with two tabs or more, `|` and `-` while the
1354
- panel has one group, `Tab` with two, then `m` while the focused group
1355
- shows a tab or `x` while it is empty, and the leader again while a
1356
- terminal has the focus). On a short screen it gives up rows before its
1357
- last. It waits
1358
- with no time limit. A key not in the table cancels it and is dropped:
1359
- nothing is typed.
1637
+ | the leader again | types the leader into the terminal that has the focus, which keeps it; with the list focused, only cancels the leader |
1638
+
1639
+ - **While the leader waits** for its key nothing on the screen changes:
1640
+ the cheat sheet stays as it was, and the help (`?`) lists the whole
1641
+ table above. It waits with no time limit. A key not in the table
1642
+ cancels it and is dropped: nothing is typed.
1360
1643
  - **Only a key in a later read counts.** A key that came in the same read of
1361
1644
  input as the leader cancels it and is dropped, with the rest of that
1362
- read, so a paste can never run a command. In a terminal the bytes before
1363
- the leader in that read still go to the agent. A leader inside a
1364
- bracketed paste is pasted text.
1645
+ read, so a paste can never run a command. The line under the list of workspaces says
1646
+ so, until the next key of any kind (one typed to an agent too) or a resize:
1647
+ `Ctrl+X and the next key came in one read, so nothing ran: press them
1648
+ one after the other.` In a terminal the bytes before the leader in that
1649
+ read still go to the agent. A leader inside a bracketed paste is pasted
1650
+ text.
1365
1651
  - **`Ctrl+X` is one byte.** Without the kitty keyboard protocol
1366
1652
  ([Chords](#chords)) every terminal sends it as `0x18`, which no read
1367
1653
  splits and nothing has to time; under the protocol it is `CSI 120;5u`,
@@ -1373,6 +1659,9 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
1373
1659
  `Esc` then `0x18` in one read is `Ctrl+Alt+X`, and goes to the agent.
1374
1660
  - **An Alt leader is one keypress only.** A leader `tui.json` names with
1375
1661
  `M-`, such as `M-o` (`Alt+O`), is sent by a terminal as `Esc` then `o`.
1662
+ A leader that is a chord of the family in force is the leader, and that
1663
+ chord is not bound: with `M-o`, `Alt+O` is the leader, and the leader
1664
+ then `o` gives the list of workspaces the focus.
1376
1665
  Those bytes count as the leader when they arrive in one read, or split
1377
1666
  across reads within 10 ms. An `Esc` then `o` typed as two keys reaches
1378
1667
  the agent unchanged: in vim that is "leave insert mode, open a line".
@@ -1395,33 +1684,76 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
1395
1684
  ### Chords
1396
1685
 
1397
1686
  A chord does in one keypress what the leader then a key does, from every
1398
- focus, an agent's terminal too, and never reaches the agent. The OATS
1687
+ focus, an agent's terminal too, and never reaches the agent. One pair has
1688
+ no leader key: `Alt+Shift+Up` and `Alt+Shift+Down` open the terminal of
1689
+ the instance before or after, in the list as it is drawn, the focus in it
1690
+ (from the shown terminal's instance, or from the selection when none is
1691
+ open; its tab when it has one, else a new [tab](#tabs); rows that cannot be
1692
+ opened are passed over, and the list does not wrap), since the leader's
1693
+ `Up` and `Down` move between workspaces. On macOS, where that pair holds ⌘
1694
+ (`⌥⌘↑`, `⌥⌘↓`), which a terminal never passes on, the list's `Up` or
1695
+ `Down` then `Enter` does it. The OATS
1399
1696
  Desktop has the same chords (`CHORDS` in `packages/client/keymap.mjs`, which
1400
1697
  both read; the TUI keeps no copy). The leader stays the key that always
1401
1698
  works, and the one for help, the views and the acts (stop, restart, start,
1402
1699
  retire), which have no chord.
1403
1700
 
1404
- Every chord, in both families, with what it does and the leader's key for
1701
+ Every chord, in every family, with what it does and the leader's key for
1405
1702
  it, is in [Every action's keys](#every-actions-keys). While the palette is
1406
1703
  open, `Alt+Shift+Up` and `Alt+Shift+Down` move between its groups instead
1407
1704
  ([The palette](#the-palette)).
1408
1705
 
1409
- `CHORDS` also holds the Desktop's `edit-instance` (`Ctrl+Alt+R`, its name and
1706
+ `CHORDS` also holds the Desktop's `edit-instance` (`Alt+R`, its name and
1410
1707
  colour dialog). The TUI has no such action, so it binds no key for it and
1411
- `Ctrl+Alt+R` stays the agent's.
1412
-
1413
- They are one family: Ctrl+Alt with a letter or a digit acts, and Alt+Shift
1414
- with the leader's arrow moves. No terminal in the table below takes them by
1415
- default, and no agent (Claude Code, Codex, pi) reads them. Ctrl+Shift with a
1416
- letter, the obvious family, is mostly the terminals' own: kitty binds 22 of
1417
- those letters, Ghostty 13, and foot, GNOME Terminal, WezTerm, Konsole and
1418
- Windows Terminal their own. So it is the option, for the terminals that
1419
- leave the seven letters alone ([Which family for my
1420
- terminal](#which-family-for-my-terminal)). With the option a row's
1421
- Ctrl+Shift key replaces its Ctrl+Alt key, which then reaches the agent as
1422
- it would without the TUI. On macOS the TUI has no chords: the Desktop's
1423
- hold ⌘, which a terminal never passes to a program.
1424
-
1708
+ `Alt+R` stays the agent's.
1709
+
1710
+ There are three families, one choice per user for both clients
1711
+ ([Switch family](#switch-family)):
1712
+
1713
+ - **Alt, the default.** Alt with a letter or a digit acts, Alt with an
1714
+ arrow moves between tabs and workspaces, and Alt+Shift with an arrow
1715
+ between groups and instances. It reads in every terminal, with no
1716
+ protocol, and takes keys that programs in a terminal read
1717
+ ([What the Alt family takes](#what-the-alt-family-takes)).
1718
+ - **Ctrl+Alt, for whoever needs Alt in their programs.** The default
1719
+ before this version, with its keys: Ctrl+Alt with a letter or a digit
1720
+ acts, and Alt+Shift with an arrow moves between tabs and instances. It
1721
+ leaves Alt alone, the Alt arrows included: the workspace moves have no
1722
+ chord here, so `Alt+Up` and `Alt+Down` reach the program (Codex's edit
1723
+ the queued message, pi's restore the queued messages), and the leader's
1724
+ `Up` and `Down` move between workspaces. No terminal in [the
1725
+ matrix](#which-terminals-let-the-chords-through) takes its chords by
1726
+ default, and no agent (Claude Code, Codex, pi) reads them. It needs the
1727
+ kitty keyboard protocol.
1728
+ - **Ctrl+Shift, for a terminal that passes Ctrl+Shift apart from Ctrl**
1729
+ (foot, Alacritty). Ctrl+Shift with a letter, the obvious family, is
1730
+ mostly the terminals' own: kitty binds 22 of those letters, Ghostty 13,
1731
+ and foot, GNOME Terminal, WezTerm, Konsole and Windows Terminal their
1732
+ own. So seven of the Ctrl+Alt family's chords move to Ctrl+Shift, for the
1733
+ terminals that leave those letters alone ([Which family for my
1734
+ terminal](#which-family-for-my-terminal)), and the others keep their
1735
+ Ctrl+Alt key. It needs the protocol too.
1736
+
1737
+ A chord of another family is no chord: in the Alt family `Ctrl+Alt+K`
1738
+ reaches the agent as it would without the TUI, and in the Ctrl+Alt family
1739
+ `Alt+K` does. On macOS the TUI has the ⌥ arrows alone ([Chords on
1740
+ macOS](#chords-on-macos)): the Desktop's other chords hold ⌘, which a
1741
+ terminal never passes to a program.
1742
+
1743
+ - **The Alt family in every terminal.** A terminal sends `Alt` with a
1744
+ letter or a digit as `Esc` then the key (`Alt+K` is `ESC k`, and
1745
+ `Alt+Shift+E` is `ESC E`), with the protocol or without it, and the
1746
+ arrows as sequences of their own (`CSI 1;3A` for `Alt+Up`, `CSI 1;4A` for
1747
+ `Alt+Shift+Up`). Under the protocol each is one report of its own. In the
1748
+ list a lone `Esc` waits 50 ms for a key after it, as it always has. In a
1749
+ terminal `Esc` and the key are one chord when they come in one read, or
1750
+ split across reads within 10 ms, as an [Alt leader](#the-leader) is: an
1751
+ `Esc` then `k` typed as two keys reaches the agent unchanged, so a
1752
+ program that reads `Esc` as Meta, as the shell does, still gets `Alt+K`
1753
+ that way. Over a slow link two keys typed apart can arrive in one read
1754
+ and act as the chord, and one chord can arrive split and reach the agent
1755
+ as `Esc` and the key. Inside tmux, its `escape-time` decides ([What the
1756
+ Alt family takes](#what-the-alt-family-takes)).
1425
1757
  - **The Ctrl+Alt and Ctrl+Shift chords only where the terminal says it
1426
1758
  can.** Without the kitty keyboard protocol a terminal sends `Ctrl+Alt+K`
1427
1759
  as `Esc` then `Ctrl+K`, the same bytes as those two keys typed for the
@@ -1429,45 +1761,51 @@ hold ⌘, which a terminal never passes to a program.
1429
1761
  it takes the terminal, `oats tui` asks for the protocol with flags 1 and 4
1430
1762
  (`CSI > 5 u`) and asks the terminal which flags it has (`CSI ? u`). Only
1431
1763
  when the answer holds flag 1 does it read the protocol and take the
1432
- chords of its family. With no answer within 2 seconds, or one without flag 1,
1433
- it pops the protocol, and the rest of the run is as without it. The
1764
+ chords of those families. With no answer within 2 seconds, or one without flag 1,
1765
+ it pops the protocol, and the rest of the run is as without it: of those
1766
+ families' chords only the arrows are taken (the Alt+Shift arrows). The
1434
1767
  answer may come split and late over a slow link, so until it comes (at
1435
1768
  most those 2 seconds) an `Esc` pressed on its own may wait for the next
1436
1769
  key or for the wait's end, as it may begin the answer.
1437
- - **The Alt+Shift arrows everywhere.** Each sends a sequence of its own,
1438
- with the protocol or without it (`CSI 1;4A` for `Alt+Shift+Up`), so the
1439
- TUI takes them in every terminal. `Ctrl+Alt+Shift` with an arrow is not
1440
- one of them.
1441
- - **The help and the cheat sheet lead with the chords** while the terminal
1442
- confirms the protocol: one row per chord, then the leader and its key
1443
- ("or `Ctrl+X` then `k`"), and the leader's own section after them. Without
1444
- the protocol the leader leads, and only the Alt+Shift arrows are listed
1445
- as chords. The help's chords open with the family in force
1446
- ([Switch to Ctrl+Shift](#switch-to-ctrlshift)). The cheat sheet names chords while an agent's terminal has the
1447
- focus; the list's names its own keys, which need no modifier.
1770
+ - **The help and the cheat sheet lead with the chords** while every chord
1771
+ of the family in force is read: always in the Alt family and on macOS,
1772
+ and in the others while the terminal confirms the protocol. Then the help has one
1773
+ row per chord, then the leader and its key ("or `Ctrl+X` then `k`"), and
1774
+ the leader's own section after them; a pair whose keys share their
1775
+ modifiers is one row (`Alt+Shift+Up/Down`), and `Ctrl+Alt+Shift+A` and
1776
+ `Ctrl+Alt+A` are a row each. Otherwise the leader leads, and only the
1777
+ chords read are listed. The help's chords open with the family in force
1778
+ ([Switch family](#switch-family)). The cheat sheet names chords while an
1779
+ agent's terminal has the focus; the list's names its own keys, which need
1780
+ no modifier.
1448
1781
  - **Your terminal may take some first** ([the matrix](#which-terminals-let-the-chords-through)).
1449
- Windows Terminal takes `Ctrl+Alt+1` to `Ctrl+Alt+9` for its own tabs, and
1450
- the Alt+Shift arrows while its panes are split. GNOME Terminal and the
1782
+ GNOME Terminal and Konsole take `Alt+1` to `Alt+9` for their own tabs
1783
+ while they have two or more, and Ghostty when the tab changes. Windows
1784
+ Terminal takes the Alt and Alt+Shift arrows while its panes are split,
1785
+ and `Ctrl+Alt+1` to `Ctrl+Alt+9` for its own tabs. GNOME Terminal and the
1451
1786
  other VTE terminals, Konsole before 26.08, and WezTerm unless
1452
- `enable_kitty_keyboard` is set have no protocol: there only the Alt+Shift
1453
- arrows reach `oats tui`. The leader works in every terminal.
1787
+ `enable_kitty_keyboard` is set have no protocol: there the Ctrl+Alt and
1788
+ Ctrl+Shift families' chords but their arrows do not reach `oats tui`.
1789
+ The leader works in every terminal.
1454
1790
  - **A character typed with AltGr stays a character.** On Windows `AltGr` is
1455
1791
  `Ctrl+Alt`: on a Spanish layout `Ctrl+Alt+E` types `€` and `Ctrl+Alt+2`
1456
1792
  `@`, on a Polish one `Ctrl+Alt+A` types `ą`. A key that arrives as text is
1457
1793
  never a chord: on such a layout those chords are the layout's, and the
1458
- leader still does what they do. On Linux and macOS `AltGr` and Option are
1459
- keys of their own.
1794
+ leader still does what they do. On Linux `AltGr` is a key of its own: a
1795
+ character it types reaches the TUI as that character, never as `Esc`
1796
+ then a key, so it is never an Alt chord either. On macOS Option is a key
1797
+ of its own.
1460
1798
  - **Every other key reads as it does without the protocol.** `Ctrl+Shift+L`
1461
1799
  is `Ctrl+L`, `Ctrl+Enter` is `Enter`, and so on: the protocol only adds
1462
- the chords of the family in force, tells an Alt leader such as `Alt+O`
1463
- from `Esc` then `o` exactly, and tells `Ctrl+Shift+X` from the leader
1464
- `Ctrl+X` ([The leader](#the-leader)). Under the default family the seven
1465
- Ctrl+Shift letters of the option are such keys too: `Ctrl+Shift+D` is
1466
- `Ctrl+D`.
1800
+ the Ctrl+Alt and Ctrl+Shift chords of the family in force, tells an Alt
1801
+ chord or an Alt leader such as `Alt+O` from `Esc` then `o` exactly, and
1802
+ tells `Ctrl+Shift+X` from the leader `Ctrl+X` ([The leader](#the-leader)).
1803
+ Outside the Ctrl+Shift family its seven Ctrl+Shift letters are such keys
1804
+ too: `Ctrl+Shift+D` is `Ctrl+D`.
1467
1805
  - **A Ctrl+Shift chord is read from the protocol alone,** from a report
1468
1806
  that holds Shift, never from the byte a terminal sends without it:
1469
- `Ctrl+D` (end of input) and `Enter` (`Ctrl+M`) stay what they are, with
1470
- the option on too.
1807
+ `Ctrl+D` (end of input) and `Enter` (`Ctrl+M`) stay what they are, in
1808
+ the Ctrl+Shift family too.
1471
1809
  - **An agent gets what it gets without the protocol.** Every key typed
1472
1810
  into an agent's terminal is turned back into the bytes the same key sends
1473
1811
  without it, the legacy encoding of xterm and the terminals that follow it:
@@ -1489,38 +1827,112 @@ hold ⌘, which a terminal never passes to a program.
1489
1827
  terminal: the shell at a suspend is the only one `oats tui` ever gives
1490
1828
  it to.
1491
1829
 
1830
+ #### Chords on macOS
1831
+
1832
+ On macOS `oats tui` binds the chords of `CHORDS` whose key holds no ⌘, ⌥
1833
+ with an arrow (the product owner's call, 2026-10-23): `⌥←` and `⌥→` the tab before or
1834
+ after, `⌥⇧←` and `⌥⇧→` the group before or after, `⌥↑` and `⌥↓` the
1835
+ workspace before or after. Its help and cheat sheet say them `Alt+Left` and
1836
+ so on, and lead with them. The other chords hold ⌘ (`⌘K`, `⌥⌘1` to `⌥⌘9`,
1837
+ `⌥⌘↑`), which a terminal never passes to a program, so the TUI binds none
1838
+ of them. The leader does the actions it has a key for (`Ctrl+X` then `k`
1839
+ for the palette, for instance); the list's `Up` or `Down`, then `Enter`,
1840
+ steps between instances; and no key goes to a tab by its place, so no tab
1841
+ carries a number ([Tabs](#tabs)). ⌥ with a letter or a digit
1842
+ types a character on many layouts (`⌥2` is `@` on a Spanish one), so none
1843
+ of them is a chord. There is no family to choose: keys.json's `chords` is
1844
+ not read there.
1845
+
1846
+ A chord comes only where the terminal sends ⌥ with an arrow as its xterm
1847
+ sequence, `CSI 1;3` (`Esc [1;3D` for `⌥←`), and ⌥⇧ with one as `CSI 1;4`.
1848
+ Where it comes, the TUI takes it from the program in the terminal, as on
1849
+ Linux; where it does not, the bytes reach the program as before (`Esc b`
1850
+ and `Esc f` move a shell by word), and the leader does what the chord
1851
+ would: then `Left` or `Right` for the tabs, `Shift+Tab` or `Tab` for the
1852
+ groups, `Up` or `Down` for the workspaces. What each terminal sends by
1853
+ default, read from its source or its documentation on 2026-10-23 (their
1854
+ main branches):
1855
+
1856
+ | Terminal | `⌥←`, `⌥→` | `⌥↑`, `⌥↓` | `⌥⇧←`, `⌥⇧→` | For the chords |
1857
+ |---|---|---|---|---|
1858
+ | Terminal.app | `Esc b`, `Esc f`, the shell's word moves ([ncurses' `nsterm` entry][nsterm], [Apple][apple-keys]) | unknown | unknown | unknown: [Apple][apple-kbd] does not say whether "Use Option as Meta key" or the profile's key list changes what an arrow sends |
1859
+ | iTerm2 | the chord | the chord | the chord | the default ([its profile][iterm-profile], [the encoder][iterm-encoder]: "Treat ⌥ as Alt for special keys"); its presets "Natural Text Editing" and "Terminal.app Compatibility" ([presets][iterm-presets]) map `⌥←`, `⌥→` (the second `⌥↑`, `⌥↓` too) to the shell's moves instead |
1860
+ | Ghostty | `Esc b`, `Esc f`, its own default keybinds ([config][ghostty-binds], [#3106][ghostty-3106]) | the chord ([encoder][ghostty-encoder]) | the chord | `keybind = alt+left=unbind` and `keybind = alt+right=unbind` |
1861
+ | kitty | the chord ([Option is Alt][kitty-option], [encoder][kitty-encoder]) | the chord | the chord | the default |
1862
+ | WezTerm | the chord ([config][wezterm-config], [encoder][wezterm-encoder]) | the chord | the chord | the default |
1863
+ | Alacritty | the chord ([Alt on named keys][alacritty-keys]) | the chord | the chord | the default |
1864
+ | Warp | the chord in a full-screen program, as `oats tui` is ([encoder][warp-encoder], [binds][warp-binds]) | its own default bind (bookmarks); unknown whether it takes them from a full-screen program | the chord | its keybinding editor |
1865
+ | VS Code's terminal | `Esc b`, `Esc f` ([its default bindings][vscode-binds]) | `CSI 1;5A`, `CSI 1;5B`, which is `Ctrl+Up`, `Ctrl+Down`: no chord | the chord | remove its `workbench.action.terminal.sendSequence` bindings of `alt+left`, `alt+right`, `alt+up` and `alt+down` in keybindings.json |
1866
+
1867
+ iTerm2's, WezTerm's and Warp's rows were read from their code, not run.
1868
+ Neither "Use Option as Meta key" (Terminal.app) nor Option as Alt or Meta in
1869
+ the others (iTerm2's Left/Right Option key, Ghostty's
1870
+ `macos-option-as-alt`, kitty's `macos_option_as_alt`, Alacritty's
1871
+ `option_as_alt`, VS Code's `terminal.integrated.macOptionIsMeta`) changes
1872
+ what the arrows send, by those terminals' code; for Terminal.app it is
1873
+ unknown. The TUI reads no other bytes as these chords: `Esc b` and `Esc f`
1874
+ are readline's word moves, and `CSI 1;5A` is `Ctrl+Up`.
1875
+
1876
+ [nsterm]: https://github.com/ThomasDickey/ncurses-snapshots/blob/master/misc/terminfo.src
1877
+ [apple-keys]: https://support.apple.com/guide/terminal/keyboard-shortcuts-trmlshtcts/mac
1878
+ [apple-kbd]: https://support.apple.com/guide/terminal/profiles-keyboard-settings-trmlkbrd/mac
1879
+ [iterm-profile]: https://github.com/gnachman/iTerm2/blob/7f4ff739721f95d0b93003d8701c4523a7edf261/sources/Settings/iTermProfilePreferences.m#L1254
1880
+ [iterm-encoder]: https://github.com/gnachman/iTerm2/blob/7f4ff739721f95d0b93003d8701c4523a7edf261/sources/VT100/VT100Output.m#L1242
1881
+ [iterm-presets]: https://github.com/gnachman/iTerm2/blob/7f4ff739721f95d0b93003d8701c4523a7edf261/plists/PresetKeyMappings.plist#L127
1882
+ [ghostty-binds]: https://github.com/ghostty-org/ghostty/blob/08a9518340e19487bd5fdf96963583fb32f0c41f/src/config/Config.zig#L7383
1883
+ [ghostty-3106]: https://github.com/ghostty-org/ghostty/issues/3106
1884
+ [ghostty-encoder]: https://github.com/ghostty-org/ghostty/blob/08a9518340e19487bd5fdf96963583fb32f0c41f/src/input/function_keys.zig#L81
1885
+ [kitty-option]: https://github.com/kovidgoyal/kitty/blob/34eda431940fc8d66ffd0ada7d4a6451fdbd6699/kitty/options/definition.py#L3499
1886
+ [kitty-encoder]: https://github.com/kovidgoyal/kitty/blob/34eda431940fc8d66ffd0ada7d4a6451fdbd6699/kitty/key_encoding.c#L160
1887
+ [wezterm-config]: https://github.com/wezterm/wezterm/blob/e2a98e1b8af156988ad0ac778658ac27b60a55fb/config/src/config.rs#L461
1888
+ [wezterm-encoder]: https://github.com/wezterm/wezterm/blob/e2a98e1b8af156988ad0ac778658ac27b60a55fb/termwiz/src/input.rs#L421
1889
+ [alacritty-keys]: https://github.com/alacritty/alacritty/blob/542147067dd016fc5f49120ef0ba605a98a4e3a7/alacritty/src/input/keyboard.rs#L105
1890
+ [warp-encoder]: https://github.com/warpdotdev/warp/blob/1e6c3ae465d6a925a9b97ae03877aaadd159b8f1/crates/warp_terminal/src/model/escape_sequences.rs#L526
1891
+ [warp-binds]: https://github.com/warpdotdev/warp/blob/1e6c3ae465d6a925a9b97ae03877aaadd159b8f1/app/src/terminal/view/init.rs#L405
1892
+ [vscode-binds]: https://github.com/microsoft/vscode/blob/b04b50a28f70d834c4d039deb1d52dd3f9242293/src/vs/workbench/contrib/terminalContrib/sendSequence/browser/terminal.sendSequence.contribution.ts#L181
1893
+
1492
1894
  #### Which terminals let the chords through
1493
1895
 
1494
1896
  Each terminal's documented default key bindings, read from its source or
1495
1897
  manual at the release named. `✗` is a chord the terminal takes for itself
1496
1898
  by default, `~` one it takes only in a state it names, `·` one it passes on.
1497
1899
  WT is Windows Terminal; iTerm2 and Terminal.app are on macOS, where the TUI
1498
- has no chords (above) and the column is for reference.
1900
+ binds the ⌥ arrows alone ([Chords on macOS](#chords-on-macos)) and the
1901
+ other rows are for reference.
1499
1902
 
1500
1903
  | Chord | foot | kitty | Ghostty | Alacritty | GNOME Terminal | WezTerm | Konsole | WT | iTerm2 | Terminal.app |
1501
1904
  |---|---|---|---|---|---|---|---|---|---|---|
1905
+ | `Alt+K` `P` `O` `Z` `W` `E` `F`, `Alt+Shift+E` | · | · | · | · | · | · | · | · | – | – |
1906
+ | `Alt+1` to `9` | · | · | ~ on Linux its tabs, when the tab changes | · | ~ its tabs, with two or more | · | ~ its tabs, with two or more | · | – | – |
1907
+ | `Alt` arrows | · | · | · | · | · | · | · | ~ pane focus, passed on with one pane | · | ✗ `⌥←` `⌥→`, sent as the shell's word moves; `⌥↑` `⌥↓` unknown ([Chords on macOS](#chords-on-macos)) |
1502
1908
  | `Ctrl+Alt+K` `P` `O` `Z` `W` `E` `A` `F` | · | · | · | · | · | · | · | · | · | · |
1503
1909
  | `Ctrl+Alt+Shift+E` | · | · | · | · | · | · | · | · | · | · |
1504
1910
  | `Ctrl+Alt+1` to `9` | · | · | · | · | · | · | · | ✗ its tabs | · | · |
1505
1911
  | `Alt+Shift+` arrows | · | · | · | · | · | · | · | ~ pane resize, passed on with one pane | · | · |
1506
- | the option's `Ctrl+Shift+K` `P` `S` `M` `W` `E` `D` | · | ✗ `K` `P` `S` `W` `E` | ✗ `P` `W` `E` | · | ✗ `W` | ✗ `K` `P` `M` `W` | ✗ all seven | ✗ `K` `P` `M` `W` `D` | – | – |
1507
- | kitty protocol, flags 1 and 4 | yes, since 1.10.3 | yes | yes | yes, since 0.13 | no (VTE has none) | only with `enable_kitty_keyboard` | yes, since 26.08 | yes, since 1.25 | yes | no |
1912
+ | the Ctrl+Shift family's `Ctrl+Shift+K` `P` `S` `M` `W` `E` `D` | · | ✗ `K` `P` `S` `W` `E` | ✗ `P` `W` `E` | · | ✗ `W` | ✗ `K` `P` `M` `W` | ✗ all seven | ✗ `K` `P` `M` `W` `D` | – | – |
1913
+ | kitty protocol, flags 1 and 4 (for the Ctrl+Alt and Ctrl+Shift families) | yes, since 1.10.3 | yes | yes | yes, since 0.13 | no (VTE has none) | only with `enable_kitty_keyboard` | yes, since 26.08 | yes, since 1.25 | yes | no |
1508
1914
  | Release read | 1.28.0 | 0.49.2 | 1.3.1 | 0.17.0 | 3.60.0 (VTE 0.84.1) | 20240203 | 26.08.2 | 1.25.2733 | 3.7 | macOS 15 |
1509
1915
 
1510
- Where a terminal has no protocol, its cells say only what it takes: the
1511
- chord does not reach the TUI there anyway. macOS has no Ctrl+Shift option,
1512
- hence `–`. What the
1916
+ Where a terminal has no protocol, its cells for the Ctrl+Alt and
1917
+ Ctrl+Shift chords say only what it takes: those chords do not reach the
1918
+ TUI there anyway. On macOS the Alt family is not bound and there is no
1919
+ choice of family, hence `–`: a macOS terminal sends Option with a letter
1920
+ as a character unless it is set to send Option as Meta, and its arrows
1921
+ are in [Chords on macOS](#chords-on-macos). The three Alt rows were read from each terminal's
1922
+ source and manual as they stood on 2026-10-23 (their main branches), not
1923
+ at the releases in the last row. What the
1513
1924
  terminals take besides, near these chords:
1514
1925
 
1515
1926
  - Konsole: `Ctrl+Alt+S`, `N`, `M`, `U`, `H`, `G`, `I`, `0`, `[`, `]`, `\`
1516
1927
  and `,`.
1517
- - Windows Terminal: `Ctrl+Alt+,`, `Ctrl+Alt+Left`, and `Alt` with an arrow
1518
- (pane focus).
1928
+ - Windows Terminal: `Ctrl+Alt+,` and `Ctrl+Alt+Left`.
1519
1929
  - kitty: `Ctrl+Shift+Alt+T`. Ghostty: `Ctrl+Shift+Alt+J`, and `Ctrl+Alt`
1520
1930
  with an arrow (split focus). WezTerm: `Ctrl+Shift+Alt` with an arrow,
1521
1931
  `'` and `5`.
1522
1932
 
1523
- The desktops' global keys come before any terminal's:
1933
+ The desktops' global keys come before any terminal's. They were read
1934
+ for the Ctrl+Alt and Ctrl+Shift chords; "the chords above" in the last
1935
+ column is those, and the Alt family's were not read against them:
1524
1936
 
1525
1937
  | Desktop (release read) | Takes, near the chords | Takes none of |
1526
1938
  |---|---|---|
@@ -1596,10 +2008,12 @@ TUI reads the keys. The help lists its keys under The palette.
1596
2008
  that can be opened is not listed.
1597
2009
  - **The group last used comes first,** as in the Desktop's palette, and so
1598
2010
  does the cluster, the root and the child: the one with the instance opened
1599
- or shown most recently in this run first, then the list's order (the
1600
- sidebar keeps its own order). When the first instance is the shown tab's,
1601
- the palette opens on the instance shown before it, wherever its group puts
1602
- it (the second instance, when none was shown before): `Enter` goes back to
2011
+ or shown most recently in this workspace in this run first, then the
2012
+ list's order (the sidebar keeps its own order). Each workspace keeps its
2013
+ own recency, its last 50 instances, so working in another leaves it as it
2014
+ was. When the first instance is the shown tab's, the palette opens on the
2015
+ instance shown before it in this workspace, wherever its group puts it
2016
+ (the second instance, when none was shown before): `Enter` goes back to
1603
2017
  that terminal.
1604
2018
  - **An instance's row** has its state mark, its name, for another machine
1605
2019
  `on <machine>`, and, dim, its siblings as the detail names them
@@ -1632,7 +2046,9 @@ TUI reads the keys. The help lists its keys under The palette.
1632
2046
  row. While the palette is open these keys are its own: they win over the
1633
2047
  chords `Alt+Shift+Up` and `Alt+Shift+Down` ([Chords](#chords)), so they
1634
2048
  open no agent and leave the palette open, with or without the kitty
1635
- keyboard protocol. The leader then `Up` or `Down` still opens one. The
2049
+ keyboard protocol. The leader then `Up` or `Down`, or `Alt+Up` or
2050
+ `Alt+Down` where they are chords, closes it and opens the workspace
2051
+ before or after. The
1636
2052
  Desktop's palette has the same pair (`PALETTE_KEYS` in
1637
2053
  `packages/client/keymap.mjs`, which both read).
1638
2054
  - **On macOS there is no group key:** the Desktop's hold `⌘`, which a
@@ -1676,7 +2092,7 @@ deployments). `XDG_CONFIG_HOME` is not read for it. It never writes the file,
1676
2092
  except to [move it](#the-move-from-configoats) from where earlier versions
1677
2093
  read it. With no file the keys are the ones above. Which chord family it
1678
2094
  binds is not here: it is `keys.json`, beside it, which the Desktop shares
1679
- ([Switch to Ctrl+Shift](#switch-to-ctrlshift)).
2095
+ ([Switch family](#switch-family)).
1680
2096
 
1681
2097
  ```json
1682
2098
  { "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
@@ -2035,8 +2451,8 @@ version:
2035
2451
  - **A row of another machine shows what its host reported at the last
2036
2452
  read,** not what is true at this moment. The time of that read is on the
2037
2453
  machine's heading when it is not the time of this machine's read. A view
2038
- of one machine has no heading: there the title names the machine
2039
- (`on garnet`) and the help's top row carries the time.
2454
+ of one machine has no heading: there the detail's `machine` line names the
2455
+ machine and the help's top row carries the time.
2040
2456
  - The Souls and Capabilities views list a workspace of this machine's
2041
2457
  souls and capabilities: both are this machine's.
2042
2458
  - There is no sorting and no mouse, and a deployment's heading cannot be
@@ -2144,7 +2560,11 @@ alone. The next run removes the directory that is left, with its `tmux`,
2144
2560
  included) and attributes: those are the agent's. With `NO_COLOR` set and
2145
2561
  not empty it uses no colour at all, the agent's included; the agent's
2146
2562
  bold, underline, reverse and the like stay. Nothing is told by colour
2147
- alone.
2563
+ alone. **Yellow says needs input, and only that:** the `!` in place of a
2564
+ row's state mark and the dot in the list of workspaces. A state unknown,
2565
+ `?`, is dim in your terminal's foreground, and a warning (a failed read,
2566
+ `Can't spawn here`, `· 1 on an older version`) is bold red, and a soul's
2567
+ `sand` is in your terminal's foreground ([What it shows](#what-it-shows)).
2148
2568
  - It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
2149
2569
  `LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
2150
2570
  no emoji. When the locale is not UTF-8, a character outside ASCII in text