lug

# Keys and commands

The screen has a transcript above and a prompt below. The prompt edits like vim, in normal, insert and visual modes, and starts in insert mode (the start_mode option). The transcript and the prompt are windows, and <C-w> with a direction moves between them: <C-w>k to the transcript, which has its own transcript mode, and <C-w>j, i or <Esc> back. <leader> is <Space> by default.

## Default mappings

Mode Keys Does
normal, transcript : Open the : line
normal, transcript <CR>, <C-y> Send the prompt
insert <C-y> Send the prompt
insert <CR> Break the line
normal, insert <Up>, <Down> Recall an older, newer prompt
normal, insert, transcript <C-c> Cancel the run
normal, insert, transcript <C-s> Steer the run with the prompt's text: it reaches the model after the tool it waits on, or is the next message
normal, insert, transcript <S-Tab> Toggle auto mode
normal, transcript <C-w>h, <C-w>j, <C-w>k, <C-w>l Focus the window to the left, below, above, right
normal, transcript <C-w>w Focus the next window
normal, transcript <C-w>c, <C-w>o Close the window; close the others
normal, transcript <C-w>H, <C-w>J, <C-w>K, <C-w>L Move the window to the left, bottom, top or right edge
normal, transcript <C-w>+, <C-w>-, <C-w>>, <C-w>< A row taller or shorter, a column wider or narrower, times the count
normal, transcript <C-w>= Share the room evenly again
transcript i, <Esc> Focus the prompt
transcript j, k, <Down>, <Up> Scroll a line
normal <C-e> Scroll the transcript down a line
normal, transcript <C-d>, <C-u> Scroll half a page
all three <PageDown>, <PageUp> Scroll half a page
all three <ScrollDown>, <ScrollUp> (the mouse wheel) Scroll three lines
transcript gg, G The top, the bottom
transcript ]m, [m The next, previous item
transcript ]u, [u The next, previous message of yours
transcript ]t, [t The next, previous tool card
normal, transcript za, zo, zc Toggle, open, close the fold under the cursor
normal, transcript zR, zM Open, close every fold
transcript h, l, w, b, e, W, B, E, 0, ^, $ Move along the row, as in the prompt
transcript v, V, then y Select characters or rows, then copy them
transcript q Quote the selection into the prompt
normal, visual, transcript gf Open the path under the cursor in your editor
insert @ Reference a file, with completion
normal, transcript <leader>am, <leader>aM Pick a model; switch to the next one
normal, transcript <leader>at Set the thinking level
normal, transcript <leader>ac Compact the conversation
normal, transcript <leader>ap Toggle plan mode
normal, transcript <leader>aa Pick from the live agents
normal, transcript <leader>ss, <leader>sr Pick a session; rename this one
normal, transcript <leader>ut Pick a theme

:map [MODE] lists the mappings in force.

## The prompt editor

Insert mode takes the usual keys, plus <C-a> and <C-e> for the line's start and end, and <C-w> and <C-u> to delete the word, or everything, before the cursor.

Normal mode supports:

There is one register. With the clipboard option on, yanks also go to the system clipboard.

## Commands

Command Does
:quit, :q, :q! Quit; refused during a run unless !
:cancel End the run and drop queued messages
:model [NAME], :model! Switch model, or pick one; switch to the next
:model @ROLE [NAME] Set the model a plugin's @ROLE means, or pick one
:plan Toggle plan mode: the model may only read, until you approve the plan it submits
:agents Pick from the live agents: <CR> opens one's conversation, <C-x> cancels its run
:thinking [LEVEL] Set the thinking level, or pick one
:login PROVIDER KEY Save a provider's API key in ~/.lug/auth.json
:sessions Pick a session of this project to switch to
:rename [TITLE] Retitle the session
:compact [INSTRUCTIONS] Replace the conversation so far with a summary
:approvals [clear] Show the approval mode and tools allowed always; clear revokes them
:auto Toggle auto mode: tool calls run without asking
:set [NAME[=VALUE]] List, show or set options
:theme [NAME] Switch palette, or pick one
:hi GROUP [ATTR...] Show or change a highlight group
:edit [PATH] Open a file, or the path under the cursor, in your editor
:map [MODE] List mappings
:lua CODE Run Lua
:close, :only Close the focused window; close the others
:resize N Give the focused window N rows or columns, as its split runs
:haul, :haul update [NAME] Open the plugins panel; update every plugin, or one
:reload Reload the configuration

## The : line, dialogs and the popup

The : line, the dialogs and the completion popup have keymap modes of their own, so their keys can be mapped like any other:

Mode Keys Does
command <CR> Run the : line; under the slug style, the command selected on the bar unless the line names one or holds a space
command <Esc>, <C-c> Close it
command <BS> Delete a character, or close an empty line
command <Tab> Complete a command's name or argument; under the slug style, select the next command on the bar
command <S-Tab> Under the slug style, select the previous command on the bar
command <Up>, <Down> An older, newer line
input, picker <CR> Accept
input, confirm, picker <Esc> Cancel
confirm y, n Yes, no
picker <Down>, <C-n>, <Up>, <C-p> The next, previous item
popup <C-n>, <Down>, <C-p>, <Up> The next, previous candidate
popup <Tab>, <C-y> Take the candidate
popup <Esc> Close the popup

Other keys edit the line, as the prompt's insert mode does. While the popup is open, its keys come before those of the editor it completes.

## Approval dialog

When a tool call needs approval, a dialog shows what it will do, with the exact diff for an edit computed from the file on disk. While it is open, keys go to the approval mode and nowhere else; the dialog lists what they do:

Key Does
a Run the call
A Run it, and allow this tool from now on
e Edit the arguments in your editor first
d, <Esc> Skip the call; the run continues
D, <C-c> Skip it and end the run

## Mapping keys

lug.keymap.set("normal", "<leader>q", ":q")
lug.keymap.set("transcript", "<C-j>", function(count) lug.feed.scroll(count) end,
  { desc = "scroll down" })
lug.keymap.del("insert", "@")

A mapping to other keys, as vim's inoremap jk <Esc>, types them with lug.prompt.keys, which the prompt editor takes past every mapping:

lug.keymap.set("insert", "jk", function() lug.prompt.keys("<Esc>") end)
lug.keymap.set("normal", "H", function() lug.prompt.keys("^") end)

Keys are written as in vim: a, <CR>, <Esc>, <Tab>, <Space>, <C-a>, <A-CR>, <S-Tab>, <F1>, <ScrollUp> and <ScrollDown> for the mouse wheel, and sequences such as gg or <C-w>k. A mapping shadows the prompt editor's own key until it is removed. A mapping made on <Char> receives the text typed in that mode.