Keybindings

All keyboard shortcuts can be customized via ~/.hoocode/keybindings.json. Each action can be bound to one or more keys.

The config file uses the same namespaced keybinding ids that hoocode uses internally and that extension authors use in keyHint() and injected keybindings managers.

Older configs using pre-namespaced ids such as cursorUp or expandTools are migrated automatically to the namespaced ids on startup, as are app.thinking.cycle and app.mode.cycle, which became …cycleForward when each gained a backward half.

After editing keybindings.json, run /reload in hoocode to apply the changes without restarting the session.

How this is grouped

There are around sixty bindings. Nobody holds sixty of anything, and the obvious answer — sort them by mechanism, so everything that cycles sits together — makes a list that is tidy on the page and useless at the keyboard. “It cycles” is a fact about the widget. It is not what you are thinking when you reach for a key.

So the grouping is by intention: the five things you are ever doing here, in the order the loop runs.

Five groups, none bigger than five, which is about the size a person can hold at once. Two of them cost nothing to learn: Flow is the set every terminal program already taught you, and the pickers print their own keys on their own hint lines — read, never remembered. That leaves three groups to genuinely know.

The declaration order in core/keybindings.ts is this grouping, and it is not cosmetic: your keybindings.json is written in the same order, so the file you open to rebind something is grouped the way this page is.

What the chord tells you

The modifier says what kind of thing will happen; the letter says to what.

Alt+letter sets a value. Nothing takes the screen, nothing loses focus, you keep typing. Six of these are dials — an ordered set of stops with the current one painted where you can see it — and Shift+Alt+letter always steps back:

Reversibility is the point, not symmetry. A control you can undo invites you to try it; a one-way control makes you stop and think first, which is the wrong tax on a key you press all day. The first time you step each dial in a session, the status line names the key that steps it back — once, at the moment you are primed to learn it, and never again after that.

Ctrl+letter acts on what is drawn right now, and shares its letter with the Alt key for the same subject:

• Alt+O sets how much tool output there ever is and saves where it lands; Ctrl+O jumps to all of it and back, leaving the dial where it was.
• Alt+T sets how much thinking there ever is; Ctrl+T shows or hides the thinking you have.

Two subjects, two letters, four keys — half what four unrelated chords cost.

A slash command picks a stop outright. /mode, /model, /color, /tree. The key steps, the command chooses; that is why app.model.select and app.session.tree ship unbound, each having given its letter to a dial.

Inside a picker, Ctrl belongs to the query you are typing — Ctrl+A is start of line, Ctrl+U kills the line, Ctrl+W kills a word. A picker’s verbs are therefore all on Alt, mnemonic to that picker. The picker captures keys while it is open, so a verb may reuse a letter the global set already has.

One letter in the whole set names nothing: Alt+N, the team roster. It survives because the task panel prints it in its own header — read off the screen rather than remembered, which is the fallback for anything that cannot earn a mnemonic.

The thinking level is the one dial with a second key: Shift+Tab still steps it. It is the only dial with no slash command, so on a terminal that does not send Alt that is the way to it.

Two consequences worth knowing before rebinding:Two consequences worth knowing before rebinding:

• No default takes a key the editor or the terminal already owns — Ctrl+A/E/B/F/K/U/W/Y/D/L/R/G, Ctrl+S (XOFF), Ctrl+M (enter), Ctrl+I (tab).
• No verb sits on a bare Shift+<letter>. Outside the Kitty keyboard protocol that arrives as the plain uppercase letter, which is indistinguishable from typing in any scope that has a query line.

test/keybinding-layout.test.ts holds all of this.

Key Format

modifier+key where modifiers are ctrl, shift, alt (combinable) and keys are:

