maestro/docs/COMMAND-BAR.md

COMMAND-BAR.md — the command bar contract

One rule for the ctrl-k command bar in both clients, so the web bar and the TUI bar open the same way, rank the same results in the same order, and act on the same keys. Read this before changing either. Both clients implement exactly what is written here; if the behaviour needs to change, change it here first.

The bar is one surface with three jobs: go to a session, run a command, spawn into a directory. It is not a new place to configure anything and it does not own any action — it chooses one and hands off to the flow that already implements it.

Opening

ctrl-k opens the bar from anywhere:

Client	From	Notes
TUI	Normal mode	Sidebar has the keyboard.
TUI	Insert mode	The pane has the keyboard; the bar still opens.
Web	Sidebar focused	Ordinary global binding.
Web	Terminal focused	Intercepted before xterm sees it.

It is a keymap entry like any other, not a hard-wired key. In the TUI it is bound in both DEFAULT_NORMAL and DEFAULT_INSERT and is rebindable through [tui.keymap.*]; because the help overlay builds its lines from the live keymap, it appears there without a second list to maintain. In the web it is an entry in the command registry, so the ? overlay lists it for the same reason.

An attached xterm swallows every keystroke it is given, so the web binding is handled in the capture phase, ahead of the terminal — the same way the restart overlay swallows the app's shortcuts (docs/RESTART.md).

Escape hatch — sending a literal Ctrl-K

Binding ctrl-k takes readline's kill-to-end-of-line away from every pane. The leader gives it back: leader then ctrl-k — ctrl-a ctrl-k by default — sends the literal 0x0B byte to the focused pane and does not open the bar.

The TUI already has a leader (ctrl-a, [tui].leader), and this chord goes through the existing chord resolution, so rebinding the leader rebinds the escape hatch with it — exactly as the leader's Insert-mode escape already works. The web gains a leader for this, defaulting to ctrl-a and mirroring the TUI's. ctrl-a is select-all in a browser; the web preventDefaults it, since selecting all of a terminal pane does nothing useful.

