@awebai/oats 0.66.0 → 0.68.0
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.
- package/bin/oats.mjs +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +96 -42
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
|
|
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,25 +95,25 @@ runs.
|
|
|
95
95
|
## What it shows
|
|
96
96
|
|
|
97
97
|
```
|
|
98
|
-
|
|
98
|
+
acme-platform │ dev
|
|
99
99
|
│ soul dev
|
|
100
100
|
Instances 1 │ state running
|
|
101
101
|
> ● dev │ harness claude, claude-opus-5-5 (so…
|
|
102
102
|
│ work worktree, agents/dev
|
|
103
|
-
● reviewer
|
|
103
|
+
● reviewer Needs input │ team eng
|
|
104
104
|
○ helper │ started 11:00
|
|
105
105
|
──────────────────────────────────────│ home …oy/agents/dev/instances/dev
|
|
106
106
|
Souls 2 │
|
|
107
107
|
Capabilities 3 │
|
|
108
108
|
──────────────────────────────────────│
|
|
109
|
-
|
|
109
|
+
Ctrl+X commands │
|
|
110
110
|
Ctrl+K palette │
|
|
111
111
|
Enter open │
|
|
112
112
|
n spawn │
|
|
113
|
+
w workspaces │
|
|
113
114
|
? help │
|
|
114
115
|
q quit │
|
|
115
116
|
│
|
|
116
|
-
│
|
|
117
117
|
```
|
|
118
118
|
|
|
119
119
|
The screen is the sidebar on the left and the main area on the right, with
|
|
@@ -121,40 +121,43 @@ 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
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
- **Under the
|
|
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
|
-
|
|
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).
|
|
145
146
|
- **The cheat sheet** comes last, under a rule: a few keys, one per row,
|
|
146
|
-
the key in bold and what it does beside it. Its first row is
|
|
147
|
-
leader, `
|
|
147
|
+
the key in bold and what it does beside it. Its first row is the
|
|
148
|
+
leader, `Ctrl+X commands`, which reaches every action (but while a
|
|
149
|
+
terminal has the focus under the kitty keyboard protocol, below); then
|
|
148
150
|
`Ctrl+K palette`. In a view's list it names what `Enter` does now
|
|
149
151
|
(`open`, `focus terminal` on the row whose terminal is open, `detail`
|
|
150
152
|
in the Souls and Capabilities views), then `n spawn` where it spawns,
|
|
153
|
+
`w workspaces` ([the list of workspaces](#the-list-of-workspaces)) in the Instances view,
|
|
151
154
|
and `? help` and `q quit` last; with the detail's focus `Tab back`
|
|
152
|
-
comes before `Enter`. The other keys (the acts, `/`, `Tab`, `r`,
|
|
155
|
+
comes before `Enter`. The other keys (the acts, `/`, `Tab`, `r`,
|
|
153
156
|
and a terminal's `z`, `c`, `[` and `]`) are not listed there:
|
|
154
|
-
the
|
|
157
|
+
the palette and the help name them. While the
|
|
155
158
|
terminal has the focus, in an overlay and in the filter field it names
|
|
156
|
-
the keys that work them. While the leader waits for its key the rows
|
|
157
|
-
|
|
159
|
+
the keys that work them. While the leader waits for its key the rows do
|
|
160
|
+
not change.
|
|
158
161
|
Everything flows from the top, so empty rows are at the bottom. On a
|
|
159
162
|
short screen the list keeps its rows first: the cheat sheet gives up rows
|
|
160
163
|
from its end, down to the leader alone, then the empty row under the
|
|
@@ -180,8 +183,21 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
180
183
|
indent alone says which instance is under which: no mark is drawn for
|
|
181
184
|
it. A row whose instances are folded away (`h`) says how many after its
|
|
182
185
|
name: `+1`.
|
|
183
|
-
- **Each row** is the mark of its state and the name, then
|
|
184
|
-
|
|
186
|
+
- **Each row** is the mark of its state and the name, then, when it needs
|
|
187
|
+
input, a tag at its right edge in the Desktop's words: `Needs input`. A
|
|
188
|
+
folded row with waiting instances among those it folds away says how
|
|
189
|
+
many: `3 below`, and `99+ below` past 99. A row that needs input itself
|
|
190
|
+
and folds waiting ones away says `Needs input`, as the Desktop's row
|
|
191
|
+
does: the detail's `below` line names the others. The tag is in reverse
|
|
192
|
+
video in the waiting colour, and on the selected row, which is in reverse
|
|
193
|
+
video already, it is the waiting colour not reversed, a gap in the
|
|
194
|
+
selection's bar; under `NO_COLOR` the reverse video alone carries it. On
|
|
195
|
+
a narrow row the tag gives way first: it says its words only where the
|
|
196
|
+
whole name, its `+1` and the row's word in its column all fit beside them,
|
|
197
|
+
and else shrinks to `!`, or the count alone (`3`, `99+`), still in
|
|
198
|
+
reverse video, in the cells every row keeps at its right edge. So the
|
|
199
|
+
tag never cuts a name, a word or a mark: those give way as on a row
|
|
200
|
+
that does not wait. The harness and the state in words are in
|
|
185
201
|
the detail. A row has a word, dim, only where its mark cannot say it: the
|
|
186
202
|
state of a home a spawn or a retire holds (`Retire didn't finish`), or
|
|
187
203
|
the shared words for why an instance cannot be reached or opened:
|
|
@@ -245,16 +261,17 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
|
|
|
245
261
|
deployment, such as `garnet now reports workspace other.` for a machine
|
|
246
262
|
that reported another workspace before, or that a deployment's teams are
|
|
247
263
|
local only. It stands under the deployment's heading. In a view of one
|
|
248
|
-
deployment, which has no heading, it stands under the
|
|
264
|
+
deployment, which has no heading, it stands under the list of workspaces.
|
|
249
265
|
- **The detail has a `machine` line**, the machine the selected instance is
|
|
250
266
|
on. When that deployment is not live, the whole sentence that says why
|
|
251
267
|
follows it.
|
|
268
|
+
- **In a view of one deployment of another machine**, which has no heading,
|
|
269
|
+
the detail has the `machine` line too: nothing else names the machine.
|
|
252
270
|
|
|
253
|
-
**A view that holds no deployment of this machine**
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
is not live, is said under the title with the reason, as for a deployment
|
|
271
|
+
**A view that holds no deployment of this machine** names its machines in
|
|
272
|
+
its headings, or, with one machine, in the detail's `machine` line. The time
|
|
273
|
+
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
|
|
274
|
+
is not live, is said under the list of workspaces with the reason, as for a deployment
|
|
258
275
|
of this machine. When no row of that machine is kept either, nothing is drawn
|
|
259
276
|
under the reason: no list and no detail.
|
|
260
277
|
|
|
@@ -274,13 +291,24 @@ in its workspace for the rest of the run, also while it is not reached.
|
|
|
274
291
|
| `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
|
|
275
292
|
| `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
|
|
276
293
|
| `+n` | `+n` | after a name: n instances folded away below it |
|
|
277
|
-
|
|
|
278
|
-
|
|
|
294
|
+
| `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 |
|
|
295
|
+
| `N below` | `N below` | N instances folded away below it need input, `N` where the whole name does not fit beside the words |
|
|
279
296
|
| `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
|
|
280
297
|
| `*` | `*` | in the switcher: the workspace that is open |
|
|
281
298
|
|
|
282
299
|
Every state has a mark of its own shape, so nothing is told by colour alone.
|
|
283
300
|
|
|
301
|
+
**An instance's colour** (feature `instance-color`; set with
|
|
302
|
+
`oats instance color <instance> <colour>`, [desktop-cli-api.md](desktop-cli-api.md#an-instances-colour-oats-instance-color))
|
|
303
|
+
colours its mark, in the list and in a soul's detail: a running mark in it, a
|
|
304
|
+
stopped one and one with a shell left in it dim in it. `?` and `◆` keep their
|
|
305
|
+
own look whatever the colour, and an instance with no colour looks as above.
|
|
306
|
+
The six colours are the terminal's: `sand` yellow, `sage` green, `slate` blue,
|
|
307
|
+
`mauve` magenta, `clay` red, `olive` cyan, the souls' own map. Which colour a
|
|
308
|
+
row shows is the Desktop's rule (`instanceColor` in `packages/client`); an
|
|
309
|
+
older kernel reports none. Setting a colour from the TUI is not in this
|
|
310
|
+
version.
|
|
311
|
+
|
|
284
312
|
<a id="held-rows"></a>**A held row** says in its word what holds it, by the
|
|
285
313
|
Desktop's rule:
|
|
286
314
|
|
|
@@ -306,7 +334,7 @@ last rows stay as they were; or they stay and are marked `stale`, with the
|
|
|
306
334
|
time of the last read that succeeded (a remote that could not be read
|
|
307
335
|
again); or the
|
|
308
336
|
deployment is `not observed` and no row is drawn. A state that is not live
|
|
309
|
-
is said in words under the
|
|
337
|
+
is said in words under the list of workspaces, with the reason on rows of its own. When
|
|
310
338
|
the kernel refused the read and no rows are kept, the reason says so and
|
|
311
339
|
quotes it: `OATS answered with an error (<code>). It says: <message>`. When
|
|
312
340
|
the last rows are kept as `stale`, the reason says so and then quotes the
|
|
@@ -332,7 +360,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
332
360
|
## Open an agent's terminal
|
|
333
361
|
|
|
334
362
|
```
|
|
335
|
-
|
|
363
|
+
acme-platform │[backend-lead 1]
|
|
336
364
|
│$ make docs
|
|
337
365
|
Instances 1 │Building the reference...
|
|
338
366
|
> ● backend-lead │
|
|
@@ -341,33 +369,50 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
341
369
|
Souls 2 │
|
|
342
370
|
Capabilities 3 │
|
|
343
371
|
──────────────────────────────│
|
|
344
|
-
Alt+
|
|
345
|
-
Alt+
|
|
346
|
-
Alt+
|
|
372
|
+
Alt+K palette │
|
|
373
|
+
Alt+Shift+Up/Down agent │
|
|
374
|
+
Alt+W close │
|
|
375
|
+
Alt+Z zoom │
|
|
376
|
+
Ctrl+X commands │
|
|
377
|
+
Ctrl+X Esc the list │
|
|
378
|
+
Ctrl+X Ctrl+X types Ctrl+X │
|
|
347
379
|
```
|
|
348
380
|
|
|
349
381
|
- **`Enter` on an instance that runs** opens its terminal on the right of
|
|
350
|
-
the sidebar, where the detail was, over every row. Its top row
|
|
351
|
-
|
|
382
|
+
the sidebar, where the detail was, over every row. Its top row is the
|
|
383
|
+
[tab bar](#tabs), here one tab: the agent's name and the tab's number in
|
|
384
|
+
brackets (no number on macOS; and ` · <machine>` for one of another machine); under it is the
|
|
352
385
|
agent's screen, as the agent draws it, in its own colours. While a
|
|
353
386
|
terminal is open the sidebar keeps 30 columns at most, also while the
|
|
354
387
|
detail stands in the terminal's place, and a name longer than its row is
|
|
355
388
|
cut with `…` (`...` in ASCII).
|
|
356
389
|
- **The terminal has the focus.** What you type, what you paste and every
|
|
357
390
|
key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
|
|
358
|
-
among them, but for **[the leader](#the-leader)** (`
|
|
359
|
-
|
|
360
|
-
one key the TUI takes from the agent, and the [chords](#chords)
|
|
361
|
-
|
|
391
|
+
among them, but for **[the leader](#the-leader)** (`Ctrl+X`, unless
|
|
392
|
+
[`tui.json`](#change-the-keys-tuijson) names another), the
|
|
393
|
+
one key the TUI takes from the agent, and the [chords](#chords) (the
|
|
394
|
+
Alt ones by default, or the Ctrl+Alt or Ctrl+Shift ones when
|
|
395
|
+
[keys.json chooses them](#switch-family), while your terminal sends them). Under the kitty keyboard protocol every key reaches
|
|
362
396
|
the agent as the bytes it sends without it. The leader then `Esc` gives the
|
|
363
397
|
focus to the list; the leader twice types the leader into the agent; the
|
|
364
398
|
leader then another key does what that key does from anywhere. While the
|
|
365
399
|
terminal has the focus the cheat sheet names those three:
|
|
366
|
-
`
|
|
367
|
-
|
|
400
|
+
`Ctrl+X commands`, `Ctrl+X Esc the list`, `Ctrl+X Ctrl+X types Ctrl+X`.
|
|
401
|
+
While every chord of the family in force is read ([Chords](#chords)),
|
|
402
|
+
which in the Alt family is in every terminal, the chords come first:
|
|
403
|
+
`Alt+K palette`, `Alt+Shift+Up/Down agent`, `Alt+Left/Right tab` (with
|
|
404
|
+
two tabs or more), `Alt+W close`, `Alt+Z zoom`, then the leader's three.
|
|
405
|
+
In the Ctrl+Alt family they are `Ctrl+Alt+K`, `Alt+Shift+Left/Right`,
|
|
406
|
+
`Ctrl+Alt+W` and `Ctrl+Alt+Z`, and in the Ctrl+Shift family
|
|
407
|
+
`Ctrl+Shift+K`, `Ctrl+Shift+W` and `Ctrl+Shift+M`, which lead only while
|
|
408
|
+
the terminal confirms the kitty keyboard protocol. Without it the
|
|
409
|
+
leader's three lead, and the Alt+Shift arrows follow them.
|
|
410
|
+
On a short screen the sheet gives up rows from its end, and the leader's
|
|
411
|
+
`commands` last of all. A leader inside a bracketed paste is pasted, not
|
|
412
|
+
taken.
|
|
368
413
|
- **With the list focused** the terminal stays open, and the agent's screen
|
|
369
414
|
is still drawn as it changes. The cheat sheet names `Enter focus terminal`
|
|
370
|
-
on its row; the leader's
|
|
415
|
+
on its row; the help names the leader's `z` (zoom) and `w` (close terminal).
|
|
371
416
|
- `Enter` on the shown terminal's row gives it the focus again.
|
|
372
417
|
- `z` gives it the focus and the whole screen: the sidebar is hidden. The
|
|
373
418
|
leader then `Esc` brings the sidebar back beside it, and the leader then
|
|
@@ -387,10 +432,10 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
387
432
|
sheet shows it again. Beside the sidebar the terminal is never narrower
|
|
388
433
|
than 40 columns: with less room it has the whole screen too.
|
|
389
434
|
- **With the whole screen** (zoomed, or a narrow terminal) no cheat sheet is
|
|
390
|
-
drawn. The terminal's
|
|
391
|
-
`
|
|
392
|
-
|
|
393
|
-
screen keeps every row under it.
|
|
435
|
+
drawn. The terminal's tab bar carries the keys at its right, dim:
|
|
436
|
+
`Ctrl+X commands Ctrl+X Esc the list`, after the chords while they
|
|
437
|
+
lead the cheat sheet (above), as many as fit, the same while the leader waits. The
|
|
438
|
+
agent's screen keeps every row under it.
|
|
394
439
|
- **A terminal also closes by itself** when its viewer ends, shown or
|
|
395
440
|
hidden ([which tab is shown then](#tabs)): the agent's
|
|
396
441
|
window ended, its session went away, or the link to its machine dropped.
|
|
@@ -401,7 +446,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
401
446
|
terminal without it when it has not come. A tmux built with libutempter
|
|
402
447
|
(Ubuntu's and Debian's are) can lose that status: while it waits,
|
|
403
448
|
`oats tui` has tmux look for it again once a second, so the terminal
|
|
404
|
-
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
|
|
449
|
+
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
|
|
405
450
|
says what happened: that it could not be opened, that the connection to
|
|
406
451
|
its machine ended, or that the viewer ended without saying why. What the
|
|
407
452
|
viewer printed on its error output stands under that line in quotation
|
|
@@ -430,7 +475,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
430
475
|
## Tabs
|
|
431
476
|
|
|
432
477
|
```
|
|
433
|
-
|
|
478
|
+
acme-platform │[backend-lead 1]│ docs-writer• 2 │ qa-runner 3
|
|
434
479
|
│$ make test
|
|
435
480
|
Instances 1 │ok 41 of 41
|
|
436
481
|
> ● backend-lead │
|
|
@@ -440,32 +485,60 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
440
485
|
Souls 2 │
|
|
441
486
|
Capabilities 3 │
|
|
442
487
|
──────────────────────────────│
|
|
443
|
-
Alt+
|
|
444
|
-
Alt+
|
|
445
|
-
Alt+
|
|
488
|
+
Alt+K palette │
|
|
489
|
+
Alt+Shift+Up/Down agent │
|
|
490
|
+
Alt+Left/Right tab │
|
|
491
|
+
Alt+W close │
|
|
492
|
+
Alt+Z zoom │
|
|
493
|
+
Ctrl+X commands │
|
|
494
|
+
Ctrl+X Esc the list │
|
|
495
|
+
Ctrl+X Ctrl+X types Ctrl+X │
|
|
446
496
|
```
|
|
447
497
|
|
|
448
498
|
Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
449
499
|
|
|
450
|
-
- **The tab
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
- **The shown tab** is the one whose screen the panel draws
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
500
|
+
- **The tab bar** is the panel's top row whenever a terminal is open, with
|
|
501
|
+
one tab or many, as a terminal's own tabs read: each tab's agent, in the
|
|
502
|
+
order the tabs were opened, a dim `│` (`|` in ASCII) between two tabs.
|
|
503
|
+
- **The shown tab** is the one whose screen the panel draws, the front
|
|
504
|
+
tab. It stands in brackets, `[backend-lead 1]`, a mark that needs no
|
|
505
|
+
style, so it reads the same under `NO_COLOR` and in ASCII. Its name is
|
|
506
|
+
bold, and the whole tab is in reverse video while the terminal has the
|
|
507
|
+
focus.
|
|
508
|
+
- **The other tabs are hidden**, dim, a cell on each side of the name. A
|
|
509
|
+
hidden tab whose agent wrote since it was last shown has `•` after its
|
|
510
|
+
name (`*` in ASCII), not dim; the mark goes when the tab is shown. A
|
|
511
|
+
hidden tab's screen is not read: only that its agent wrote.
|
|
512
|
+
- **An agent of another machine** reads `<name> · <machine>` inside its
|
|
513
|
+
tab, the machine dim (`-` for `·` in ASCII): `[billing-lead · garnet 1]`.
|
|
514
|
+
- **Each tab ends with its number:** its position in its group's strip,
|
|
515
|
+
the N that `Alt+N` (`tab-N`) shows. It stands after the name, the
|
|
516
|
+
activity mark and the machine, one blank cell before the tab's closing
|
|
517
|
+
side (`[backend-lead 1]`, ` docs-writer• 2 `). It is dim, and dim in the
|
|
518
|
+
reverse video of the shown tab while its terminal has the focus. In a
|
|
519
|
+
[split](#splits) each group numbers its own tabs from 1. The first eight
|
|
520
|
+
tabs are numbered 1 to 8. In a strip of nine or more, the last tab
|
|
521
|
+
shows 9 (`tab-9` shows the last tab) and the others past the eighth
|
|
522
|
+
show none; with four tabs at most today, that is never reached. The
|
|
523
|
+
number is a position, not a key label: it is the same in every chord
|
|
524
|
+
family, and the same in ASCII. On macOS no tab has one: `⌥⌘1` to `⌥⌘9`,
|
|
525
|
+
the Desktop's keys for them, never reach a terminal, so no key would
|
|
526
|
+
reach the numbers.
|
|
527
|
+
- **The numbers go first, and all together.** They are drawn only while
|
|
528
|
+
every tab fits whole with them, every name and every machine.
|
|
529
|
+
Otherwise no tab shows a number, and the row is cut as below. A number
|
|
530
|
+
never takes a cell from a name. At 80 columns, with the sidebar beside
|
|
531
|
+
the panel, the numbers usually go at the third or fourth tab; at 120
|
|
532
|
+
all four fit.
|
|
533
|
+
- **A bar longer than its row is cut** in this order: the hidden tabs'
|
|
534
|
+
machines, then the hidden tabs' names, each to an equal share of what
|
|
535
|
+
the shown tab leaves, with `…` (`...` in ASCII), then the shown tab's
|
|
536
|
+
machine; then the hidden tabs farthest from the shown one are left out
|
|
537
|
+
of the row with their dividers (they stay open). The shown tab's name
|
|
538
|
+
stays whole while the row can hold it, and is cut last.
|
|
539
|
+
- The TUI takes no mouse input: a tab is shown with the keys below.
|
|
467
540
|
- **Opening.** `Enter` on a row, an instance in
|
|
468
|
-
[the palette](#the-palette),
|
|
541
|
+
[the palette](#the-palette), `Alt+Shift+Up` or `Alt+Shift+Down`, and a
|
|
469
542
|
[spawn](#spawning-an-agent)'s new agent open a terminal the same way:
|
|
470
543
|
- an instance that has a tab: that tab is shown, with the focus in it;
|
|
471
544
|
- any other: a new tab, after the shown one, is shown with the focus in
|
|
@@ -474,18 +547,21 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
474
547
|
machine is asked whether it can be opened, another open does nothing,
|
|
475
548
|
and neither does a key that shows another tab.
|
|
476
549
|
- **At four tabs nothing closes by itself.** The open does nothing, and
|
|
477
|
-
the line under the
|
|
550
|
+
the line under the list of workspaces says `4 terminals are open; close one with Ctrl+X w.`
|
|
478
551
|
(with your leader, when [`tui.json`](#change-the-keys-tuijson) names
|
|
479
552
|
another). A tab still starting, and an agent of another machine while
|
|
480
553
|
it is asked, hold a place among the four. An instance that cannot be
|
|
481
554
|
opened says why, as it does with no tab open.
|
|
482
555
|
- **Switching.** `[` and `]` in the Instances view, from the list or the
|
|
483
556
|
detail, show the tab before or after the shown one; the help names them,
|
|
484
|
-
and the leader's
|
|
485
|
-
open. The leader then
|
|
557
|
+
and the leader's own. The leader then
|
|
486
558
|
`Left` or `Right` does the same from any focus, and from another view
|
|
487
|
-
goes to the Instances view first
|
|
488
|
-
|
|
559
|
+
goes to the Instances view first, and so do the [chords](#chords)
|
|
560
|
+
`Alt+Left` and `Alt+Right` (`Alt+Shift+Left` and `Alt+Shift+Right` in the
|
|
561
|
+
Ctrl+Alt and Ctrl+Shift families). `Alt+1` to `Alt+8` show the focused
|
|
562
|
+
group's first to eighth tab, and `Alt+9` its last (`Ctrl+Alt+1` to
|
|
563
|
+
`Ctrl+Alt+9` in the other families).
|
|
564
|
+
- The bar does not wrap: on the first tab `[` does nothing, and on the
|
|
489
565
|
last `]`; the leader then `Left` or `Right` there leaves even the focus
|
|
490
566
|
where it was.
|
|
491
567
|
- The focus does not move: in the terminal it stays in the terminal,
|
|
@@ -493,10 +569,11 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
493
569
|
- **Showing a tab selects its instance's row** in the list and brings it
|
|
494
570
|
into view: a filter that hides the row is cleared, and an instance
|
|
495
571
|
folded over it is opened.
|
|
496
|
-
- **The palette**
|
|
497
|
-
as the Desktop's does. When the first of them
|
|
498
|
-
|
|
499
|
-
|
|
572
|
+
- **The palette** groups the instances as [The palette](#the-palette) says,
|
|
573
|
+
the group last used first, as the Desktop's does. When the first of them
|
|
574
|
+
is the shown tab's, the palette opens on the instance shown before it,
|
|
575
|
+
wherever its group puts it, so the palette then `Enter` goes back to that
|
|
576
|
+
terminal.
|
|
500
577
|
- **Closing.** The leader then `w`, or `c` in the Instances view, closes the
|
|
501
578
|
shown tab: its agent keeps running. The tab to its right is shown, else
|
|
502
579
|
the one to its left.
|
|
@@ -506,17 +583,44 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
506
583
|
- Closing the last tab closes the panel: the right side is the detail
|
|
507
584
|
again, and the list has the focus.
|
|
508
585
|
- **A tab that closes by itself**, when its viewer ends, says so on the line
|
|
509
|
-
under the
|
|
586
|
+
under the list of workspaces in the words [above](#open-an-agents-terminal), for that
|
|
510
587
|
tab's agent (no line when it ended cleanly).
|
|
511
588
|
- The shown tab: the tab to its right is shown, else the one to its left,
|
|
512
589
|
and the list takes the focus.
|
|
513
590
|
- A hidden tab: the shown tab and the focus stay as they were.
|
|
514
591
|
- **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole
|
|
515
|
-
screen. The
|
|
516
|
-
- **The tabs are the open workspace's
|
|
517
|
-
[the switcher](#the-switcher)
|
|
518
|
-
|
|
519
|
-
|
|
592
|
+
screen. The tab bar stays its top row, and the other tabs stay open.
|
|
593
|
+
- **The tabs are the open workspace's, and it keeps them while the run
|
|
594
|
+
lasts.** Opening another workspace in [the switcher](#the-switcher)
|
|
595
|
+
closes their viewers; their agents keep running, and nothing of a hidden
|
|
596
|
+
workspace's terminals runs meanwhile. Coming back opens them again, one
|
|
597
|
+
at a time as an open goes, once the workspace's rows are read; a tab of
|
|
598
|
+
one of its deployments whose last read failed waits, with the tabs after
|
|
599
|
+
it, until that deployment is read again:
|
|
600
|
+
- the tabs in their order and their groups, the split, each group's
|
|
601
|
+
shown tab, and the focus (the terminal's, zoomed or not, or the list's)
|
|
602
|
+
as the workspace was left. The shown tab is the most recent for
|
|
603
|
+
[the palette](#the-palette).
|
|
604
|
+
- A tab whose instance is gone or cannot be opened now (retired,
|
|
605
|
+
stopped) is dropped, and nothing is said of it. A group the drops
|
|
606
|
+
leave with no tab goes, as when its last tab is closed; a group that
|
|
607
|
+
was empty when the workspace was left is empty again. A shown tab
|
|
608
|
+
dropped gives its place to the next, else the one before.
|
|
609
|
+
- Another machine's tab is asked first again, as an open is; when that
|
|
610
|
+
fails, the line says why and the tab is dropped. Suspending the TUI
|
|
611
|
+
while it is asked asks it again once the TUI is back.
|
|
612
|
+
- A key pressed while the tabs open again leaves the focus where it is:
|
|
613
|
+
the tabs still open, and the list keeps it. Opening an agent yourself
|
|
614
|
+
meanwhile stops it: the tabs not open yet are dropped. Opening another
|
|
615
|
+
workspace meanwhile closes what was opened, and keeps the rest for the
|
|
616
|
+
next time.
|
|
617
|
+
|
|
618
|
+
A workspace no longer being listed forgets them, open (its tabs close)
|
|
619
|
+
or not; one listed again later starts with none. A read that failed is
|
|
620
|
+
not the workspace gone: it forgets nothing.
|
|
621
|
+
Opening the same workspace again, with its deployment of this machine
|
|
622
|
+
now opened beside another machine's, keeps them as they are. Nothing is
|
|
623
|
+
kept after the run ends.
|
|
520
624
|
|
|
521
625
|
## Splits
|
|
522
626
|
|
|
@@ -531,13 +635,13 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
531
635
|
Souls 2 │ │
|
|
532
636
|
Capabilities 3 │ │
|
|
533
637
|
──────────────────────────────│ │
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
638
|
+
Ctrl+X commands │ │
|
|
639
|
+
Ctrl+X Esc the list │ │
|
|
640
|
+
Ctrl+X Ctrl+X types Ctrl+X │ │
|
|
537
641
|
```
|
|
538
642
|
|
|
539
643
|
The panel can be split in two **groups**, side by side or one above the
|
|
540
|
-
other. Each group is a panel of [tabs](#tabs) of its own: a
|
|
644
|
+
other. Each group is a panel of [tabs](#tabs) of its own: a tab bar, a shown
|
|
541
645
|
tab and the marks of its hidden ones.
|
|
542
646
|
|
|
543
647
|
- **Splitting.** The leader then `|` splits the panel side by side, and the
|
|
@@ -546,16 +650,16 @@ tab and the marks of its hidden ones.
|
|
|
546
650
|
(left, or top). The second group starts empty and is the focused group.
|
|
547
651
|
- A split needs a tab open, and none starting.
|
|
548
652
|
- **There are at most two groups.** With two, the split keys do nothing,
|
|
549
|
-
and the line under the
|
|
653
|
+
and the line under the list of workspaces says `The panel has two groups already.`
|
|
550
654
|
- **Each group needs 40 columns side by side, and 8 rows one above the
|
|
551
|
-
other**, its
|
|
655
|
+
other**, its tab bar counted. The panel beside the sidebar then needs 81
|
|
552
656
|
columns (a terminal of 112), or 17 rows. A split that would leave a
|
|
553
657
|
group smaller does nothing, and the line says so:
|
|
554
658
|
`No room to split side by side: each group needs 40 columns.` or
|
|
555
659
|
`No room to split one above the other: each group needs 8 rows.`
|
|
556
660
|
- **What is drawn.** A rule separates the groups. Both groups' shown tabs
|
|
557
661
|
are drawn as their agents write; hidden tabs only set their marks.
|
|
558
|
-
- The focused group's
|
|
662
|
+
- The focused group's tab bar is drawn as with one group: its shown tab in
|
|
559
663
|
reverse while its terminal has the focus, bold otherwise. The other
|
|
560
664
|
group's shown tab is bold, never in reverse, so one terminal at a time
|
|
561
665
|
reads as the one you type into.
|
|
@@ -572,14 +676,14 @@ tab and the marks of its hidden ones.
|
|
|
572
676
|
- **Zoom** (`z`, or the leader then `z`) gives the focused group's shown
|
|
573
677
|
terminal the whole screen, and the same key brings the split back. With
|
|
574
678
|
the empty group focused it does nothing.
|
|
575
|
-
- **Opening.** `Enter`, the palette,
|
|
679
|
+
- **Opening.** `Enter`, the palette, `Alt+Shift+Up`/`Alt+Shift+Down` and a
|
|
576
680
|
spawn open as with one group:
|
|
577
681
|
- an instance that has a tab, in either group: that tab is shown in its
|
|
578
682
|
group, and that group takes the focus;
|
|
579
683
|
- any other: a new tab in the focused group, after its shown tab, or as
|
|
580
684
|
the first tab of the empty group.
|
|
581
685
|
- **The four tabs are counted across both groups.** At four, the line
|
|
582
|
-
says `4 terminals are open; close one with
|
|
686
|
+
says `4 terminals are open; close one with Ctrl+X w.` as with one group.
|
|
583
687
|
- **Moving between the groups.** The leader then `Tab` from a terminal goes
|
|
584
688
|
to the other group's shown terminal, or to the other group when it is
|
|
585
689
|
empty. From the list it goes to the focused group's terminal, or, with
|
|
@@ -625,7 +729,7 @@ them, from the same code.
|
|
|
625
729
|
──────────────────────────────────────│ ● dev-1 ● dev-2
|
|
626
730
|
Capabilities 3 │ i shows them in the Instances view.
|
|
627
731
|
──────────────────────────────────────│
|
|
628
|
-
|
|
732
|
+
Ctrl+X commands │
|
|
629
733
|
Ctrl+K palette │
|
|
630
734
|
Enter detail │
|
|
631
735
|
n spawn │
|
|
@@ -694,7 +798,7 @@ them, from the same code.
|
|
|
694
798
|
oats-okf · package · v1.2.0 │
|
|
695
799
|
okf-knowledge Knowledge │ Used by 2 souls
|
|
696
800
|
──────────────────────────────────────│ ■ dev ·2 · 1 on an older version
|
|
697
|
-
|
|
801
|
+
Ctrl+X commands │ ■ reviewer ·1
|
|
698
802
|
Ctrl+K palette │
|
|
699
803
|
Enter detail │
|
|
700
804
|
? help │
|
|
@@ -765,24 +869,110 @@ them, from the same code.
|
|
|
765
869
|
each with where it comes from; choosing one shows this view with it
|
|
766
870
|
selected.
|
|
767
871
|
|
|
872
|
+
## The list of workspaces
|
|
873
|
+
|
|
874
|
+
```
|
|
875
|
+
acme-platform │ dev
|
|
876
|
+
acme-billing ● │ soul dev
|
|
877
|
+
lfx │ state running
|
|
878
|
+
garnet │ harness claude, claude-opus-5-5 (so…
|
|
879
|
+
+2 │ work worktree, agents/dev
|
|
880
|
+
│ team eng
|
|
881
|
+
Instances 1 │ started 11:00
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
The sidebar's first rows list the workspaces this run can show, one row a
|
|
885
|
+
workspace, whatever machines it is on, in [the switcher](#the-switcher)'s
|
|
886
|
+
order: `lfx` is one row however many machines hold it, and a machine the
|
|
887
|
+
rules shared with the Desktop matched to no workspace is a row by its own
|
|
888
|
+
name, in the same flat list. A row is one line: the name. With one
|
|
889
|
+
workspace the list is its row.
|
|
890
|
+
|
|
891
|
+
- **Not in the list:** this computer's deployments that this run has not
|
|
892
|
+
opened (a workspace only they make), and the rows that cannot be opened
|
|
893
|
+
(missing, not a deployment, unreadable, a machine with nothing to open).
|
|
894
|
+
The switcher keeps them: `w` twice.
|
|
895
|
+
- **The open workspace's row** is in reverse video, and while the list has
|
|
896
|
+
the focus its name is underlined instead (the cursor has the reverse
|
|
897
|
+
video). Its state, when it is not live, is said under the list.
|
|
898
|
+
- **The dot**, `●` in yellow one cell after the name, says that an instance
|
|
899
|
+
of that workspace needs input, the claim the list of instances shows, the
|
|
900
|
+
open workspace's included. On a row in reverse video its cell is a gap in
|
|
901
|
+
the bar: the dot is on the normal background. With colour off
|
|
902
|
+
(`NO_COLOR`) or in ASCII it is `!`, and the help's Marks name it. It
|
|
903
|
+
comes from what this run observes alone, its reads of the deployments it
|
|
904
|
+
serves and of other machines: a workspace whose instances are not known
|
|
905
|
+
(never read, stale, not reached) has no dot, never a false one. The dot
|
|
906
|
+
never moves a row.
|
|
907
|
+
- **A long name** is cut with `…` (`...` in ASCII), the dot one cell after
|
|
908
|
+
what is drawn of it, as it is after a name drawn in `?` where the locale
|
|
909
|
+
is not UTF-8.
|
|
910
|
+
- **Five rows at most.** With more, four stand around the open row (around
|
|
911
|
+
the cursor's while the list has the focus), and `+N` says how many
|
|
912
|
+
workspaces are not shown, with the dot one cell after it when an instance
|
|
913
|
+
of one of them needs input (`+3 ●`; the help's Marks say so too). Under 80 columns or beside a terminal (30
|
|
914
|
+
columns) the names are cut as the list of instances cuts them.
|
|
915
|
+
|
|
916
|
+
**The keys:**
|
|
917
|
+
|
|
918
|
+
- **The leader then `Up` or `Down`**, or the [chords](#chords) `Alt+Up` and
|
|
919
|
+
`Alt+Down` (in the Alt family and on macOS; the Ctrl+Alt and Ctrl+Shift
|
|
920
|
+
families leave them to the programs, and the leader does it), opens the
|
|
921
|
+
workspace before or after the open one, as the list draws them. It does not wrap: at an end nothing
|
|
922
|
+
moves, and the line under the list says `No workspace above this one.` or
|
|
923
|
+
`No workspace below this one.` until the next key, of any kind (one typed
|
|
924
|
+
to an agent too), or a resize. The line stands in the empty row under the
|
|
925
|
+
list, so the list of instances does not move while it shows; only when
|
|
926
|
+
that list fills the sidebar, which then has no such row, does the line
|
|
927
|
+
take a row, the list giving up its last. With the list's focus (`w`) the
|
|
928
|
+
focus stays there, the cursor where it was. A workspace with a deployment of this
|
|
929
|
+
machine not opened yet (lfx, with `~/Work/lfx` on this computer's list)
|
|
930
|
+
opens it first, as the switcher's `Enter` does. What the workspace left
|
|
931
|
+
had open is kept for it, as for a switch from the
|
|
932
|
+
switcher ([Tabs](#tabs)), and from a terminal's focus the focus is kept
|
|
933
|
+
too.
|
|
934
|
+
With no workspace open (a run started outside a deployment, or the open
|
|
935
|
+
one gone), the switcher is shown, and the leader then `Down` opens the
|
|
936
|
+
first row the list would hold and `Up` its last; with no such row
|
|
937
|
+
nothing happens.
|
|
938
|
+
- **`w`**, the leader then `o`, and `Alt+O` (`Ctrl+Alt+O` or
|
|
939
|
+
`Ctrl+Shift+S` in the [other families](#switch-family)) give the list the focus, on the open workspace's row. The row
|
|
940
|
+
under the cursor carries `>` and the reverse video, and the open
|
|
941
|
+
workspace's name is underlined until `Enter` opens another; the list of
|
|
942
|
+
instances keeps its selection in reverse video, without its `>`. `Up`/`k`,
|
|
943
|
+
`Down`/`j`, `g`/`Home` and `G`/`End` move the cursor over the rows that
|
|
944
|
+
open; `Enter` opens its row and gives the list of instances the focus;
|
|
945
|
+
`Esc` gives that focus back with nothing opened; `w` again opens the
|
|
946
|
+
switcher, for what the list does not hold. Any other key gives the list
|
|
947
|
+
of instances the focus, then does what it does there. The cheat sheet
|
|
948
|
+
says `Enter open`, `Up/Down move`, `Esc back`, `w all workspaces`, with
|
|
949
|
+
the keys `tui.json` gives those actions; one with no key has no hint.
|
|
950
|
+
A row whose deployment an identity read places in a workspace (or takes
|
|
951
|
+
out of one) keeps the cursor: it moves to the row that now holds it.
|
|
952
|
+
- The list is no stop of `Tab`, and the TUI takes no mouse input.
|
|
953
|
+
|
|
768
954
|
## The switcher
|
|
769
955
|
|
|
770
|
-
`w`
|
|
956
|
+
`w` from [the list of workspaces](#the-list-of-workspaces)' focus (`w` twice
|
|
957
|
+
from the list of instances) opens the switcher: what this run can show, over
|
|
958
|
+
the main area, with what the list does not hold: each deployment's line,
|
|
959
|
+
this computer's deployments not opened, the rows that cannot be opened, the
|
|
960
|
+
filter, and Remove. With no workspace open, `w` opens it at once. The
|
|
771
961
|
sidebar's title says `workspaces` and no view is open; under 80 columns the
|
|
772
962
|
switcher covers the whole screen.
|
|
773
963
|
|
|
774
964
|
```
|
|
775
|
-
workspaces │ > * acme-platform
|
|
776
|
-
│
|
|
777
|
-
Instances 1 │
|
|
778
|
-
Souls 2 │
|
|
779
|
-
Capabilities 3 │
|
|
780
|
-
────────────────────────────────────────────────│
|
|
781
|
-
|
|
782
|
-
Ctrl+K palette │
|
|
783
|
-
Enter open │
|
|
784
|
-
/ filter │
|
|
785
|
-
r refresh │
|
|
965
|
+
workspaces │ > * acme-platform
|
|
966
|
+
│ This machine
|
|
967
|
+
Instances 1 │ garnet
|
|
968
|
+
Souls 2 │ lfx
|
|
969
|
+
Capabilities 3 │ This machine · not opened
|
|
970
|
+
────────────────────────────────────────────────│ athenea (lfx)
|
|
971
|
+
Ctrl+X commands │ Not matched to a workspace
|
|
972
|
+
Ctrl+K palette │ basalt ssh needs a prompt
|
|
973
|
+
Enter open │ On this machine, not opened
|
|
974
|
+
/ filter │ acme-docs Timed out · ~/acme-docs
|
|
975
|
+
r refresh │ sandbox Not found.
|
|
786
976
|
Esc close │
|
|
787
977
|
? help │
|
|
788
978
|
q quit │
|
|
@@ -790,20 +980,36 @@ switcher covers the whole screen.
|
|
|
790
980
|
|
|
791
981
|
It lists, in this order:
|
|
792
982
|
|
|
793
|
-
- **The workspaces
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
983
|
+
- **The workspaces**, one row each, by name. Under each stands one dim line
|
|
984
|
+
per deployment of it:
|
|
985
|
+
- the machine it is on (`This machine`, `garnet`), with the folder's last
|
|
986
|
+
segment when one machine holds two deployments of it;
|
|
987
|
+
- then its state when it is not live: `not opened` for a deployment of
|
|
988
|
+
this computer's list that this run has not opened, else the words the
|
|
989
|
+
sidebar's headings use (`not observed`, `not reached`, `stale`,
|
|
990
|
+
`remembered`).
|
|
991
|
+
|
|
992
|
+
A workspace is what the rules shared with the Desktop make of the
|
|
993
|
+
deployments opened in this run, of what the registered machines answered,
|
|
994
|
+
and of the deployments of this computer's list whose workspace was read
|
|
995
|
+
(below): the ones that report the same workspace (its key and default
|
|
996
|
+
team) are one row, whichever machine they are on. Its name is the one a
|
|
997
|
+
deployment of this machine gives it: the workspace's own name once one is
|
|
998
|
+
opened and read, the folder's name of one that is not, else the last part
|
|
999
|
+
of the workspace's key. `*` marks the workspace that is open.
|
|
799
1000
|
- **`Not matched to a workspace`**: what those rules matched to no
|
|
800
1001
|
workspace, each by its own name with a short reason. A machine that has
|
|
801
1002
|
not answered in this run is listed here.
|
|
802
1003
|
- **`On this machine, not opened`**: the rows of this computer's list of
|
|
803
|
-
deployments (`oats deployments`) that this run has not opened
|
|
804
|
-
list's order, each by its folder's name and its
|
|
805
|
-
|
|
806
|
-
path
|
|
1004
|
+
deployments (`oats deployments`) that this run has not opened and that no
|
|
1005
|
+
workspace took, in the list's order, each by its folder's name and its
|
|
1006
|
+
path. A row whose workspace is not known yet says nothing more; one whose
|
|
1007
|
+
read failed says why before its path (`Timed out`, `Not read`), and so
|
|
1008
|
+
does one whose workspace attaches to none (`Workspace not known yet`,
|
|
1009
|
+
`Invalid workspace reference`, `Reports no workspace`), so a narrow row
|
|
1010
|
+
cuts the path, not the reason; both still open.
|
|
1011
|
+
A row that cannot be opened says why where its path stood, and does not
|
|
1012
|
+
open:
|
|
807
1013
|
|
|
808
1014
|
| The row says | The list's state |
|
|
809
1015
|
|---|---|
|
|
@@ -811,9 +1017,26 @@ It lists, in this order:
|
|
|
811
1017
|
| `Not an OATS deployment any more.` | `not-a-deployment`: the folder has no `oats-local.yaml` |
|
|
812
1018
|
| `Can't be read.` | `unreadable`: the check failed, for example for a permission |
|
|
813
1019
|
|
|
814
|
-
The list is read when the switcher opens, on `r` in
|
|
815
|
-
Remove. When a read fails, the rows of the last read stay,
|
|
816
|
-
that says the list could not be read, with the kernel's
|
|
1020
|
+
The list is read once at the start, when the switcher opens, on `r` in
|
|
1021
|
+
it and after a Remove. When a read fails, the rows of the last read stay,
|
|
1022
|
+
under a line that says the list could not be read, with the kernel's
|
|
1023
|
+
message.
|
|
1024
|
+
|
|
1025
|
+
**How a deployment of the list finds its workspace.** Each row of the list
|
|
1026
|
+
that this run has not opened and that the kernel says is a deployment is
|
|
1027
|
+
read for its workspace identity: `oats status --dir <path> --json`, the
|
|
1028
|
+
same read an opened deployment gets, whose `workspace` object says which
|
|
1029
|
+
workspace and default team it is.
|
|
1030
|
+
|
|
1031
|
+
- **When:** once at the start, and again each time the switcher is opened
|
|
1032
|
+
and on `r` in it, after the list is read. Never on a timer.
|
|
1033
|
+
- **How:** one at a time, each with its own 30 seconds, all of them within
|
|
1034
|
+
60 seconds. A read still running when the 60 seconds are up is ended,
|
|
1035
|
+
and it and the ones not begun say `Timed out`.
|
|
1036
|
+
- **The switcher never waits for them:** it is drawn at once, and each
|
|
1037
|
+
answer moves its row into its workspace's as it comes in. A later
|
|
1038
|
+
answer replaces an earlier one; nothing else is read from such a
|
|
1039
|
+
deployment until it is opened.
|
|
817
1040
|
|
|
818
1041
|
| Key | Does |
|
|
819
1042
|
|---|---|
|
|
@@ -825,9 +1048,16 @@ It lists, in this order:
|
|
|
825
1048
|
| `Esc` | while a Remove is asked, keeps the row; else clears a kept filter; else closes the switcher, back to the view that was open |
|
|
826
1049
|
| `1` | closes the switcher, back to the view that was open |
|
|
827
1050
|
|
|
828
|
-
**Enter on a workspace** opens its view.
|
|
829
|
-
|
|
830
|
-
|
|
1051
|
+
**Enter on a workspace** opens its view. Every deployment of it on this
|
|
1052
|
+
machine that this run has not opened is opened first: asked whether it is
|
|
1053
|
+
still a deployment, as a row of the list is, then read with the others from
|
|
1054
|
+
then on. The view holds it and the other machines' deployments of the
|
|
1055
|
+
workspace at once, `not observed` until its first read. One that is no
|
|
1056
|
+
longer a deployment is not opened, and the workspace opens on its other
|
|
1057
|
+
deployments; with none to open, the switcher stays and the list is read
|
|
1058
|
+
again. **Enter on a row of the list** opens that deployment in this run:
|
|
1059
|
+
from then on it is read with the others, and its workspace is the open
|
|
1060
|
+
view. A folder that stopped being a deployment
|
|
831
1061
|
since the list was read is not opened: its row says
|
|
832
1062
|
`Not an OATS deployment any more.` where its path stood.
|
|
833
1063
|
|
|
@@ -856,10 +1086,12 @@ A workspace this run has open has no Remove here.
|
|
|
856
1086
|
would make the file refused at the start. To use another key, give it to
|
|
857
1087
|
`remove` there, for example `{ "keys": { "remove": ["x"] } }`.
|
|
858
1088
|
|
|
859
|
-
**Each
|
|
860
|
-
where its list and its detail were scrolled, and what
|
|
861
|
-
found again when the
|
|
862
|
-
|
|
1089
|
+
**Each workspace keeps its place while the run lasts:** the selected
|
|
1090
|
+
instance, where its list and its detail were scrolled, the filter, and what
|
|
1091
|
+
was folded away are found again when the workspace is opened again, through
|
|
1092
|
+
any of its deployments. A filter still being typed in is kept as `Enter`
|
|
1093
|
+
keeps it. Another workspace starts with no filter, or with its own. Nothing
|
|
1094
|
+
is kept after the run ends.
|
|
863
1095
|
|
|
864
1096
|
**When the open workspace stops being listed** (it was a machine, and the
|
|
865
1097
|
kernel's answer stopped naming it), the switcher is shown with
|
|
@@ -891,7 +1123,7 @@ confirmation, which is needed only when the first retire's holder can't be
|
|
|
891
1123
|
read, since the kernel refuses a second retire while one runs. The
|
|
892
1124
|
palette offers the acts the selected instance offers now, and the leader's
|
|
893
1125
|
hint and the help name their keys. A key for an act
|
|
894
|
-
the instance does not offer opens nothing, and the line under the
|
|
1126
|
+
the instance does not offer opens nothing, and the line under the list of workspaces
|
|
895
1127
|
says why. The keys are yours to change in
|
|
896
1128
|
[`tui.json`](#change-the-keys-tuijson): the actions are `stop`, `retire`,
|
|
897
1129
|
`start` and `restart`.
|
|
@@ -1028,7 +1260,7 @@ the TUI adds only what to do next, naming its keys or an `oats` command:
|
|
|
1028
1260
|
|
|
1029
1261
|
| Outcome | What follows |
|
|
1030
1262
|
|---|---|
|
|
1031
|
-
| created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the sidebar in a new [tab](#tabs), with the focus in it. With four tabs open the line says it was created, then `4 terminals are open; close one with
|
|
1263
|
+
| created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the sidebar in a new [tab](#tabs), with the focus in it. With four tabs open the line says it was created, then `4 terminals are open; close one with Ctrl+X w.`, and nothing opens. Not running after two reads: the line says it is not visible yet, and nothing opens later by itself |
|
|
1032
1264
|
| created, but not started, or its wake not saved, or not finished | the line says so; nothing opens. A home the spawn left reads as [held](#held-rows) |
|
|
1033
1265
|
| not known (the answer was lost, or still running at the deadline) | the line says so, and `C` checks its result once, without spawning again: it is offered only then |
|
|
1034
1266
|
| its cleanup is owed | the line says so and names the retire |
|
|
@@ -1040,6 +1272,265 @@ The line after leaving says so and names `oats status` to see it.
|
|
|
1040
1272
|
|
|
1041
1273
|
## Keys
|
|
1042
1274
|
|
|
1275
|
+
The keys come in three layers:
|
|
1276
|
+
|
|
1277
|
+
1. **In the list:** plain keys, such as `n` to spawn, `w` for the switcher, `/` to filter ([In the list](#in-the-list)).
|
|
1278
|
+
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.
|
|
1279
|
+
3. **Always:** [the leader](#the-leader), `Ctrl+X` then a key, in every terminal.
|
|
1280
|
+
|
|
1281
|
+
### Every action's keys
|
|
1282
|
+
|
|
1283
|
+
The same keys in `oats tui` and in OATS Desktop. A column per way in: the
|
|
1284
|
+
list's key (the Desktop's sidebar has the same, but `Ctrl+K`), the chord in
|
|
1285
|
+
each family on Linux and Windows, the chord on macOS (the Desktop's;
|
|
1286
|
+
`oats tui` has those without ⌘, the ⌥ arrows: [Chords on
|
|
1287
|
+
macOS](#chords-on-macos)), and the key after the leader. `–` is no key of
|
|
1288
|
+
that kind.
|
|
1289
|
+
|
|
1290
|
+
| Action | In the list | Alt (default) | Ctrl+Alt | Ctrl+Shift | macOS | The leader then |
|
|
1291
|
+
|---|---|---|---|---|---|---|
|
|
1292
|
+
| the palette | `Ctrl+K` | `Alt+K` | `Ctrl+Alt+K` | `Ctrl+Shift+K` | `⌘K` | `k`, `Space` |
|
|
1293
|
+
| spawn an agent (the Desktop's Quick Open) | `n` | `Alt+P` | `Ctrl+Alt+P` | `Ctrl+Shift+P` | `⌘P` | `n` |
|
|
1294
|
+
| the list of workspaces (`w` there: the switcher) | `w` | `Alt+O` | `Ctrl+Alt+O` | `Ctrl+Shift+S` | `⌥⌘O` | `o` |
|
|
1295
|
+
| the workspace before, after | – | `Alt+Up`, `Alt+Down` | – | – | `⌥↑`, `⌥↓` | `Up`, `Down` |
|
|
1296
|
+
| zoom the shown terminal | `z` | `Alt+Z` | `Ctrl+Alt+Z` | `Ctrl+Shift+M` | `⌥⌘Z` | `z` |
|
|
1297
|
+
| close the shown terminal's tab | `c` | `Alt+W` | `Ctrl+Alt+W` | `Ctrl+Shift+W` | `⌘W` | `w` |
|
|
1298
|
+
| split side by side | `\|` | `Alt+E` | `Ctrl+Alt+E` | `Ctrl+Shift+E` | `⌘\` | `\|` |
|
|
1299
|
+
| split one above the other | `-` | `Alt+Shift+E` | `Ctrl+Alt+Shift+E` | `Ctrl+Shift+D` | `⌘⇧\` | `-` |
|
|
1300
|
+
| the next group | – | `Alt+Shift+Right` | `Ctrl+Alt+A` | `Ctrl+Alt+A` | `⌥⇧→` | `Tab` |
|
|
1301
|
+
| the previous group | – | `Alt+Shift+Left` | `Ctrl+Alt+Shift+A` | `Ctrl+Alt+Shift+A` | `⌥⇧←` | `Shift+Tab` |
|
|
1302
|
+
| the filter | `/` | `Alt+F` | `Ctrl+Alt+F` | `Ctrl+Alt+F` | `⌘F` | `/` |
|
|
1303
|
+
| 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` | `⌥⌘↑`, `⌥⌘↓` | – |
|
|
1304
|
+
| the tab before, after | `[`, `]` | `Alt+Left`, `Alt+Right` | `Alt+Shift+Left`, `Alt+Shift+Right` | `Alt+Shift+Left`, `Alt+Shift+Right` | `⌥←`, `⌥→` | `Left`, `Right` |
|
|
1305
|
+
| 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` | – |
|
|
1306
|
+
| an instance's name and colour (OATS Desktop only) | – | `Alt+R` | `Ctrl+Alt+R` | `Ctrl+Alt+R` | `⌥⌘R` | – |
|
|
1307
|
+
| move the tab to the other group | – | – | – | – | – | `m` |
|
|
1308
|
+
| close the empty group | – | – | – | – | – | `x` |
|
|
1309
|
+
| stop, restart, start, retire | `X`, `R`, `S`, `D` | – | – | – | – | `X`, `R`, `S`, `D` |
|
|
1310
|
+
| spawn another of the soul | `N` | – | – | – | – | `N` |
|
|
1311
|
+
| the Instances, Souls, Capabilities views | `1`, `2`, `3` | – | – | – | – | `1`, `2`, `3` |
|
|
1312
|
+
| the help | `?` | – | – | – | – | `?` |
|
|
1313
|
+
| the list | `Esc` | – | – | – | – | `Esc` |
|
|
1314
|
+
|
|
1315
|
+
The Ctrl+Shift family moves seven of the Ctrl+Alt family's chords to
|
|
1316
|
+
Ctrl+Shift. The others keep their Ctrl+Alt key: Ctrl+Shift with an arrow
|
|
1317
|
+
selects text in inputs and editors, Ctrl+Shift with a digit is a shifted
|
|
1318
|
+
symbol on most layouts, and Ctrl+Shift+A and Ctrl+Shift+F are taken by
|
|
1319
|
+
terminals (kitty, Ghostty, and for F Alacritty and GNOME Terminal too) and
|
|
1320
|
+
by agents (Codex's Ctrl+Shift+A, pi's Ctrl+Shift+F). The workspace moves
|
|
1321
|
+
and the previous group are new in this version. The workspace moves are
|
|
1322
|
+
`Alt+Up` and `Alt+Down` in the Alt family alone: the Ctrl+Alt and
|
|
1323
|
+
Ctrl+Shift families are for whoever needs Alt in their programs, so they
|
|
1324
|
+
leave those keys to them, and the leader's `Up` and `Down` move between
|
|
1325
|
+
workspaces there. The previous group is `Alt+Shift+Left` in the Alt
|
|
1326
|
+
family, beside `Alt+Shift+Right` for the next, and `Ctrl+Alt+Shift+A` in
|
|
1327
|
+
the other two, beside `Ctrl+Alt+A`. On macOS the moves between tabs,
|
|
1328
|
+
groups and workspaces are ⌥ with an arrow, in both clients; the letters
|
|
1329
|
+
and digits keep ⌘, since ⌥ with one types a character.
|
|
1330
|
+
`Alt+R` (`Ctrl+Alt+R` in the other families) is the Desktop's alone:
|
|
1331
|
+
`oats tui` has no such action and binds no key for it. The list's own keys for moving and reading are in
|
|
1332
|
+
[In the list](#in-the-list). The tables come from
|
|
1333
|
+
`packages/client/keymap.mjs` (`CHORDS`, `PLAIN_KEYS`, `LEADER_TABLE`), which
|
|
1334
|
+
both clients read.
|
|
1335
|
+
|
|
1336
|
+
### Which family for my terminal
|
|
1337
|
+
|
|
1338
|
+
For `oats tui`, on Linux and Windows. `✓` is a family whose chords reach
|
|
1339
|
+
`oats tui` in that terminal, `✗` one whose chords do not, with the reason.
|
|
1340
|
+
The leader works in all of them. In OATS Desktop every family works. The
|
|
1341
|
+
Alt family needs no kitty keyboard protocol: `Alt` with a letter or a digit
|
|
1342
|
+
is `Esc` and the key, and the Alt arrows have sequences of their own, in
|
|
1343
|
+
every terminal below.
|
|
1344
|
+
|
|
1345
|
+
| Terminal | Alt (default) | Ctrl+Alt | Ctrl+Shift |
|
|
1346
|
+
|---|---|---|---|
|
|
1347
|
+
| foot | ✓ | ✓ | ✓ |
|
|
1348
|
+
| Alacritty | ✓ | ✓ | ✓ |
|
|
1349
|
+
| 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 |
|
|
1350
|
+
| kitty | ✓ | ✓ | ✗ kitty takes Ctrl+Shift+K, P, S, W and E for itself; W closes its window, `oats tui` with it |
|
|
1351
|
+
| 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 |
|
|
1352
|
+
| 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 |
|
|
1353
|
+
| 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 |
|
|
1354
|
+
| 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 |
|
|
1355
|
+
|
|
1356
|
+
Where a terminal takes `Alt` with a digit, the leader then `Left` or
|
|
1357
|
+
`Right` and `Alt+Left`, `Alt+Right` still go from tab to tab, or choose
|
|
1358
|
+
Ctrl+Alt. On macOS `oats tui` has the ⌥ arrows alone, and which macOS
|
|
1359
|
+
terminals send them is in [Chords on macOS](#chords-on-macos); a macOS
|
|
1360
|
+
terminal sends Option with a letter as a character (`Option+K` is `˚`)
|
|
1361
|
+
unless it is set to send Option as Meta (Terminal.app's "Use Option as
|
|
1362
|
+
Meta key", iTerm2's Option key "Esc+"), and then the program in the
|
|
1363
|
+
terminal gets it. Each terminal's defaults at the release
|
|
1364
|
+
[the full matrix](#which-terminals-let-the-chords-through) names.
|
|
1365
|
+
|
|
1366
|
+
<a id="switch-to-ctrlshift"></a>
|
|
1367
|
+
|
|
1368
|
+
### Switch family
|
|
1369
|
+
|
|
1370
|
+
On Linux and Windows. macOS has no choice: the Desktop keeps its ⌘ chords
|
|
1371
|
+
and its ⌥ arrows there, and `oats tui` the ⌥ arrows ([Chords on
|
|
1372
|
+
macOS](#chords-on-macos)) and the leader.
|
|
1373
|
+
|
|
1374
|
+
- **In OATS Desktop:** the Shortcuts page (`Ctrl+,`), at its top, **Shortcut
|
|
1375
|
+
family, shared with oats tui**: **Alt (default)**, **Ctrl+Alt (for
|
|
1376
|
+
programs that read Alt)** or **Ctrl+Shift (foot, Alacritty)**. The
|
|
1377
|
+
Desktop writes the file below and switches its keys at once. A change by
|
|
1378
|
+
hand reaches the Desktop when it next gets the focus.
|
|
1379
|
+
- **Or by hand:** write `$OATS_HOME_DIR/config/keys.json`, else
|
|
1380
|
+
`~/.oats/config/keys.json`, beside [`tui.json`](#change-the-keys-tuijson):
|
|
1381
|
+
|
|
1382
|
+
```json
|
|
1383
|
+
{ "chords": "ctrl+alt" }
|
|
1384
|
+
```
|
|
1385
|
+
|
|
1386
|
+
or `"ctrl+shift"`. `"alt"` is the default, and no file, or a file with no
|
|
1387
|
+
`chords`, is the default too.
|
|
1388
|
+
- **A choice is kept.** A keys.json that says `"ctrl+alt"`, written by the
|
|
1389
|
+
Desktop or by hand before this version, when Ctrl+Alt was the default,
|
|
1390
|
+
keeps the Ctrl+Alt family with the keys it had. Only a user who never
|
|
1391
|
+
chose moves to Alt. An older client that does not know the Alt family
|
|
1392
|
+
reads `"chords": "alt"` as a value it cannot take, so it binds its own
|
|
1393
|
+
default and says so.
|
|
1394
|
+
- **`oats tui` reads it at its start:** restart it after a change, from the
|
|
1395
|
+
Desktop or by hand.
|
|
1396
|
+
- **Nothing to fix when it is wrong.** A file that cannot be read or is
|
|
1397
|
+
larger than 16 KiB, one that is not a JSON object, one with another
|
|
1398
|
+
value: each means Alt, and the help says why (`keys.json: unknown chords
|
|
1399
|
+
value, using Alt`). A missing file is the default with nothing to say. The
|
|
1400
|
+
Desktop changes only `chords` and keeps every other key in the file; a
|
|
1401
|
+
file it cannot keep whole it leaves as it is, and says so.
|
|
1402
|
+
- **It is the clients' file.** The kernel never reads it, and `tui.json`
|
|
1403
|
+
does not hold it.
|
|
1404
|
+
- **Your own keys still win, row by row.** A key you give an action in
|
|
1405
|
+
`tui.json`'s `keys` is not bound as a chord, and an action you rebind in
|
|
1406
|
+
the Desktop's shortcuts editor keeps your key in every family; the
|
|
1407
|
+
editor shows a clash with a key a family takes.
|
|
1408
|
+
- **In `oats tui` the Ctrl+Alt and Ctrl+Shift families need the kitty
|
|
1409
|
+
keyboard protocol** ([Chords](#chords)). Without it `Ctrl+Alt+K` is `Esc`
|
|
1410
|
+
then `Ctrl+K`, and a Ctrl+Shift letter is the Ctrl letter, so the TUI
|
|
1411
|
+
binds none of them: only the Alt+Shift arrows, `Alt+Up` and `Alt+Down`
|
|
1412
|
+
are chords, and the leader does the rest. The Alt family needs nothing.
|
|
1413
|
+
- **The help says which family is in force.** In `oats tui` the help (`?`)
|
|
1414
|
+
opens its chords with a line: `Shortcuts: Alt. To leave Alt to the
|
|
1415
|
+
programs in your terminals, set "chords": "ctrl+alt" in keys.json (or
|
|
1416
|
+
"ctrl+shift", for foot and Alacritty) and restart.`, or `Shortcuts:
|
|
1417
|
+
Ctrl+Alt, from keys.json.` (`Ctrl+Shift`, the same way), or, in a terminal
|
|
1418
|
+
that does not confirm the protocol, `Shortcuts: Ctrl+Alt, from keys.json,
|
|
1419
|
+
but this terminal does not confirm the kitty keyboard protocol: use the
|
|
1420
|
+
leader.` The Desktop's Shortcuts page shows the choice, `oats tui uses it
|
|
1421
|
+
from its next start.` under it, and the same note when the file was not
|
|
1422
|
+
taken.
|
|
1423
|
+
|
|
1424
|
+
### What the Alt family takes
|
|
1425
|
+
|
|
1426
|
+
The Alt family's chords are keys that programs in a terminal read: the
|
|
1427
|
+
TUI takes them from every focus, an agent's terminal included, and the
|
|
1428
|
+
program never gets them. These are the keys it takes, by the programs' own
|
|
1429
|
+
key documentation (researched 2026-10-23; sources below). "Esc, then the
|
|
1430
|
+
key" works where the program says an `Esc` prefix is Meta: readline, zsh,
|
|
1431
|
+
Emacs and irssi do. Typed as two keys apart (more than 10 ms), `Esc` then
|
|
1432
|
+
the key reaches the program as those two bytes ([Chords](#chords)). Where a
|
|
1433
|
+
program's docs don't say, the way is marked unknown, and the Ctrl+Alt
|
|
1434
|
+
family gives the key back ([Switch family](#switch-family)). An Alt key no
|
|
1435
|
+
chord holds (`Alt+B`, `Alt+D`, `Alt+T`, `Alt+.`) is still the program's.
|
|
1436
|
+
|
|
1437
|
+
Unlike the Desktop's terminal, which sends an Alt arrow as the Ctrl arrow,
|
|
1438
|
+
the terminal you run `oats tui` in sends the Alt arrows as `CSI 1;3` (`Esc
|
|
1439
|
+
[1;3C` for `Alt+Right`), which programs read. So the TUI takes the Alt
|
|
1440
|
+
arrows from them too, in the Alt family. All four go back to the programs
|
|
1441
|
+
in the Ctrl+Alt and Ctrl+Shift families: `Alt+Up` and `Alt+Down`, the
|
|
1442
|
+
workspace moves, are the Alt family's alone.
|
|
1443
|
+
|
|
1444
|
+
| Program | Key the Alt family takes | What the program does with it | How it still gets it |
|
|
1445
|
+
|---|---|---|---|
|
|
1446
|
+
| 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 |
|
|
1447
|
+
| Claude Code | `Alt+O` | fast mode on or off | as `Alt+P` |
|
|
1448
|
+
| Claude Code | `Alt+F` | forward a word | as `Alt+P` |
|
|
1449
|
+
| 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 |
|
|
1450
|
+
| Codex | `Alt+F` | a word right | `Ctrl+Right`, its other key for it |
|
|
1451
|
+
| 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 |
|
|
1452
|
+
| Codex | `Alt+Up` | edit the queued message | `Shift+Left` |
|
|
1453
|
+
| Codex | `Alt+Down` | back through the prompt stack | `Shift+Right` |
|
|
1454
|
+
| pi | `Alt+F` | a word right | `Esc`, then `f`: pi reads `ESC f` as a word right |
|
|
1455
|
+
| 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` |
|
|
1456
|
+
| 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` |
|
|
1457
|
+
| pi | `Alt+Down` | in the model selector, move a model down | `Esc`, then `n`, which pi reads as `Alt+Down` |
|
|
1458
|
+
| bash (readline) | `Alt+P`, `Alt+F` | search history back; forward a word | `Esc`, then `p` or `f` |
|
|
1459
|
+
| bash (readline) | `Alt+1` to `Alt+9` | a numeric argument | `Esc`, then the digit |
|
|
1460
|
+
| bash (readline) | `Alt+Left`, `Alt+Right` | a word back or forward | `Esc`, then `b` or `f` |
|
|
1461
|
+
| 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 |
|
|
1462
|
+
| zsh (emacs keymap) | `Alt+1` to `Alt+9` | a numeric argument | `Esc`, then the digit |
|
|
1463
|
+
| 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 |
|
|
1464
|
+
| irssi | `Alt+K`, `P`, `F` | erase completion; page back; forward a word | `Esc`, then the key |
|
|
1465
|
+
| 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 |
|
|
1466
|
+
| WeeChat | `Alt+1` to `Alt+9` | go to buffer 1 to 9 | unknown; switch to Ctrl+Alt |
|
|
1467
|
+
| 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 |
|
|
1468
|
+
| WeeChat | `Alt+Left`, `Alt+Up`; `Alt+Right`, `Alt+Down` | the buffer before; after | `F5`, `F6` |
|
|
1469
|
+
| 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 |
|
|
1470
|
+
| 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 |
|
|
1471
|
+
| Emacs | `Alt+1` to `Alt+9` | a numeric argument | `Esc`, then the digit |
|
|
1472
|
+
| Emacs | `Alt+Left`, `Alt+Right` | a word left or right | `Esc`, then `b` or `f` |
|
|
1473
|
+
|
|
1474
|
+
Not taken from these programs, by their docs: `Alt+K`, `Z`, `W`, `E` and `R`
|
|
1475
|
+
in Claude Code; the Alt+Shift arrows everywhere above but in WeeChat's
|
|
1476
|
+
cursor mode; `Alt+O` in Emacs since 28; `Alt+A` from every one of them,
|
|
1477
|
+
since the Alt family leaves it alone (the next group is `Alt+Shift+Right`
|
|
1478
|
+
there); and `Alt+R` from every one of them in `oats tui`, which binds no
|
|
1479
|
+
key for the Desktop's `edit-instance` ([Chords](#chords)): Codex's raw
|
|
1480
|
+
output, readline's revert-line, WeeChat's delete-line and Emacs's
|
|
1481
|
+
move-to-window-line keep it here, though the Desktop takes it. On macOS only
|
|
1482
|
+
the arrow rows apply: there `oats tui` takes the ⌥ arrows alone, where the
|
|
1483
|
+
terminal sends them as such ([Chords on macOS](#chords-on-macos)).
|
|
1484
|
+
|
|
1485
|
+
**Inside tmux.** `oats tui` run in a tmux pane gets its keys through tmux,
|
|
1486
|
+
which reads an `Esc` followed by a key within its `escape-time` (10 ms by
|
|
1487
|
+
default in tmux 3.7c) as that key with Alt, and passes it on as one. With
|
|
1488
|
+
a large `escape-time` (some configurations set 500 ms), `Esc` then `k`
|
|
1489
|
+
typed quickly is `Alt+K` and opens the palette, and an `Esc` pressed alone
|
|
1490
|
+
reaches `oats tui` only when that time is over. With the default, as
|
|
1491
|
+
outside tmux, only one keypress is a chord.
|
|
1492
|
+
|
|
1493
|
+
Sources: Claude Code [interactive mode](https://code.claude.com/docs/en/interactive-mode)
|
|
1494
|
+
and [keybindings](https://code.claude.com/docs/en/keybindings); Codex
|
|
1495
|
+
[`keymap.rs`](https://github.com/openai/codex/blob/d6817454d76885e9d0e118bbf82e507aed6f715a/codex-rs/tui/src/keymap.rs)
|
|
1496
|
+
and [`app/input.rs`](https://github.com/openai/codex/blob/d6817454d76885e9d0e118bbf82e507aed6f715a/codex-rs/tui/src/app/input.rs);
|
|
1497
|
+
pi [`keybindings.md`](https://github.com/badlogic/pi-mono/blob/42cb822f1c5d3153069dd0661bfd297424666cf1/packages/coding-agent/docs/keybindings.md)
|
|
1498
|
+
and [`keys.ts`](https://github.com/badlogic/pi-mono/blob/42cb822f1c5d3153069dd0661bfd297424666cf1/packages/tui/src/keys.ts);
|
|
1499
|
+
the [Readline manual](https://tiswww.case.edu/php/chet/readline/readline.html)
|
|
1500
|
+
("Typing 'ESC f' is equivalent to typing M-f") and readline 8.3's `readline.c`
|
|
1501
|
+
for the Alt arrows; the [zsh line editor](https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html);
|
|
1502
|
+
irssi's [startup HOWTO](https://github.com/irssi/irssi/blob/43f1727ef9fe1cb51d5031ee2dd0e1965217e4cb/docs/startup-HOWTO.txt)
|
|
1503
|
+
and [`gui-readline.c`](https://github.com/irssi/irssi/blob/43f1727ef9fe1cb51d5031ee2dd0e1965217e4cb/src/fe-text/gui-readline.c);
|
|
1504
|
+
the [WeeChat user guide](https://weechat.org/files/doc/weechat/stable/weechat_user.en.html#key_bindings) (4.10.1);
|
|
1505
|
+
[tmux(1)](https://man7.org/linux/man-pages/man1/tmux.1.html); the
|
|
1506
|
+
[Emacs manual](https://www.gnu.org/software/emacs/manual/html_node/emacs/User-Input.html)
|
|
1507
|
+
(ESC as Meta) and its Sentences, Words, Moving Point, Other Kill Commands and
|
|
1508
|
+
Arguments nodes.
|
|
1509
|
+
|
|
1510
|
+
<a id="what-the-option-takes-from-an-agent"></a>
|
|
1511
|
+
|
|
1512
|
+
### What the Ctrl+Shift family takes from an agent
|
|
1513
|
+
|
|
1514
|
+
With the Ctrl+Shift family, both clients take its seven Ctrl+Shift chords
|
|
1515
|
+
from every focus, an agent's terminal included: the agent never gets them.
|
|
1516
|
+
|
|
1517
|
+
- **Of the agents' own keys, that is one:** pi's Ctrl+Shift+P (previous
|
|
1518
|
+
model, [pi's keys](https://github.com/earendil-works/pi/blob/26293e74f664c2cfb731b22a653cccf852830e00/packages/coding-agent/docs/keybindings.md#L154))
|
|
1519
|
+
spawns an agent instead. No other Ctrl+Shift key of Claude Code, Codex or
|
|
1520
|
+
pi is among the seven.
|
|
1521
|
+
- **The plain Ctrl letters stay the agent's:** `Ctrl+K`, `Ctrl+P`,
|
|
1522
|
+
`Ctrl+W` and the rest.
|
|
1523
|
+
- **A Ctrl+Shift chord is only ever the protocol's report of it,** with
|
|
1524
|
+
Shift in it. Without the protocol a terminal sends Ctrl+Shift+D as
|
|
1525
|
+
`Ctrl+D` (end of input) and Ctrl+Shift+M as `Enter`; those stay the
|
|
1526
|
+
agent's, and the list's.
|
|
1527
|
+
- **IBus 1.5.24 and older** opens its emoji picker on Ctrl+Shift+E
|
|
1528
|
+
([its setting](https://github.com/ibus/ibus/blob/1.5.24/data/dconf/org.freedesktop.ibus.gschema.xml#L186);
|
|
1529
|
+
a newer IBus may keep an old setting) before either client sees it. There
|
|
1530
|
+
the leader then `|` splits side by side.
|
|
1531
|
+
|
|
1532
|
+
### In the list
|
|
1533
|
+
|
|
1043
1534
|
| Key | Does |
|
|
1044
1535
|
|---|---|
|
|
1045
1536
|
| `Up` `k`, `Down` `j` | move the selection; with the detail focused, scroll it |
|
|
@@ -1053,16 +1544,16 @@ The line after leaving says so and names `oats status` to see it.
|
|
|
1053
1544
|
| `1` | the Instances view |
|
|
1054
1545
|
| `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
|
|
1055
1546
|
| `3` | [the Capabilities view](#the-capabilities-view); `Esc` or `1` goes back |
|
|
1056
|
-
| `w` | opens [the switcher](#the-switcher) |
|
|
1547
|
+
| `w` | gives [the list of workspaces](#the-list-of-workspaces) the focus; `w` there opens [the switcher](#the-switcher) |
|
|
1057
1548
|
| `Delete` | in the switcher, asks whether to remove the selected row from this computer's list of deployments; `Enter` removes it |
|
|
1058
1549
|
| `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 |
|
|
1059
1550
|
| `z` | gives the shown terminal the focus and the whole screen |
|
|
1060
1551
|
| `c` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
1061
1552
|
| `[`, `]` | in the Instances view, shows the tab before or after the shown one |
|
|
1062
1553
|
| `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
|
|
1063
|
-
| `
|
|
1554
|
+
| `Ctrl+X` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
|
|
1064
1555
|
| `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
|
|
1065
|
-
| `
|
|
1556
|
+
| `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 |
|
|
1066
1557
|
| `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
|
|
1067
1558
|
| `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
|
|
1068
1559
|
| `N` | spawns another of the selected instance's soul: its preview |
|
|
@@ -1084,68 +1575,87 @@ instance can always be read, however many they are. The selection stays
|
|
|
1084
1575
|
where it is, and the list returns to it at the next key that moves it.
|
|
1085
1576
|
|
|
1086
1577
|
The help screen is generated from the table the program acts on, so it
|
|
1087
|
-
always lists the keys that work, the leader's among them, the
|
|
1088
|
-
|
|
1578
|
+
always lists the keys that work, the leader's among them, the
|
|
1579
|
+
[chords](#chords) (first of all while every chord of the family in force
|
|
1580
|
+
is read: always in the Alt family, and in the others while your terminal
|
|
1581
|
+
confirms the kitty keyboard protocol), the palette's and the spawn prompt's, with the
|
|
1089
1582
|
marks and with what this version does not do. Its top row has the time of the read and the count of withheld rows
|
|
1090
1583
|
([What it shows](#what-it-shows)). The movement keys scroll it. While
|
|
1091
|
-
a terminal has the focus the table's keys are the agent's: the leader
|
|
1092
|
-
|
|
1584
|
+
a terminal has the focus the table's keys are the agent's: the leader and
|
|
1585
|
+
the chords alone are the TUI's.
|
|
1093
1586
|
|
|
1094
1587
|
### The leader
|
|
1095
1588
|
|
|
1096
1589
|
Every action is reached by keys from every focus, a terminal's too: the
|
|
1097
1590
|
leader (tui.json's `open.detachKey`), then one plain key. The leader is
|
|
1098
|
-
`
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
`
|
|
1102
|
-
|
|
1103
|
-
|
|
1591
|
+
`Ctrl+X` on every platform, as in OATS Desktop (where, on Linux and
|
|
1592
|
+
Windows, `Ctrl+X` stays Cut in a text field), unless
|
|
1593
|
+
[`tui.json`](#change-the-keys-tuijson) names another key: `M-o` names
|
|
1594
|
+
`Alt+O` and `C-\` names `Ctrl+\`, the leaders of earlier versions on
|
|
1595
|
+
Linux and Windows and on macOS. `Ctrl+X` is Emacs' prefix key: the same
|
|
1596
|
+
key on every platform and keyboard layout, and one byte in every terminal
|
|
1597
|
+
without the kitty keyboard protocol, so it needs neither the protocol nor
|
|
1598
|
+
any timing (below). Its cost is the programs
|
|
1599
|
+
that read `Ctrl+X` themselves, which take the leader twice (the
|
|
1600
|
+
leader again types it into the terminal): in the shell `Ctrl+X Ctrl+E`,
|
|
1601
|
+
which edits the command line in your editor, is `Ctrl+X` twice, then
|
|
1602
|
+
`Ctrl+E`, and nano exits with `Ctrl+X` twice.
|
|
1104
1603
|
|
|
1105
1604
|
| The leader, then | Does |
|
|
1106
1605
|
|---|---|
|
|
1107
1606
|
| `k` or `Space` | opens [the palette](#the-palette) |
|
|
1108
1607
|
| `1`, `2`, `3` | the Instances, Souls and Capabilities views |
|
|
1109
|
-
| `Up`, `Down` | opens the
|
|
1110
|
-
| `Left`, `Right` | shows the tab before or after the shown one; the
|
|
1608
|
+
| `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)) |
|
|
1609
|
+
| `Left`, `Right` | shows the tab before or after the shown one; the tab bar does not wrap, and the focus stays where it was |
|
|
1111
1610
|
| `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
|
|
1112
1611
|
| `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
1113
1612
|
| `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
|
|
1114
1613
|
| `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 |
|
|
1614
|
+
| `Shift+Tab` | goes to the previous group, as `Tab` goes to the next: with two groups at most, the same as `Tab` |
|
|
1115
1615
|
| `m` | with two groups, moves the shown tab to the other group, and goes there |
|
|
1116
1616
|
| `x` | closes the focused group while it is empty |
|
|
1117
1617
|
| `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 |
|
|
1118
1618
|
| `n`, `N` | [spawns an agent](#spawning-an-agent); `N` of the shown terminal's soul from its focus |
|
|
1119
1619
|
| `/` | the filter |
|
|
1120
|
-
| `o` | [the
|
|
1620
|
+
| `o` | gives [the list of workspaces](#the-list-of-workspaces) the focus |
|
|
1121
1621
|
| `?` | the help |
|
|
1122
1622
|
| `Esc` | gives the list the focus |
|
|
1123
|
-
| the leader again | types the leader into the terminal that has the focus, which keeps it; with the list focused, only
|
|
1124
|
-
|
|
1125
|
-
- **While the leader waits** for its key
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
panel has one group, `Tab` with two, then `m` while the focused group
|
|
1130
|
-
shows a tab or `x` while it is empty, and the leader again while a
|
|
1131
|
-
terminal has the focus). On a short screen it gives up rows before its
|
|
1132
|
-
last. It waits
|
|
1133
|
-
with no time limit. A key not in the table cancels it and is dropped:
|
|
1134
|
-
nothing is typed.
|
|
1623
|
+
| the leader again | types the leader into the terminal that has the focus, which keeps it; with the list focused, only cancels the leader |
|
|
1624
|
+
|
|
1625
|
+
- **While the leader waits** for its key nothing on the screen changes:
|
|
1626
|
+
the cheat sheet stays as it was, and the help (`?`) lists the whole
|
|
1627
|
+
table above. It waits with no time limit. A key not in the table
|
|
1628
|
+
cancels it and is dropped: nothing is typed.
|
|
1135
1629
|
- **Only a key in a later read counts.** A key that came in the same read of
|
|
1136
1630
|
input as the leader cancels it and is dropped, with the rest of that
|
|
1137
|
-
read, so a paste can never run a command.
|
|
1138
|
-
the
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
the
|
|
1147
|
-
|
|
1148
|
-
|
|
1631
|
+
read, so a paste can never run a command. The line under the list of workspaces says
|
|
1632
|
+
so, until the next key of any kind (one typed to an agent too) or a resize:
|
|
1633
|
+
`Ctrl+X and the next key came in one read, so nothing ran: press them
|
|
1634
|
+
one after the other.` In a terminal the bytes before the leader in that
|
|
1635
|
+
read still go to the agent. A leader inside a bracketed paste is pasted
|
|
1636
|
+
text.
|
|
1637
|
+
- **`Ctrl+X` is one byte.** Without the kitty keyboard protocol
|
|
1638
|
+
([Chords](#chords)) every terminal sends it as `0x18`, which no read
|
|
1639
|
+
splits and nothing has to time; under the protocol it is `CSI 120;5u`,
|
|
1640
|
+
which the TUI reads as `Ctrl+X` too. `Ctrl+Shift+X` and `Ctrl+Alt+X` are
|
|
1641
|
+
not the leader under the protocol: each is a key of its own, which
|
|
1642
|
+
nothing binds, and in a terminal it reaches the agent as the bytes it
|
|
1643
|
+
sends without the protocol. Without it most terminals send `0x18` for
|
|
1644
|
+
`Ctrl+Shift+X` as for `Ctrl+X`, so there it is the leader. In a terminal
|
|
1645
|
+
`Esc` then `0x18` in one read is `Ctrl+Alt+X`, and goes to the agent.
|
|
1646
|
+
- **An Alt leader is one keypress only.** A leader `tui.json` names with
|
|
1647
|
+
`M-`, such as `M-o` (`Alt+O`), is sent by a terminal as `Esc` then `o`.
|
|
1648
|
+
A leader that is a chord of the family in force is the leader, and that
|
|
1649
|
+
chord is not bound: with `M-o`, `Alt+O` is the leader, and the leader
|
|
1650
|
+
then `o` gives the list of workspaces the focus.
|
|
1651
|
+
Those bytes count as the leader when they arrive in one read, or split
|
|
1652
|
+
across reads within 10 ms. An `Esc` then `o` typed as two keys reaches
|
|
1653
|
+
the agent unchanged: in vim that is "leave insert mode, open a line".
|
|
1654
|
+
Over a slow link two keys typed apart can arrive in one read and act as
|
|
1655
|
+
the leader, and one `Alt+O` can arrive split and reach the agent as `Esc`
|
|
1656
|
+
and `o`. Under the kitty keyboard protocol there is no timing: `Alt+O` is
|
|
1657
|
+
one sequence and `Esc` another, so each is told exactly, in a terminal
|
|
1658
|
+
and in the list.
|
|
1149
1659
|
- **In the list no leader is needed:** the plain keys work as they always
|
|
1150
1660
|
have, and the leader works there too.
|
|
1151
1661
|
- **What was open under it is settled first,** from whatever view: a
|
|
@@ -1159,47 +1669,129 @@ to use Option as Meta.
|
|
|
1159
1669
|
|
|
1160
1670
|
### Chords
|
|
1161
1671
|
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
the
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1672
|
+
A chord does in one keypress what the leader then a key does, from every
|
|
1673
|
+
focus, an agent's terminal too, and never reaches the agent. One pair has
|
|
1674
|
+
no leader key: `Alt+Shift+Up` and `Alt+Shift+Down` open the terminal of
|
|
1675
|
+
the instance before or after, in the list as it is drawn, the focus in it
|
|
1676
|
+
(from the shown terminal's instance, or from the selection when none is
|
|
1677
|
+
open; its tab when it has one, else a new [tab](#tabs); rows that cannot be
|
|
1678
|
+
opened are passed over, and the list does not wrap), since the leader's
|
|
1679
|
+
`Up` and `Down` move between workspaces. On macOS, where that pair holds ⌘
|
|
1680
|
+
(`⌥⌘↑`, `⌥⌘↓`), which a terminal never passes on, the list's `Up` or
|
|
1681
|
+
`Down` then `Enter` does it. The OATS
|
|
1682
|
+
Desktop has the same chords (`CHORDS` in `packages/client/keymap.mjs`, which
|
|
1683
|
+
both read; the TUI keeps no copy). The leader stays the key that always
|
|
1684
|
+
works, and the one for help, the views and the acts (stop, restart, start,
|
|
1685
|
+
retire), which have no chord.
|
|
1686
|
+
|
|
1687
|
+
Every chord, in every family, with what it does and the leader's key for
|
|
1688
|
+
it, is in [Every action's keys](#every-actions-keys). While the palette is
|
|
1689
|
+
open, `Alt+Shift+Up` and `Alt+Shift+Down` move between its groups instead
|
|
1690
|
+
([The palette](#the-palette)).
|
|
1691
|
+
|
|
1692
|
+
`CHORDS` also holds the Desktop's `edit-instance` (`Alt+R`, its name and
|
|
1693
|
+
colour dialog). The TUI has no such action, so it binds no key for it and
|
|
1694
|
+
`Alt+R` stays the agent's.
|
|
1695
|
+
|
|
1696
|
+
There are three families, one choice per user for both clients
|
|
1697
|
+
([Switch family](#switch-family)):
|
|
1698
|
+
|
|
1699
|
+
- **Alt, the default.** Alt with a letter or a digit acts, Alt with an
|
|
1700
|
+
arrow moves between tabs and workspaces, and Alt+Shift with an arrow
|
|
1701
|
+
between groups and instances. It reads in every terminal, with no
|
|
1702
|
+
protocol, and takes keys that programs in a terminal read
|
|
1703
|
+
([What the Alt family takes](#what-the-alt-family-takes)).
|
|
1704
|
+
- **Ctrl+Alt, for whoever needs Alt in their programs.** The default
|
|
1705
|
+
before this version, with its keys: Ctrl+Alt with a letter or a digit
|
|
1706
|
+
acts, and Alt+Shift with an arrow moves between tabs and instances. It
|
|
1707
|
+
leaves Alt alone, the Alt arrows included: the workspace moves have no
|
|
1708
|
+
chord here, so `Alt+Up` and `Alt+Down` reach the program (Codex's edit
|
|
1709
|
+
the queued message, pi's restore the queued messages), and the leader's
|
|
1710
|
+
`Up` and `Down` move between workspaces. No terminal in [the
|
|
1711
|
+
matrix](#which-terminals-let-the-chords-through) takes its chords by
|
|
1712
|
+
default, and no agent (Claude Code, Codex, pi) reads them. It needs the
|
|
1713
|
+
kitty keyboard protocol.
|
|
1714
|
+
- **Ctrl+Shift, for a terminal that passes Ctrl+Shift apart from Ctrl**
|
|
1715
|
+
(foot, Alacritty). Ctrl+Shift with a letter, the obvious family, is
|
|
1716
|
+
mostly the terminals' own: kitty binds 22 of those letters, Ghostty 13,
|
|
1717
|
+
and foot, GNOME Terminal, WezTerm, Konsole and Windows Terminal their
|
|
1718
|
+
own. So seven of the Ctrl+Alt family's chords move to Ctrl+Shift, for the
|
|
1719
|
+
terminals that leave those letters alone ([Which family for my
|
|
1720
|
+
terminal](#which-family-for-my-terminal)), and the others keep their
|
|
1721
|
+
Ctrl+Alt key. It needs the protocol too.
|
|
1722
|
+
|
|
1723
|
+
A chord of another family is no chord: in the Alt family `Ctrl+Alt+K`
|
|
1724
|
+
reaches the agent as it would without the TUI, and in the Ctrl+Alt family
|
|
1725
|
+
`Alt+K` does. On macOS the TUI has the ⌥ arrows alone ([Chords on
|
|
1726
|
+
macOS](#chords-on-macos)): the Desktop's other chords hold ⌘, which a
|
|
1727
|
+
terminal never passes to a program.
|
|
1728
|
+
|
|
1729
|
+
- **The Alt family in every terminal.** A terminal sends `Alt` with a
|
|
1730
|
+
letter or a digit as `Esc` then the key (`Alt+K` is `ESC k`, and
|
|
1731
|
+
`Alt+Shift+E` is `ESC E`), with the protocol or without it, and the
|
|
1732
|
+
arrows as sequences of their own (`CSI 1;3A` for `Alt+Up`, `CSI 1;4A` for
|
|
1733
|
+
`Alt+Shift+Up`). Under the protocol each is one report of its own. In the
|
|
1734
|
+
list a lone `Esc` waits 50 ms for a key after it, as it always has. In a
|
|
1735
|
+
terminal `Esc` and the key are one chord when they come in one read, or
|
|
1736
|
+
split across reads within 10 ms, as an [Alt leader](#the-leader) is: an
|
|
1737
|
+
`Esc` then `k` typed as two keys reaches the agent unchanged, so a
|
|
1738
|
+
program that reads `Esc` as Meta, as the shell does, still gets `Alt+K`
|
|
1739
|
+
that way. Over a slow link two keys typed apart can arrive in one read
|
|
1740
|
+
and act as the chord, and one chord can arrive split and reach the agent
|
|
1741
|
+
as `Esc` and the key. Inside tmux, its `escape-time` decides ([What the
|
|
1742
|
+
Alt family takes](#what-the-alt-family-takes)).
|
|
1743
|
+
- **The Ctrl+Alt and Ctrl+Shift chords only where the terminal says it
|
|
1744
|
+
can.** Without the kitty keyboard protocol a terminal sends `Ctrl+Alt+K`
|
|
1745
|
+
as `Esc` then `Ctrl+K`, the same bytes as those two keys typed for the
|
|
1746
|
+
agent, and `Ctrl+Shift+K` as `Ctrl+K`. As
|
|
1747
|
+
it takes the terminal, `oats tui` asks for the protocol with flags 1 and 4
|
|
1748
|
+
(`CSI > 5 u`) and asks the terminal which flags it has (`CSI ? u`). Only
|
|
1749
|
+
when the answer holds flag 1 does it read the protocol and take the
|
|
1750
|
+
chords of those families. With no answer within 2 seconds, or one without flag 1,
|
|
1751
|
+
it pops the protocol, and the rest of the run is as without it: of those
|
|
1752
|
+
families' chords only the arrows are taken (the Alt+Shift arrows). The
|
|
1753
|
+
answer may come split and late over a slow link, so until it comes (at
|
|
1754
|
+
most those 2 seconds) an `Esc` pressed on its own may wait for the next
|
|
1755
|
+
key or for the wait's end, as it may begin the answer.
|
|
1756
|
+
- **The help and the cheat sheet lead with the chords** while every chord
|
|
1757
|
+
of the family in force is read: always in the Alt family and on macOS,
|
|
1758
|
+
and in the others while the terminal confirms the protocol. Then the help has one
|
|
1759
|
+
row per chord, then the leader and its key ("or `Ctrl+X` then `k`"), and
|
|
1760
|
+
the leader's own section after them; a pair whose keys share their
|
|
1761
|
+
modifiers is one row (`Alt+Shift+Up/Down`), and `Ctrl+Alt+Shift+A` and
|
|
1762
|
+
`Ctrl+Alt+A` are a row each. Otherwise the leader leads, and only the
|
|
1763
|
+
chords read are listed. The help's chords open with the family in force
|
|
1764
|
+
([Switch family](#switch-family)). The cheat sheet names chords while an
|
|
1765
|
+
agent's terminal has the focus; the list's names its own keys, which need
|
|
1766
|
+
no modifier.
|
|
1767
|
+
- **Your terminal may take some first** ([the matrix](#which-terminals-let-the-chords-through)).
|
|
1768
|
+
GNOME Terminal and Konsole take `Alt+1` to `Alt+9` for their own tabs
|
|
1769
|
+
while they have two or more, and Ghostty when the tab changes. Windows
|
|
1770
|
+
Terminal takes the Alt and Alt+Shift arrows while its panes are split,
|
|
1771
|
+
and `Ctrl+Alt+1` to `Ctrl+Alt+9` for its own tabs. GNOME Terminal and the
|
|
1772
|
+
other VTE terminals, Konsole before 26.08, and WezTerm unless
|
|
1773
|
+
`enable_kitty_keyboard` is set have no protocol: there the Ctrl+Alt and
|
|
1774
|
+
Ctrl+Shift families' chords but their arrows do not reach `oats tui`.
|
|
1775
|
+
The leader works in every terminal.
|
|
1776
|
+
- **A character typed with AltGr stays a character.** On Windows `AltGr` is
|
|
1777
|
+
`Ctrl+Alt`: on a Spanish layout `Ctrl+Alt+E` types `€` and `Ctrl+Alt+2`
|
|
1778
|
+
`@`, on a Polish one `Ctrl+Alt+A` types `ą`. A key that arrives as text is
|
|
1779
|
+
never a chord: on such a layout those chords are the layout's, and the
|
|
1780
|
+
leader still does what they do. On Linux `AltGr` is a key of its own: a
|
|
1781
|
+
character it types reaches the TUI as that character, never as `Esc`
|
|
1782
|
+
then a key, so it is never an Alt chord either. On macOS Option is a key
|
|
1783
|
+
of its own.
|
|
1199
1784
|
- **Every other key reads as it does without the protocol.** `Ctrl+Shift+L`
|
|
1200
1785
|
is `Ctrl+L`, `Ctrl+Enter` is `Enter`, and so on: the protocol only adds
|
|
1201
|
-
the
|
|
1202
|
-
|
|
1786
|
+
the Ctrl+Alt and Ctrl+Shift chords of the family in force, tells an Alt
|
|
1787
|
+
chord or an Alt leader such as `Alt+O` from `Esc` then `o` exactly, and
|
|
1788
|
+
tells `Ctrl+Shift+X` from the leader `Ctrl+X` ([The leader](#the-leader)).
|
|
1789
|
+
Outside the Ctrl+Shift family its seven Ctrl+Shift letters are such keys
|
|
1790
|
+
too: `Ctrl+Shift+D` is `Ctrl+D`.
|
|
1791
|
+
- **A Ctrl+Shift chord is read from the protocol alone,** from a report
|
|
1792
|
+
that holds Shift, never from the byte a terminal sends without it:
|
|
1793
|
+
`Ctrl+D` (end of input) and `Enter` (`Ctrl+M`) stay what they are, in
|
|
1794
|
+
the Ctrl+Shift family too.
|
|
1203
1795
|
- **An agent gets what it gets without the protocol.** Every key typed
|
|
1204
1796
|
into an agent's terminal is turned back into the bytes the same key sends
|
|
1205
1797
|
without it, the legacy encoding of xterm and the terminals that follow it:
|
|
@@ -1221,22 +1813,199 @@ its own.
|
|
|
1221
1813
|
terminal: the shell at a suspend is the only one `oats tui` ever gives
|
|
1222
1814
|
it to.
|
|
1223
1815
|
|
|
1816
|
+
#### Chords on macOS
|
|
1817
|
+
|
|
1818
|
+
On macOS `oats tui` binds the chords of `CHORDS` whose key holds no ⌘, ⌥
|
|
1819
|
+
with an arrow (the product owner's call, 2026-10-23): `⌥←` and `⌥→` the tab before or
|
|
1820
|
+
after, `⌥⇧←` and `⌥⇧→` the group before or after, `⌥↑` and `⌥↓` the
|
|
1821
|
+
workspace before or after. Its help and cheat sheet say them `Alt+Left` and
|
|
1822
|
+
so on, and lead with them. The other chords hold ⌘ (`⌘K`, `⌥⌘1` to `⌥⌘9`,
|
|
1823
|
+
`⌥⌘↑`), which a terminal never passes to a program, so the TUI binds none
|
|
1824
|
+
of them. The leader does the actions it has a key for (`Ctrl+X` then `k`
|
|
1825
|
+
for the palette, for instance); the list's `Up` or `Down`, then `Enter`,
|
|
1826
|
+
steps between instances; and no key goes to a tab by its place, so no tab
|
|
1827
|
+
carries a number ([Tabs](#tabs)). ⌥ with a letter or a digit
|
|
1828
|
+
types a character on many layouts (`⌥2` is `@` on a Spanish one), so none
|
|
1829
|
+
of them is a chord. There is no family to choose: keys.json's `chords` is
|
|
1830
|
+
not read there.
|
|
1831
|
+
|
|
1832
|
+
A chord comes only where the terminal sends ⌥ with an arrow as its xterm
|
|
1833
|
+
sequence, `CSI 1;3` (`Esc [1;3D` for `⌥←`), and ⌥⇧ with one as `CSI 1;4`.
|
|
1834
|
+
Where it comes, the TUI takes it from the program in the terminal, as on
|
|
1835
|
+
Linux; where it does not, the bytes reach the program as before (`Esc b`
|
|
1836
|
+
and `Esc f` move a shell by word), and the leader does what the chord
|
|
1837
|
+
would: then `Left` or `Right` for the tabs, `Shift+Tab` or `Tab` for the
|
|
1838
|
+
groups, `Up` or `Down` for the workspaces. What each terminal sends by
|
|
1839
|
+
default, read from its source or its documentation on 2026-10-23 (their
|
|
1840
|
+
main branches):
|
|
1841
|
+
|
|
1842
|
+
| Terminal | `⌥←`, `⌥→` | `⌥↑`, `⌥↓` | `⌥⇧←`, `⌥⇧→` | For the chords |
|
|
1843
|
+
|---|---|---|---|---|
|
|
1844
|
+
| 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 |
|
|
1845
|
+
| 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 |
|
|
1846
|
+
| 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` |
|
|
1847
|
+
| kitty | the chord ([Option is Alt][kitty-option], [encoder][kitty-encoder]) | the chord | the chord | the default |
|
|
1848
|
+
| WezTerm | the chord ([config][wezterm-config], [encoder][wezterm-encoder]) | the chord | the chord | the default |
|
|
1849
|
+
| Alacritty | the chord ([Alt on named keys][alacritty-keys]) | the chord | the chord | the default |
|
|
1850
|
+
| 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 |
|
|
1851
|
+
| 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 |
|
|
1852
|
+
|
|
1853
|
+
iTerm2's, WezTerm's and Warp's rows were read from their code, not run.
|
|
1854
|
+
Neither "Use Option as Meta key" (Terminal.app) nor Option as Alt or Meta in
|
|
1855
|
+
the others (iTerm2's Left/Right Option key, Ghostty's
|
|
1856
|
+
`macos-option-as-alt`, kitty's `macos_option_as_alt`, Alacritty's
|
|
1857
|
+
`option_as_alt`, VS Code's `terminal.integrated.macOptionIsMeta`) changes
|
|
1858
|
+
what the arrows send, by those terminals' code; for Terminal.app it is
|
|
1859
|
+
unknown. The TUI reads no other bytes as these chords: `Esc b` and `Esc f`
|
|
1860
|
+
are readline's word moves, and `CSI 1;5A` is `Ctrl+Up`.
|
|
1861
|
+
|
|
1862
|
+
[nsterm]: https://github.com/ThomasDickey/ncurses-snapshots/blob/master/misc/terminfo.src
|
|
1863
|
+
[apple-keys]: https://support.apple.com/guide/terminal/keyboard-shortcuts-trmlshtcts/mac
|
|
1864
|
+
[apple-kbd]: https://support.apple.com/guide/terminal/profiles-keyboard-settings-trmlkbrd/mac
|
|
1865
|
+
[iterm-profile]: https://github.com/gnachman/iTerm2/blob/7f4ff739721f95d0b93003d8701c4523a7edf261/sources/Settings/iTermProfilePreferences.m#L1254
|
|
1866
|
+
[iterm-encoder]: https://github.com/gnachman/iTerm2/blob/7f4ff739721f95d0b93003d8701c4523a7edf261/sources/VT100/VT100Output.m#L1242
|
|
1867
|
+
[iterm-presets]: https://github.com/gnachman/iTerm2/blob/7f4ff739721f95d0b93003d8701c4523a7edf261/plists/PresetKeyMappings.plist#L127
|
|
1868
|
+
[ghostty-binds]: https://github.com/ghostty-org/ghostty/blob/08a9518340e19487bd5fdf96963583fb32f0c41f/src/config/Config.zig#L7383
|
|
1869
|
+
[ghostty-3106]: https://github.com/ghostty-org/ghostty/issues/3106
|
|
1870
|
+
[ghostty-encoder]: https://github.com/ghostty-org/ghostty/blob/08a9518340e19487bd5fdf96963583fb32f0c41f/src/input/function_keys.zig#L81
|
|
1871
|
+
[kitty-option]: https://github.com/kovidgoyal/kitty/blob/34eda431940fc8d66ffd0ada7d4a6451fdbd6699/kitty/options/definition.py#L3499
|
|
1872
|
+
[kitty-encoder]: https://github.com/kovidgoyal/kitty/blob/34eda431940fc8d66ffd0ada7d4a6451fdbd6699/kitty/key_encoding.c#L160
|
|
1873
|
+
[wezterm-config]: https://github.com/wezterm/wezterm/blob/e2a98e1b8af156988ad0ac778658ac27b60a55fb/config/src/config.rs#L461
|
|
1874
|
+
[wezterm-encoder]: https://github.com/wezterm/wezterm/blob/e2a98e1b8af156988ad0ac778658ac27b60a55fb/termwiz/src/input.rs#L421
|
|
1875
|
+
[alacritty-keys]: https://github.com/alacritty/alacritty/blob/542147067dd016fc5f49120ef0ba605a98a4e3a7/alacritty/src/input/keyboard.rs#L105
|
|
1876
|
+
[warp-encoder]: https://github.com/warpdotdev/warp/blob/1e6c3ae465d6a925a9b97ae03877aaadd159b8f1/crates/warp_terminal/src/model/escape_sequences.rs#L526
|
|
1877
|
+
[warp-binds]: https://github.com/warpdotdev/warp/blob/1e6c3ae465d6a925a9b97ae03877aaadd159b8f1/app/src/terminal/view/init.rs#L405
|
|
1878
|
+
[vscode-binds]: https://github.com/microsoft/vscode/blob/b04b50a28f70d834c4d039deb1d52dd3f9242293/src/vs/workbench/contrib/terminalContrib/sendSequence/browser/terminal.sendSequence.contribution.ts#L181
|
|
1879
|
+
|
|
1880
|
+
#### Which terminals let the chords through
|
|
1881
|
+
|
|
1882
|
+
Each terminal's documented default key bindings, read from its source or
|
|
1883
|
+
manual at the release named. `✗` is a chord the terminal takes for itself
|
|
1884
|
+
by default, `~` one it takes only in a state it names, `·` one it passes on.
|
|
1885
|
+
WT is Windows Terminal; iTerm2 and Terminal.app are on macOS, where the TUI
|
|
1886
|
+
binds the ⌥ arrows alone ([Chords on macOS](#chords-on-macos)) and the
|
|
1887
|
+
other rows are for reference.
|
|
1888
|
+
|
|
1889
|
+
| Chord | foot | kitty | Ghostty | Alacritty | GNOME Terminal | WezTerm | Konsole | WT | iTerm2 | Terminal.app |
|
|
1890
|
+
|---|---|---|---|---|---|---|---|---|---|---|
|
|
1891
|
+
| `Alt+K` `P` `O` `Z` `W` `E` `F`, `Alt+Shift+E` | · | · | · | · | · | · | · | · | – | – |
|
|
1892
|
+
| `Alt+1` to `9` | · | · | ~ on Linux its tabs, when the tab changes | · | ~ its tabs, with two or more | · | ~ its tabs, with two or more | · | – | – |
|
|
1893
|
+
| `Alt` arrows | · | · | · | · | · | · | · | ~ pane focus, passed on with one pane | · | ✗ `⌥←` `⌥→`, sent as the shell's word moves; `⌥↑` `⌥↓` unknown ([Chords on macOS](#chords-on-macos)) |
|
|
1894
|
+
| `Ctrl+Alt+K` `P` `O` `Z` `W` `E` `A` `F` | · | · | · | · | · | · | · | · | · | · |
|
|
1895
|
+
| `Ctrl+Alt+Shift+E` | · | · | · | · | · | · | · | · | · | · |
|
|
1896
|
+
| `Ctrl+Alt+1` to `9` | · | · | · | · | · | · | · | ✗ its tabs | · | · |
|
|
1897
|
+
| `Alt+Shift+` arrows | · | · | · | · | · | · | · | ~ pane resize, passed on with one pane | · | · |
|
|
1898
|
+
| 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` | – | – |
|
|
1899
|
+
| 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 |
|
|
1900
|
+
| 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 |
|
|
1901
|
+
|
|
1902
|
+
Where a terminal has no protocol, its cells for the Ctrl+Alt and
|
|
1903
|
+
Ctrl+Shift chords say only what it takes: those chords do not reach the
|
|
1904
|
+
TUI there anyway. On macOS the Alt family is not bound and there is no
|
|
1905
|
+
choice of family, hence `–`: a macOS terminal sends Option with a letter
|
|
1906
|
+
as a character unless it is set to send Option as Meta, and its arrows
|
|
1907
|
+
are in [Chords on macOS](#chords-on-macos). The three Alt rows were read from each terminal's
|
|
1908
|
+
source and manual as they stood on 2026-10-23 (their main branches), not
|
|
1909
|
+
at the releases in the last row. What the
|
|
1910
|
+
terminals take besides, near these chords:
|
|
1911
|
+
|
|
1912
|
+
- Konsole: `Ctrl+Alt+S`, `N`, `M`, `U`, `H`, `G`, `I`, `0`, `[`, `]`, `\`
|
|
1913
|
+
and `,`.
|
|
1914
|
+
- Windows Terminal: `Ctrl+Alt+,` and `Ctrl+Alt+Left`.
|
|
1915
|
+
- kitty: `Ctrl+Shift+Alt+T`. Ghostty: `Ctrl+Shift+Alt+J`, and `Ctrl+Alt`
|
|
1916
|
+
with an arrow (split focus). WezTerm: `Ctrl+Shift+Alt` with an arrow,
|
|
1917
|
+
`'` and `5`.
|
|
1918
|
+
|
|
1919
|
+
The desktops' global keys come before any terminal's. They were read
|
|
1920
|
+
for the Ctrl+Alt and Ctrl+Shift chords; "the chords above" in the last
|
|
1921
|
+
column is those, and the Alt family's were not read against them:
|
|
1922
|
+
|
|
1923
|
+
| Desktop (release read) | Takes, near the chords | Takes none of |
|
|
1924
|
+
|---|---|---|
|
|
1925
|
+
| GNOME 49 to 51 | `Ctrl+Alt` with an arrow (workspaces) and with `Shift` (move to a workspace), `Ctrl+Alt+Tab`, `Ctrl+Alt+Esc`, `Ctrl+Alt+Delete`, `Ctrl+Alt+F1` to `F12`, `Ctrl+Shift+Alt+R`, `Shift+Alt+Tab`; Ubuntu adds `Ctrl+Alt+T` | the chords above |
|
|
1926
|
+
| KDE Plasma 6.8.1 | `Ctrl+Alt+Delete`, `Ctrl+Alt+F1` to `F12`, `Alt+Shift+Tab`, `Alt+Shift+F2`; Konsole, where installed, `Ctrl+Alt+T` | the chords above |
|
|
1927
|
+
| Omarchy 4.0.4 (Hyprland) | `Ctrl+Alt+Delete`, `Ctrl+Alt+Tab`, `Ctrl+Alt+Shift+Tab`, `Alt+Shift+Tab` | the chords above |
|
|
1928
|
+
|
|
1929
|
+
From
|
|
1930
|
+
[GNOME's window manager keys](https://gitlab.gnome.org/GNOME/gsettings-desktop-schemas/-/blob/49.1/schemas/org.gnome.desktop.wm.keybindings.gschema.xml.in),
|
|
1931
|
+
[mutter's](https://gitlab.gnome.org/GNOME/mutter/-/blob/49.8/data/org.gnome.mutter.wayland.gschema.xml.in),
|
|
1932
|
+
[the shell's](https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/49.10/data/org.gnome.shell.gschema.xml.in)
|
|
1933
|
+
and [the settings daemon's](https://gitlab.gnome.org/GNOME/gnome-settings-daemon/-/blob/49.1/data/org.gnome.settings-daemon.plugins.media-keys.gschema.xml.in);
|
|
1934
|
+
[KWin's](https://invent.kde.org/plasma/kwin/-/blob/v6.8.1/src/tabbox/tabbox.cpp#L330-L335),
|
|
1935
|
+
[the session's](https://invent.kde.org/plasma/plasma-workspace/-/blob/v6.8.1/startkde/session-shortcuts/main.cpp#L40)
|
|
1936
|
+
and [KRunner's](https://invent.kde.org/plasma/plasma-workspace/-/blob/v6.8.1/krunner/org.kde.krunner.desktop.cmake#L135);
|
|
1937
|
+
and [Omarchy's](https://github.com/basecamp/omarchy/blob/v4.0.4/default/hypr/bindings/tiling.lua).
|
|
1938
|
+
|
|
1939
|
+
Sources:
|
|
1940
|
+
[foot](https://codeberg.org/dnkl/foot/src/tag/1.28.0/config.c#L3362-L3445)
|
|
1941
|
+
([protocol](https://codeberg.org/dnkl/foot/src/tag/1.28.0/CHANGELOG.md#L2222-L2245)),
|
|
1942
|
+
[kitty](https://github.com/kovidgoyal/kitty/blob/v0.49.2/kitty/options/definition.py#L3650-L4711)
|
|
1943
|
+
([protocol](https://github.com/kovidgoyal/kitty/blob/v0.49.2/docs/keyboard-protocol.rst#L302-L309)),
|
|
1944
|
+
[Ghostty](https://github.com/ghostty-org/ghostty/blob/v1.3.1/src/config/Config.zig#L6392-L7146)
|
|
1945
|
+
([protocol](https://github.com/ghostty-org/ghostty/blob/v1.3.1/src/terminal/kitty/key.zig#L79-L84)),
|
|
1946
|
+
[Alacritty](https://github.com/alacritty/alacritty/blob/v0.17.0/alacritty/src/config/bindings.rs#L430-L562)
|
|
1947
|
+
([protocol](https://github.com/alacritty/alacritty/blob/v0.17.0/CHANGELOG.md#L243)),
|
|
1948
|
+
[GNOME Terminal](https://gitlab.gnome.org/GNOME/gnome-terminal/-/blob/3.60.0/src/org.gnome.Terminal.gschema.xml#L362-L631)
|
|
1949
|
+
([VTE has no protocol](https://gitlab.gnome.org/GNOME/vte/-/work_items/2601)),
|
|
1950
|
+
[WezTerm](https://wezterm.org/config/default-keys.html)
|
|
1951
|
+
(and [commands.rs](https://github.com/wezterm/wezterm/blob/20240203-110809-5046fc22/wezterm-gui/src/commands.rs#L109-L140),
|
|
1952
|
+
which gives each ⌘ default a Ctrl+Shift twin;
|
|
1953
|
+
[protocol](https://wezterm.org/config/lua/config/enable_kitty_keyboard.html)),
|
|
1954
|
+
[Konsole](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/ViewManager.cpp#L120-L393)
|
|
1955
|
+
(and [SessionController.cpp](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/session/SessionController.cpp#L660-L955),
|
|
1956
|
+
[MainWindow.cpp](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/MainWindow.cpp#L430-L470),
|
|
1957
|
+
where `ACCEL` is Ctrl+Shift ([Shortcut_p.h](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/Shortcut_p.h#L17-L25)),
|
|
1958
|
+
and KDE's Save As, Ctrl+Shift+S;
|
|
1959
|
+
[protocol](https://invent.kde.org/utilities/konsole/-/commit/1983d2b4735d6b61b74cf85854acc1cb4d2445d5)),
|
|
1960
|
+
[Windows Terminal](https://github.com/microsoft/terminal/blob/v1.25.2733.0/src/cascadia/TerminalSettingsModel/defaults.json#L721-L803)
|
|
1961
|
+
([protocol](https://github.com/microsoft/terminal/releases/tag/v1.25.622.0)),
|
|
1962
|
+
[iTerm2](https://github.com/gnachman/iTerm2/blob/beb7cfbffeb3ae482042b08a8dd2590cd2cf4ee5/plists/DefaultGlobalKeyMap.plist)
|
|
1963
|
+
([keys](https://iterm2.com/documentation-preferences-keys.html)),
|
|
1964
|
+
[Terminal.app](https://support.apple.com/guide/terminal/keyboard-shortcuts-trmlshtcts/mac).
|
|
1965
|
+
The agents' keys:
|
|
1966
|
+
[Claude Code](https://code.claude.com/docs/en/keybindings),
|
|
1967
|
+
[Codex](https://github.com/openai/codex/blob/e1b9c9457ceca75a99b034a5df39ac48c3998d15/codex-rs/tui/src/keymap.rs#L1673-L2003),
|
|
1968
|
+
[pi](https://github.com/earendil-works/pi/blob/26293e74f664c2cfb731b22a653cccf852830e00/packages/coding-agent/docs/keybindings.md).
|
|
1969
|
+
Of the shells' keys, bash's readline binds `Ctrl+Alt+E` and `Ctrl+Alt+F`
|
|
1970
|
+
(expand the line, a word forward); under the protocol the TUI takes them
|
|
1971
|
+
from an agent's line editor, which no agent above binds them in.
|
|
1972
|
+
|
|
1224
1973
|
### The palette
|
|
1225
1974
|
|
|
1226
1975
|
The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
|
|
1227
1976
|
over a list, as the OATS Desktop's ⌘K does. From 80 columns it covers the
|
|
1228
1977
|
main area and the sidebar stays beside it, its cheat sheet naming the
|
|
1229
|
-
palette's keys (`Enter run`, `Up/Down move`, `Esc close
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
the
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1978
|
+
palette's keys (`Enter run`, `Up/Down move`, `Esc close`, then
|
|
1979
|
+
`Alt+Shift+Up/Down group`, which macOS has not); under 80 columns it covers
|
|
1980
|
+
the whole screen, with those keys on its first row, as many as fit (at 60
|
|
1981
|
+
columns `group` gives way). While it is open no terminal is drawn and the
|
|
1982
|
+
TUI reads the keys. The help lists its keys under The palette.
|
|
1983
|
+
|
|
1984
|
+
- **It lists, in this order:** the instances that can be opened, in groups;
|
|
1985
|
+
then the souls, the capabilities, the views, the acts and the commands,
|
|
1986
|
+
one group each.
|
|
1987
|
+
- **The instances are grouped as the sidebar groups them:** a cluster under
|
|
1988
|
+
its name, and a run of single instances under `independent`. Where the
|
|
1989
|
+
view has several deployments, each group is one deployment's, and its
|
|
1990
|
+
label names the machine first (`<machine> · <group>`).
|
|
1991
|
+
- **Each instance group has a label row:** its label, dim, before its rows.
|
|
1992
|
+
It is never selected: `Up`/`Down` and `PageUp`/`PageDown` pass over it,
|
|
1993
|
+
and the palette opens on the first row under it. A group with no instance
|
|
1994
|
+
that can be opened is not listed.
|
|
1995
|
+
- **The group last used comes first,** as in the Desktop's palette, and so
|
|
1996
|
+
does the cluster, the root and the child: the one with the instance opened
|
|
1997
|
+
or shown most recently in this workspace in this run first, then the
|
|
1998
|
+
list's order (the sidebar keeps its own order). Each workspace keeps its
|
|
1999
|
+
own recency, its last 50 instances, so working in another leaves it as it
|
|
2000
|
+
was. When the first instance is the shown tab's, the palette opens on the
|
|
2001
|
+
instance shown before it in this workspace, wherever its group puts it
|
|
2002
|
+
(the second instance, when none was shown before): `Enter` goes back to
|
|
2003
|
+
that terminal.
|
|
2004
|
+
- **An instance's row** has its state mark, its name, for another machine
|
|
2005
|
+
`on <machine>`, and, dim, its siblings as the detail names them
|
|
2006
|
+
(`sibling of <names>`), which are cut first when the row is short and are
|
|
2007
|
+
never matched by a query.
|
|
2008
|
+
- **The other groups:** the souls
|
|
1240
2009
|
of the open workspace, once they were read (by [the Souls
|
|
1241
2010
|
view](#the-souls-view), the Capabilities view or a spawn), and choosing
|
|
1242
2011
|
one shows the Souls view with it selected; its capabilities, once [the
|
|
@@ -1249,12 +2018,27 @@ keys under The palette.
|
|
|
1249
2018
|
catalog lists its soul; then Spawn an agent, Workspaces, Refresh and Help, and [the split's](#splits)
|
|
1250
2019
|
rows where each applies.
|
|
1251
2020
|
Each row says at its right edge what kind it is: `instance`, `soul`,
|
|
1252
|
-
`capability`, `view`, `act` or `command`.
|
|
1253
|
-
- **Typing filters it** with the Desktop's subsequence match
|
|
1254
|
-
|
|
2021
|
+
`capability`, `view`, `act` or `command`. A label row says none.
|
|
2022
|
+
- **Typing filters it** with the Desktop's subsequence match. An instance
|
|
2023
|
+
group keeps the rows that match, in its own order, and a group with none
|
|
2024
|
+
loses its label row. Each other group keeps the rows that match, the best
|
|
2025
|
+
first, a prefix first.
|
|
1255
2026
|
`Backspace` removes a character, and a paste adds its first line.
|
|
1256
2027
|
`Up`/`Down` (and `PageUp`/`PageDown`) move, `Enter` runs the selected
|
|
1257
2028
|
row, `Esc` closes it.
|
|
2029
|
+
- **`Alt+Shift+Down` goes to the next group, `Alt+Shift+Up` to the one
|
|
2030
|
+
before:** to its first row. Past the last group it wraps to the first,
|
|
2031
|
+
and before the first to the last; with one group, both go to its first
|
|
2032
|
+
row. While the palette is open these keys are its own: they win over the
|
|
2033
|
+
chords `Alt+Shift+Up` and `Alt+Shift+Down` ([Chords](#chords)), so they
|
|
2034
|
+
open no agent and leave the palette open, with or without the kitty
|
|
2035
|
+
keyboard protocol. The leader then `Up` or `Down`, or `Alt+Up` or
|
|
2036
|
+
`Alt+Down` where they are chords, closes it and opens the workspace
|
|
2037
|
+
before or after. The
|
|
2038
|
+
Desktop's palette has the same pair (`PALETTE_KEYS` in
|
|
2039
|
+
`packages/client/keymap.mjs`, which both read).
|
|
2040
|
+
- **On macOS there is no group key:** the Desktop's hold `⌘`, which a
|
|
2041
|
+
terminal never passes to a program.
|
|
1258
2042
|
- **Running a row** settles what was open under the palette, as the leader
|
|
1259
2043
|
does: an instance shows its tab, or opens its terminal in a new one, in
|
|
1260
2044
|
the Instances view, the focus in it ([Tabs](#tabs)); an act opens its
|
|
@@ -1292,7 +2076,9 @@ kernel's own files, so it is `$OATS_HOME_DIR/config/tui.json` when
|
|
|
1292
2076
|
`OATS_HOME_DIR` is set (the same rule as this computer's list of
|
|
1293
2077
|
deployments). `XDG_CONFIG_HOME` is not read for it. It never writes the file,
|
|
1294
2078
|
except to [move it](#the-move-from-configoats) from where earlier versions
|
|
1295
|
-
read it. With no file the keys are the ones above.
|
|
2079
|
+
read it. With no file the keys are the ones above. Which chord family it
|
|
2080
|
+
binds is not here: it is `keys.json`, beside it, which the Desktop shares
|
|
2081
|
+
([Switch family](#switch-family)).
|
|
1296
2082
|
|
|
1297
2083
|
```json
|
|
1298
2084
|
{ "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
|
|
@@ -1300,7 +2086,8 @@ read it. With no file the keys are the ones above.
|
|
|
1300
2086
|
|
|
1301
2087
|
- `keys.<action>` is the list of keys of that action. It **replaces** the
|
|
1302
2088
|
action's keys; an empty list leaves the action with no key. An action you
|
|
1303
|
-
do not name keeps its keys.
|
|
2089
|
+
do not name keeps its keys. A [chord](#chords) whose key you give an
|
|
2090
|
+
action here is not bound: your key wins, row by row, in either family.
|
|
1304
2091
|
- The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
|
|
1305
2092
|
`collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
|
|
1306
2093
|
`souls`, `capabilities`, `workspaces`, `palette`, `open`, `soul-instances`, `zoom`, `close-terminal`,
|
|
@@ -1325,14 +2112,16 @@ read it. With no file the keys are the ones above.
|
|
|
1325
2112
|
keys of their own.
|
|
1326
2113
|
- `ascii: true` is `--ascii`.
|
|
1327
2114
|
- `open.detachKey` is **[the leader](#the-leader)**. When you name none
|
|
1328
|
-
it is `
|
|
1329
|
-
|
|
2115
|
+
it is `C-x` (`Ctrl+X`) on every platform. `M-o` (`Alt+O`) and `C-\`
|
|
2116
|
+
(`Ctrl+\`), the defaults of earlier versions, are keys you can name, as
|
|
2117
|
+
in `"open": {"detachKey": "M-o"}`; a `detachKey` your file names is
|
|
2118
|
+
kept as it is. It is
|
|
1330
2119
|
`oats tui`'s own: it never reaches the kernel, and it reaches the agent
|
|
1331
2120
|
only when you press it twice in the agent's terminal.
|
|
1332
2121
|
It is read as a key wherever the TUI reads keys, so it may not be a key
|
|
1333
2122
|
an action has: `C-l` is `redraw`'s `Ctrl+L`, `C-k` the palette's
|
|
1334
2123
|
`Ctrl+K`, `C-j` is `Enter`. That holds for the default too: a file that
|
|
1335
|
-
gives `
|
|
2124
|
+
gives `ctrl+x` to an action names another leader as
|
|
1336
2125
|
well. It is one of these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
|
|
1337
2126
|
terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
|
|
1338
2127
|
`]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
|
|
@@ -1462,9 +2251,9 @@ with the Desktop (`packages/client/`).
|
|
|
1462
2251
|
asked for one, and no other machine is shown.
|
|
1463
2252
|
- **This computer's list of deployments is the kernel's**, read and changed
|
|
1464
2253
|
through the same kernel, with 15 seconds and 4 MiB each, from `/`:
|
|
1465
|
-
- `oats deployments --json`, at
|
|
1466
|
-
`--dir
|
|
1467
|
-
in it and after a Remove. One runs at a time: one asked for while one is
|
|
2254
|
+
- `oats deployments --json`, at the start (outside every deployment with
|
|
2255
|
+
no `--dir`, before the terminal is taken), when the switcher opens, on
|
|
2256
|
+
`r` in it and after a Remove. One runs at a time: one asked for while one is
|
|
1468
2257
|
on its way runs after it, however many times it was asked, and the
|
|
1469
2258
|
answer taken is that later one's.
|
|
1470
2259
|
- `oats deployments add <path> --via tui --json`, once a run, for the
|
|
@@ -1473,9 +2262,16 @@ with the Desktop (`packages/client/`).
|
|
|
1473
2262
|
|
|
1474
2263
|
An add and a remove are changes: `oats tui` never ends one, and one still
|
|
1475
2264
|
running as it leaves is named in one line after the screen is left.
|
|
2265
|
+
- **The workspace of each row of that list the run has not opened** is
|
|
2266
|
+
one more read, `oats status --dir <path> --json` with `--max-age 60`, by
|
|
2267
|
+
the same kernel ([the switcher](#the-switcher)): at the start, when the
|
|
2268
|
+
switcher opens and on `r` in it, one at a time, 30 seconds each and 60
|
|
2269
|
+
seconds for all of them; never from the reads' cadence above. A kernel
|
|
2270
|
+
that reports no workspace identities is not asked.
|
|
1476
2271
|
- **One look at the file system serves the switcher**, and it reads no
|
|
1477
|
-
file's content: when a row of the list
|
|
1478
|
-
asked for a regular
|
|
2272
|
+
file's content: when a row of the list, or a workspace with such a row,
|
|
2273
|
+
is opened, each of those directories is asked for a regular
|
|
2274
|
+
`oats-local.yaml`.
|
|
1479
2275
|
- **Opening an agent runs one more command,** `oats session attach --home
|
|
1480
2276
|
<home>`, by the same kernel, in a pane of the run's private tmux server
|
|
1481
2277
|
([above](#open-an-agents-terminal)), with no key of its own. For an agent
|
|
@@ -1641,8 +2437,8 @@ version:
|
|
|
1641
2437
|
- **A row of another machine shows what its host reported at the last
|
|
1642
2438
|
read,** not what is true at this moment. The time of that read is on the
|
|
1643
2439
|
machine's heading when it is not the time of this machine's read. A view
|
|
1644
|
-
of one machine has no heading: there the
|
|
1645
|
-
|
|
2440
|
+
of one machine has no heading: there the detail's `machine` line names the
|
|
2441
|
+
machine and the help's top row carries the time.
|
|
1646
2442
|
- The Souls and Capabilities views list a workspace of this machine's
|
|
1647
2443
|
souls and capabilities: both are this machine's.
|
|
1648
2444
|
- There is no sorting and no mouse, and a deployment's heading cannot be
|