• Letters: a-z
• Digits: 0-9
• Special: escape, esc, enter, return, tab, space, backspace, delete, insert, clear, home, end, pageUp, pageDown, up, down, left, right
• Function: f1-f12
• Symbols: `, -, =, [, ], \, ;, ', ,, ., /, !, @, #, $, %, ^, &, *, (, ), _, +, |, ~, {, }, :, <, >, ?

Modifier combinations: ctrl+shift+x, alt+ctrl+x, ctrl+shift+alt+x, ctrl+1, etc.

alt needs a cooperating terminal. On macOS outside the Kitty keyboard protocol, Option composes characters instead of sending Alt — Option+M types µ. Some Linux terminals claim Alt+<letter> for menu mnemonics. See terminal-setup.md for the per-terminal setting.

Interrupt, clear, exit, expand and submit are deliberately never on Alt, so a terminal that eats Option is still recoverable.

All Actions

Listed in the five families, in the order core/keybindings.ts declares them — which is also the order your keybindings.json is written in.

Compose — the message in your hands

Steer — what the agent is before it runs

The only three that change what happens next, and the only three that cost anything. The footer shows all three.

Read — what you see of what it did

Free and reversible, every one: nothing here touches the work, only the window onto it.

Go — sessions and places

Each takes the screen and hands it back on escape, and each has a slash command that does the same thing.

app.session.new and app.session.fork ship unbound because one replaces the transcript and the other needs a message picked out of it, so neither wants to be one stray chord away. app.model.select and app.session.tree are unbound for a different reason — each gave its letter to the dial that shares it. All four are bindable by hand.

Flow — getting out, getting back

Every terminal program already bound these, so they cost nothing to learn and never move: whatever else is misconfigured, you can still stop the agent, clear the line, and leave.

The editor

Standard readline/emacs bindings. Reference, not something to memorise — which is why they are not one of the five groups.

ctrl+d and ctrl+c each carry two ids. They are one key with a state-dependent meaning, not a conflict: ctrl+d exits only on an empty editor and deletes a character otherwise, and ctrl+c copies when there is a selection and clears the editor when there is not.

Overlays — live only while their surface is open

Never a memory burden: each surface prints its own keys on its own hint line, so these are recognised, not recalled. They may reuse a letter the global set already has, because the surface captures keys while it is up.

Lists and pickers, everywhere

Session picker (/resume)

Session tree (/tree)

The five lenses are numbered rather than lettered because they are an ordered set: alt+1-alt+5 needs no mnemonic. Everything else the tree types goes into its search query.

Scoped models picker (/models)

alt+g (“group”) rather than the obvious alt+p: without the Kitty protocol alt+p arrives as ESC-p, which the parser also reads as alt+up — this picker’s reorder key.

Team roster (--team)

Live only while the task panel holds focus, which is why they are plain letters: you are never typing there.

Options pane

The pane the agent raises to ask you a question.

On the free-text row the arrows are the text cursor’s first, and only act on the step at the ends of what you have typed. enter always commits.

Custom Configuration

Create ~/.hoocode/keybindings.json:

{
  "tui.editor.cursorUp": ["up", "ctrl+p"],
  "tui.editor.cursorDown": ["down", "ctrl+n"],
  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
}

Each action can have a single key or an array of keys. User config overrides defaults.

On native Windows, app.suspend has no default binding because Windows terminals do not support Unix job control. If you bind it manually, hoocode shows a status message instead of suspending. In WSL, the normal Linux ctrl+z/fg behavior still applies.

Emacs Example

{
  "tui.editor.cursorUp": ["up", "ctrl+p"],
  "tui.editor.cursorDown": ["down", "ctrl+n"],
  "tui.editor.cursorLeft": ["left", "ctrl+b"],
  "tui.editor.cursorRight": ["right", "ctrl+f"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
  "tui.input.newLine": ["shift+enter", "ctrl+j"]
}

ctrl+p and ctrl+n are both free of app bindings by default — the model and task-ledger dials that used to hold them are on alt+m and alt+l now — so this config collides with nothing.

Vim Example

{
  "tui.editor.cursorUp": ["up", "alt+k"],
  "tui.editor.cursorDown": ["down", "alt+j"],
  "tui.editor.cursorLeft": ["left", "alt+h"],
  "tui.editor.cursorRight": ["right", "alt+l"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
}

This one takes alt+h from the session picker, alt+k from the shortcut list and alt+w from /cd; rebind those too if you use them.