One knob drives both clients: the daemon serves [tui].leader as leader on GET /api/info, and the web binds that instead of its own constant (#159). A daemon too old to send the field, or an unreachable /api/info, leaves the web on ctrl-a. The section is named [tui] for history — it is the leader for every client, not the TUI's alone.

The leader itself needs the same kind of way back: holding it consumes every press, on both clients, even before anything is bound behind it. Pressing it twice — ctrl-a ctrl-a by default — sends one literal leader byte to the focused pane and clears the pending chord, the way tmux resolves a doubled prefix key. This chord is also built from the configured leader, so a rebound leader carries its own escape hatch with it.

Only Ctrl-K and the leader itself get an escape hatch. No other control character is intercepted, so none of them needs one.

Focus round-trip

Closing the bar returns the keyboard to whatever held it when the bar opened, the terminal included. A round trip through the bar never silently moves focus, and never counts as a focus change for the daemon: opening the bar does not report the pane unfocused, and closing it does not report a new focus. The bar is a view over the app, not a place in it.

Opening the bar while a session is previewed (docs/PREVIEW.md) discards the preview first, like any other real change; the bar is not previewed into.

Structure

The bar is a query line over a result list. By default the list is flat and mixed — sessions and commands ranked together — and rendered under kind headers: a header row naming the kind, then that kind's results.

Grouping is a rendering of the ranking, never a reordering of it:

• Results are ranked as one list by the algorithm below.
• A kind's group holds its matches in that rank order.
• Groups are ordered by their best-scoring member. The first row under the first header is therefore the globally best result, and the highlight starts on it.

Two sigils, typed as the first character of the query, narrow the list to one kind:

Sigil	Kind	Candidates	Enter
>	commands	Every entry in the client's command registry — the web registry from the ? overlay, the TUI's live (chord, Action) keymap for the current mode.	Runs the command.
~	directories	Recent dirs (GET /api/recent-dirs) and the project list the spawn form already uses, with GET /api/dirs filling in as a path is typed.	Spawns a session there with every default resolved.

While a sigil is in force there is one kind, so the kind header is dropped. A command row shows its key chord beside its label, so the bar teaches the keymap instead of replacing it. A ~ spawn takes the same fast-forward path as N / FastForwardSpawn: an unresolvable default opens the pre-filled spawn form rather than failing silently.

Backspacing past a sigil returns to the mixed list. The sigil is one character of the query like any other — deleting it is not a special key, it is the query becoming empty again.

The sigil is only a sigil in first position. > or ~ typed anywhere else is a literal query character (a directory query is where a ~ is most likely to be typed twice, and the second one must reach the matcher).

Empty query

With no sigil and an empty query the bar lists sessions only, most recently focused first, so ctrl-k enter is "back to where I just was". Commands and directories need a sigil or a query to appear; an empty bar is a session switcher.

Recency comes from the daemon, not from client state — the same order in every client, on every device, including one that just loaded the page. The daemon stamps a last-focused time per session and ships it on the session like any other field (#145). Both of the ways focus moves stamp the same field: a client opening /api/attach/:id, and a client reporting focus explicitly at POST /api/sessions/:id/focus when it refocuses a pane that is already open.

A session that has never been focused sorts after every session that has, and among those, most recently created first. Dead sessions sort after live ones regardless of recency: a session you cannot attach to is not where you just were.

Under > an empty query lists every command in registry order. Under ~ it lists recent dirs, most recent first, then the project list.

Keys

Key	Action
enter	Open the highlighted result — attach the session, run the command, spawn into the directory.
tab	Drill into the highlighted session's action page. No effect on any other kind.
esc	At the top level, close the bar. On an action page, return to the result list.
backspace	Ordinary editing; at an empty query on an action page, return to the result list.
up / down	Move the highlight.
ctrl-p / ctrl-n	Move the highlight.

The highlight does not wrap: it stops at the first and last row. Kind headers are never landed on — they are labels, not rows.

Enter on a session goes through the same open path the sidebar's click and the hash router already share, so a bar attach can never leave the layout in a state a click could not produce.

Drill-in — the session action page

tab on a highlighted session opens that session's action page inside the same overlay: kill, rename, spawn similar. The page is still fuzzy searchable — the query line keeps working, now over those actions.

• The overlay names the session being acted on, so the target is never ambiguous.
• Escape, or backspace at an empty query, returns to the result list with the previous query intact. Drilling in and backing out is free.
• Each action raises the flow it already has: kill through the confirmation both clients ask for (docs/SIDEBAR.md) and the blockers dialog behind it (docs/WORKTREES.md), rename through the existing prompt pre-filled with the session's own name (docs/SIDEBAR.md), spawn similar through the spawn form seeded from the session's directory and command. The bar picks the action; it never reimplements one.

No actions beyond those three, and no action across more than one session.

Touch entry

On the web, tapping or focusing the sidebar's search field opens the bar with an empty query. There is no ctrl-k on a phone and the product is mobile-first, so the field the operator already reaches for is the entry point.

This replaces the sidebar's inline substring filter — one search affordance in the header, not two beside each other. The tree's "No matches" empty state belonged to that filter and goes with it; the bar's own no-results state takes over (see the fixture F4).

At phone width the bar follows the bottom-sheet treatment the spawn modal already uses below 600px. Visuals otherwise come from DESIGN.md's existing overlay tokens — the bar is the same family of surface as the spawn modal and the help overlay, not a new one.

What a candidate is

The matcher is a pure function: (query, candidates) → ranked subset with matched ranges. It knows nothing about sessions, panes or the network. A candidate is a kind plus a set of named text fields, each with a fixed weight.

Kind	Field	Weight	Text
session	name	0	The name as the sidebar shows it: metadata.name if set, else the command line (docs/SIDEBAR.md's fallback).
session	directory	-24	The directory the sidebar groups it under, abbreviated: ~/dev/api, not /home/me/dev/api.
session	command	-32	The full command line, arguments included.
session	tool	-40	The tool id the card's icon stands for (claude, codex, opencode, …), absent when the program is not one we have a mark for.
command	label	0	The plain-language label — the web registry's label, the TUI's Action::help_label.
directory	path	0	The path as displayed, abbreviated the same way.

A command's key chord is displayed, not matched. It is there to teach the keymap; matching it would make > results depend on a user's rebinds, and the two clients do not share a keymap.

A candidate matches if at least one of its fields matches. Its score is the best field score + field weight across its fields, and the matched ranges it returns are those of that winning field — so a session found through its directory highlights inside the directory, not inside its name.

Match and rank

Two independent implementations (#146 in TypeScript, #147 in Rust) must produce the same order for the same input. Everything below is exact.

Normalization

• Query: lowercase, then remove every whitespace character. The result is the normalized query. If it is empty, see "Empty query" below.
• Field text: matched against its lowercased form. Bonuses are computed against the original text, because case is a signal (camelCase) that lowercasing destroys.
• Compact form of a string: lowercase with whitespace removed. Used only for the exact and prefix tests.

Lowercasing is per-character simple lowercase (char::to_lowercase / String.prototype.toLowerCase). Positions are character positions — Unicode scalar values in Rust, UTF-16 code units in TypeScript, which agree for every character these fields realistically hold; ranges are returned in the host language's own unit, since they exist to slice that language's string.

What a match is

Case-insensitive subsequence: every character of the normalized query appears in the lowercased field text, in order, not necessarily adjacent. A field with no such embedding does not match.

Word boundaries

A matched character at position p earns exactly one character bonus, taking the first rule that applies:

Rule	Bonus
p == 0 — first character of the field	+18
The character before it is a separator: / \ - _ . : or a space	+16
It is uppercase and the character before it is lowercase (a camelCase hump)	+12
It is a digit and the character before it is not	+12
Otherwise	0

That is one rule for both shapes the doc has to cover. In a path, / is a separator, so the first character of every segment is a word start: foo in ~/dev/foobar starts a segment and outscores foo in ~/src/myfoo, which starts nothing. In a session name, -, _, . and spaces do the same work, so ws reaches web-search more cheaply than websearch.

Score

Let the query characters be matched at positions p₀ < p₁ < … < pₘ₋₁, and let p₋₁ = -1. For each matched character i, with gap = pᵢ - pᵢ₋₁ - 1:

contribution(i) = 16                      // every matched character
                + bonus(pᵢ)               // the table above
                + (gap == 0 ? +8          // adjacent to the previous match
                            : -min(gap, 12))

gap for i = 0 is the number of characters skipped before the first match, so a match that starts late is penalised exactly like an internal gap, and the cap is the same one.

The field score is the sum of the contributions, plus at most one whole-field adjustment:

• compact field text equals the normalized query → +64
• else compact field text starts with the normalized query → +32

Length is deliberately not in the score — it is a tie-break, so a long field never loses to a short one that matched worse.

Which embedding

A query can sit in a field many ways. The one that counts is the highest-scoring embedding; among embeddings that score the same, the leftmost — compare position vectors element by element, smaller wins.

Greedy leftmost-first matching is not sufficient and must not be used: in maestro-tui, mtu greedily takes m₀ a₁ … and never reaches tui. Both implementations use the obvious dynamic program over (query index, text position), carrying the best score and its position vector, since the gap term depends only on the previous matched position.

The whole-field adjustment is constant for a (query, field) pair, so adding it after the dynamic program cannot change which embedding wins.

Ordering

Sort by score, highest first. Equal scores break in this order:

1. Kind — session, then command, then directory.
2. Length of the matched field text, shorter first.
3. The matched field text, ascending, compared by code point, case sensitive.
4. Input order. The sort is stable, so candidates the caller ordered deliberately — sessions most recently focused first, commands in registry order — keep that order when nothing else separates them.

Kind leads because that is the ruling the ambiguous cases need: a session named kill and the kill command that score alike put the session first, because the operator who typed a session's name meant the session.

Empty query

A normalized query that is empty matches every candidate, each with score 0 and no ranges, in input order. The bar's own rules decide what is in the candidate list at that point (sessions only at the top level); the matcher does not filter by kind.

Fixtures

These are the contract. Both matchers are tested against exactly these cases; the prose above is the explanation of why they come out this way.

Candidates are written as kind(fields); unlisted fields are absent. session(name, dir, command, tool). Scores are shown for diagnosis — the order is what is being asserted, and an implementation that ranks correctly with different absolute numbers has still failed, because the numbers are how the next fixture stays predictable.

F1 — empty query keeps input order

query:      ""
candidates: session("kill", "~/dev/api", "bash")
            session("killer-app", "~/dev/killer-app", "claude --resume", "claude")
            command("Kill selected session")
expected:   session("kill")           score 0
            session("killer-app")     score 0
            command("Kill selected session")  score 0

Every candidate matches, in the order given. No ranges.

F2 — a session named kill against the kill command

query:      "kill"
candidates: (as F1)
expected:   session("kill")                   178   name
            session("killer-app")             146   name
            command("Kill selected session")  146   label

kill wins on the exact bonus. The other two tie at 146 — both are a contiguous prefix match — and the kind tie-break puts the session first.

F3 — a fragment matching mid-segment inside a path

query:      "foo"
candidates: directory("~/dev/foobar")
            directory("~/src/myfoo")
            directory("~/foo")
expected:   directory("~/foo")         78   ranges [2,3,4]
            directory("~/dev/foobar")  74   ranges [6,7,8]
            directory("~/src/myfoo")   56   ranges [8,9,10]

The first two start a path segment; the third is mid-segment and loses by the whole boundary bonus. ~/foo beats ~/dev/foobar only because less was skipped before the match.

F4 — a query matching nothing

query:      "zzz"
candidates: session("kill", "~/dev/api", "bash")
            command("Kill selected session")
expected:   (empty)

The matcher returns an empty list, never a list of zero-scored candidates. The bar renders its no-results state.

F5 — a non-contiguous subsequence

query:      "mtu"
candidates: session("maestro-tui")
            session("maestro-daemon")
            session("mtui-scratch")
expected:   session("mtui-scratch")  122   ranges [0,1,2]
            session("maestro-tui")    91   ranges [0,8,9]

maestro-daemon has no u after its t and does not match. maestro-tui does, across a gap — which greedy matching would miss entirely.

F6 — a name beats a directory

query:      "api"
candidates: session("api", "~/dev/web", "bash")
            session("worker", "~/dev/api", "bash")
expected:   session("api")     154   name
            session("worker")   50   directory

The second session is found through its directory, and highlights there.

F7 — case-insensitive, tie broken by length

query:      "api"
candidates: session("API-Gateway")
            session("apiary")
expected:   session("apiary")       122   name
            session("API-Gateway")  122   name

Both are prefix matches and score identically. Same kind, so length decides: 6 characters before 11. Input order does not save API-Gateway.

F8 — the tool field

query:      "claude"
candidates: session("nameless", "~/dev/x", "claude --resume", "claude")
            session("clay", "~/dev/y", "bash")
expected:   session("nameless")  186   tool

clay has no claude subsequence anywhere and drops out. nameless matches its tool exactly (+64, weight -40, giving 186) which beats the prefix match on its command field (+32, weight -32, giving 162).

F9 — a word boundary inside a session name

query:      "ws"
candidates: session("websearch")
            session("web-search")
expected:   session("web-search")  71   ranges [0,4]
            session("websearch")   56   ranges [0,3]

The s after - earns the boundary bonus; the s inside websearch earns nothing.

F10 — command labels

query:      "se"
candidates: command("Kill selected session")
            command("Create a session")
            command("Show help")
expected:   command("Show help")             53   ranges [0,6]
            command("Kill selected session") 51   ranges [5,6]
            command("Create a session")      47   ranges [9,10]

Show help starts at position 0; the other two start at a word boundary but later, and pay for the skipped characters.

F11 — a query against session directories

query:      "dev"
candidates: session("api", "~/dev/api", "bash")
            session("notes", "~/documents/dev-notes", "nvim")
            session("scratch", "~/srv/devops", "bash")
expected:   session("api")      54   directory, ranges [2,3,4]
            session("scratch")  50   directory, ranges [6,7,8]
            session("notes")    44   directory, ranges [12,13,14]

All three start a path segment. They separate purely on how much was skipped first, and notes hits the -12 gap cap.

F12 — exact beats prefix

query:      "quit"
candidates: command("Quit Maestro")
            command("Quit")
expected:   command("Quit")           178   label
            command("Quit Maestro")   146   label

The 32-point difference between the exact and prefix adjustments is the whole gap; nothing else about the two matches differs.