@tiagojct/subsub 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Sub-Sub follows the version numbers of npm: a change in the second number (0.13) adds features or changes how you use it; a change in the third (0.13.1) only fixes.
 
+## 0.23.0 (2026-10-24)
+
+- The browser view is set like the website. Replies and notes have the website's headings (a fine rule above each section), its numbered steps and a slightly larger text. A note opens on the lighter field of a page, and the list of notes is grouped by folder under small-capital heads, with the date on the right. The empty conversation has the website's running head and a larger heading. Notes and the model in the top bar are plain text buttons, as in the website's menu. A command you send (`/read ...`) is shown in the mono. The working line is drawn dotted, dashed and solid, as in the terminal, instead of a moving gradient. Scrollbars are thin. On a phone, Notes is no longer cut to "No..." (the theme button is in the side panel there).
+- In the browser view, the sections of the side panel (Library, Actions, Conversations) and the two groups of actions (Research, Library) fold at their heading. With the others folded, the list of conversations takes the whole panel. The browser remembers which ones you folded.
+
+## 0.22.0 (2026-10-24)
+
+- `subsub tui`: Sub-Sub on the whole terminal. It is a full-screen client of pi's RPC mode, like the browser view, with the look of `subsub`: a conversation that scrolls (mouse wheel, PgUp and PgDn), a side panel from 110 columns (mode, library, keys, earlier conversations), an editor that completes commands, and the footer. Alt+N, Alt+L, Alt+A and Alt+M open the notes, the library search and the actions, and switch the mode, as in `subsub`. `/sessions` and `/new` change the conversation, `/model` chooses the model, `/restart` starts pi again in the same conversation, `/quit` leaves. Ctrl+O shows the output of tool rows, Esc stops a running answer, and Ctrl+C twice quits. `--light` or `--dark` set the colours when the terminal does not say (the default is dark), and `--librarian` starts in the Librarian.
+- In `subsub tui`, every question that Sub-Sub asks is answered on screen: the approval screen for a library change (`y` applies it, `n` or Esc leaves it, Enter does nothing, keys in the first half second are ignored), lists and typed answers. Nothing is applied without a yes. pi's own screens (`/login`, `/settings`, `/tree`, `/resume`, `/fork`, `/share`, `/export`) are not in it: use `subsub` or `subsub web` for them.
+- Shortcuts: F2, F3, F4 and F5 open the notes, the library search and the actions, and switch the mode, in `subsub` and in `subsub tui`. Alt+N, Alt+L, Alt+A and Alt+M (0.21.0) need a terminal that sends Alt as Escape plus the letter; macOS Terminal and iTerm2 do not by default (Option types a symbol), so on a Mac they did nothing. On a Mac the F keys need Fn unless you set them as standard function keys in System Settings.
+- Fixed: when pi is started with Sub-Sub's own folder as its folder (the browser view and `subsub tui` do this), an empty `auth.json` could be replaced by a link to itself, and the model then could not read its credentials ("Credential store read failed ... ELOOP"). It is no longer linked.
+- Internal: the code that talks to pi in RPC mode (`Agent`, the library state and search, the command hints) is in `src/rpc.ts`, shared by the browser view and the terminal client. Tests: screen snapshots of the client at 80 and 120 columns, and a test that runs `subsub tui` in a terminal with a fake model and a fake Zotero (macOS and Linux).
+
 ## 0.21.0 (2026-10-23)
 
 A new look for the terminal. It is on by default in `subsub`; set `"look": false` in the settings to go back to the old screen.

package/README.md

@@ -80,13 +80,16 @@ Sub-Sub runs its Zotero server, [zotero-local-mcp](https://github.com/tiagojct/z
 subsub web           # in the browser
 subsub               # in the terminal
 subsub --librarian   # in the terminal, in the Librarian
+subsub tui           # on the whole terminal (full screen)
 subsub -c            # continue the last conversation
 subsub --help        # all commands
 ```
 
 In the browser view, connect a model provider with the model button. In the terminal, type `/login`.
 
-The terminal has its own look, drawn like the website: a footer with the mode, the library, the model, the context in use and the cost; Sub-Sub's tools in plain words (`search the library: asthma`); and an approval screen for library changes (`y` applies, `n` or Esc leaves the library as it is, Enter does nothing). `/notes`, `/library` and `/actions` open screens for your notes, a library search and the actions of the browser view; Alt+N, Alt+L, Alt+A and Alt+M (mode) are shortcuts. Nothing is red: a failure is ink with a hollow mark and a word, and a removal is struck through. For terminals that cannot draw box glyphs, set `SUBSUB_ASCII=1`; `SUBSUB_REDUCE_MOTION=1` stops the working indicator from moving; `"look": false` in the settings brings back the plain screen.
+The terminal has its own look, drawn like the website: a footer with the mode, the library, the model, the context in use and the cost; Sub-Sub's tools in plain words (`search the library: asthma`); and an approval screen for library changes (`y` applies, `n` or Esc leaves the library as it is, Enter does nothing). `/notes`, `/library` and `/actions` open screens for your notes, a library search and the actions of the browser view; F2, F3, F4 and F5 (mode) are shortcuts; so are Alt+N, Alt+L, Alt+A and Alt+M where your terminal sends Alt (in macOS Terminal and iTerm2, Option types a symbol unless you turn on "Use Option as Meta key", and a Mac needs Fn with the F key unless the F keys are set as standard). Nothing is red: a failure is ink with a hollow mark and a word, and a removal is struck through. For terminals that cannot draw box glyphs, set `SUBSUB_ASCII=1`; `SUBSUB_REDUCE_MOTION=1` stops the working indicator from moving; `"look": false` in the settings brings back the plain screen.
+
+`subsub tui` puts Sub-Sub on the whole terminal, as the browser view puts it in the browser: a conversation that scrolls, a side panel from 110 columns, the editor and the footer, with the same colours and screens. Besides the commands above, `/sessions` and `/new` change the conversation, `/model` chooses the model, `/restart` starts pi again in the same conversation, and `/quit` leaves (Ctrl+C twice also quits). `--light` or `--dark` set the colours when your terminal does not say. It does not have pi's own screens (`/login`, `/settings`, `/tree`, `/resume`): use `subsub` or `subsub web` for them.
 
 The browser view also has a library search (each result can start `/read` or `/lit-note`), a notes pane that shows the notes of your Sub-Sub folder next to the conversation (note paths and `[[links]]` in replies open there), argument hints for the commands, and rename, delete (to `~/.subsub/trash`) and export for conversations.
 
@@ -98,6 +101,7 @@ Commands in Sub-Sub:
 | `/subsub` | Zotero connection, mode, model and library counts |
 | `/history`, `/undo [id]` | Recent library changes; undo the last one or one by its id |
 | `/notes`, `/library`, `/actions` | Terminal screens: the notes in your Sub-Sub folder (the chosen note beside the list from 100 columns); a library search as you type (Enter starts `/read`, Ctrl+N `/lit-note`); the actions of the browser view as a list |
+| `/sessions`, `/new`, `/model`, `/restart`, `/quit` | In `subsub tui`: earlier conversations; a new one; the model; pi again in the same conversation; leave |
 | `/feedback [what happened]` | A draft bug report in `Inbox/`, with versions, `subsub doctor` and the last error, and without your folders, emails or keys. You post it on GitHub; Sub-Sub sends nothing |
 | `/ai-statement [uses]` | A draft statement on the use of AI for a manuscript, with the Sub-Sub version, its DOI and your models |
 | `/tag-batch [size]` | Tag items that have no topic, with your tag list |

package/dist/cli.js

@@ -14,6 +14,7 @@
  * - `subsub init` sets Sub-Sub up; `subsub doctor` checks the setup.
  * - `subsub web` (or `subsub serve`) opens Sub-Sub in the browser;
  *   `subsub shortcut` adds a Sub-Sub shortcut that does the same.
+ * - `subsub tui` is Sub-Sub on the whole terminal: a full-screen client of pi's RPC mode, like the web view.
  */
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
@@ -106,6 +107,9 @@ function isEmptyAuth(file) {
 export function shareAuth(agentDir, piAgentDir) {
     const mine = join(agentDir, "auth.json");
     const theirs = join(piAgentDir, "auth.json");
+    // The web view and `subsub tui` start pi with PI_CODING_AGENT_DIR set to Sub-Sub's folder: a link to itself would make auth.json unreadable.
+    if (real(mine) === real(theirs))
+        return false;
     if (!existsSync(theirs))
         return false;
     try {
@@ -149,6 +153,7 @@ Usage:
   subsub                 Start Sub-Sub in the terminal
   subsub --librarian     Start in the Librarian, which only manages the library
   subsub web             Open Sub-Sub in the browser
+  subsub tui             Sub-Sub on the whole terminal: transcript, side panel, footer (--light or --dark for the colours)
   subsub init            Set up or change the settings (folder, tag list, models)
   subsub doctor          Check the set-up; each line marked FIX says what to do
   subsub usage           The pilot's usage log (if turned on): a summary and where the file is
@@ -189,6 +194,11 @@ export async function run(argv = process.argv.slice(2)) {
         process.exitCode = await webMain([...args.slice(1), ...(here ? ["--here"] : [])], env);
         return;
     }
+    if (args[0] === "tui") {
+        const { runTui } = await import("./tui.js");
+        // The terminal is given back before this returns; exit so that nothing else keeps the process alive.
+        process.exit(await runTui([...args.slice(1), ...(here ? ["--here"] : [])], env));
+    }
     if (args[0] === "shortcut") {
         const { shortcutMain } = await import("./shortcut.js");
         process.exitCode = shortcutMain(args.slice(1), env);

package/dist/rpc.js

@@ -0,0 +1,185 @@
+/**
+ * pi in RPC mode, for the clients that show Sub-Sub: the web view (src/web.ts) and the full-screen terminal client (src/tui.ts). One child
+ * process, strict JSONL (records end at LF only), requests answered by id, every other record handed to the listeners. Sub-Sub's extension
+ * tells its clients what pi's RPC protocol has no place for through two status texts: the state of the library ("subsub.web") and the
+ * answer to a library search ("subsub.find").
+ */
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { field, frontMatter } from "./notes.js";
+/** pi as a child process in RPC mode. Strict JSONL: records end at LF only. */
+export class Agent {
+    proc;
+    decoder = new StringDecoder("utf8");
+    buf = "";
+    n = 0;
+    pending = new Map();
+    listeners = new Set();
+    stderr = "";
+    onExit;
+    command;
+    args;
+    cwd;
+    env;
+    constructor(command, args, cwd, env) {
+        this.command = command;
+        this.args = args;
+        this.cwd = cwd;
+        this.env = env;
+    }
+    start(extra = []) {
+        this.buf = "";
+        this.decoder = new StringDecoder("utf8");
+        const proc = spawn(this.command, [...this.args, ...extra], { cwd: this.cwd, env: this.env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+        this.proc = proc;
+        proc.stdout.on("data", (chunk) => this.feed(this.decoder.write(chunk)));
+        proc.stderr.on("data", (d) => {
+            this.stderr = (this.stderr + d.toString()).slice(-20_000);
+        });
+        proc.once("exit", (code) => {
+            if (this.proc !== proc)
+                return;
+            this.proc = undefined;
+            for (const p of this.pending.values()) {
+                clearTimeout(p.timer);
+                p.reject(new Error(`pi stopped (code ${code}). ${this.stderr.slice(-500)}`));
+            }
+            this.pending.clear();
+            this.onExit?.(code);
+        });
+    }
+    feed(text) {
+        this.buf += text;
+        let i;
+        while ((i = this.buf.indexOf("\n")) >= 0) {
+            const line = this.buf.slice(0, i).replace(/\r$/, "");
+            this.buf = this.buf.slice(i + 1);
+            if (!line.trim())
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (rec.type === "response" && typeof rec.id === "string" && this.pending.has(rec.id)) {
+                const p = this.pending.get(rec.id);
+                this.pending.delete(rec.id);
+                clearTimeout(p.timer);
+                if (rec.success === false)
+                    p.reject(new Error(rec.error ?? `${rec.command} failed`));
+                else
+                    p.resolve(rec.data);
+                continue;
+            }
+            for (const l of this.listeners)
+                l(rec);
+        }
+    }
+    on(l) {
+        this.listeners.add(l);
+        return () => this.listeners.delete(l);
+    }
+    write(rec) {
+        const stdin = this.proc?.stdin;
+        if (!stdin || !stdin.writable)
+            throw new Error("pi is not running");
+        stdin.write(`${JSON.stringify(rec)}\n`);
+    }
+    request(cmd, timeoutMs = 30_000) {
+        const id = `w${++this.n}`;
+        return new Promise((resolvePromise, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`pi did not answer ${String(cmd.type)} in time`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve: resolvePromise, reject, timer });
+            try {
+                this.write({ ...cmd, id });
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(err);
+            }
+        });
+    }
+    async stop() {
+        const proc = this.proc;
+        if (!proc)
+            return;
+        this.proc = undefined;
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error("pi was stopped"));
+        }
+        this.pending.clear();
+        await new Promise((done) => {
+            const t = setTimeout(() => {
+                proc.kill("SIGKILL");
+                done();
+            }, 3000);
+            proc.once("exit", () => {
+                clearTimeout(t);
+                done();
+            });
+            proc.kill();
+        });
+    }
+}
+/** The dialogs that wait for an answer (extension_ui_response): the rest of the extension UI requests are notices. */
+export function isDialog(ev) {
+    return ev?.type === "extension_ui_request" && ["select", "confirm", "input", "editor"].includes(ev.method);
+}
+/** What the extension sends as status texts: the state of the library and the answer to the last library search. */
+export class Side {
+    state = null;
+    find = null;
+    /** Decode an extension_ui_request; tells which of the two it was, or undefined. */
+    take(ev) {
+        if (ev?.type !== "extension_ui_request" || ev.method !== "setStatus")
+            return undefined;
+        const decode = () => {
+            try {
+                return ev.statusText ? JSON.parse(ev.statusText) : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        if (ev.statusKey === "subsub.web") {
+            this.state = decode();
+            return "state";
+        }
+        if (ev.statusKey === "subsub.find") {
+            this.find = decode();
+            return "find";
+        }
+        return undefined;
+    }
+}
+/** Search the library through the extension (the hidden /subsub-find command); the answer comes back as a status text. */
+export async function findLibrary(agent, side, q) {
+    if (!q)
+        return { q, items: [] };
+    await agent.request({ type: "prompt", message: `/subsub-find ${q}` });
+    return side.find?.q === q ? side.find : { q, items: [] };
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** RPC has no argument hints: read them from the front matter of the prompt files. */
+export function withHints(commands) {
+    return commands.map((c) => {
+        const front = c.source === "prompt" && c.sourceInfo?.path ? frontMatter(readText(c.sourceInfo.path)) : undefined;
+        const hint = front && field(front, "argument-hint");
+        return hint ? { ...c, hint } : c;
+    });
+}

package/dist/screens.js

@@ -13,12 +13,14 @@ export const SCREEN_WORDS = {
         hintNotes: "up and down: choose   type: filter   PgUp PgDn: scroll   ctrl+o: open   Esc: close", hintRead: "up and down: scroll   ctrl+o: open   Esc: back",
         library: "Library", typeToSearch: "Type to search your library.", searching: "Searching...", noItems: "Nothing found.", failed: "The search failed",
         hintLibrary: "up and down: choose   Enter: read   ctrl+n: note   Esc: close", hintLibrarian: "up and down: choose   Enter: copy the key   Esc: close",
+        hintChoice: "up and down: choose   Enter: select   type: filter   Esc: cancel", noChoice: "Nothing matches.", hintInput: "Enter: send   Esc: cancel",
     },
     pt: {
         notes: "Notas", of: "de", filter: "filtro", none: "Ainda não há notas. O Sub-Sub escreve-as em Literature/, Research/ e Syntheses/.", noMatch: "Nenhuma nota corresponde.", empty: "(nota vazia)",
         hintNotes: "cima e baixo: escolher   escrever: filtrar   PgUp PgDn: deslocar   ctrl+o: abrir   Esc: fechar", hintRead: "cima e baixo: deslocar   ctrl+o: abrir   Esc: voltar",
         library: "Biblioteca", typeToSearch: "Escreva para pesquisar na biblioteca.", searching: "A pesquisar...", noItems: "Nada encontrado.", failed: "A pesquisa falhou",
         hintLibrary: "cima e baixo: escolher   Enter: ler   ctrl+n: nota   Esc: fechar", hintLibrarian: "cima e baixo: escolher   Enter: copiar a chave   Esc: fechar",
+        hintChoice: "cima e baixo: escolher   Enter: selecionar   escrever: filtrar   Esc: cancelar", noChoice: "Nada corresponde.", hintInput: "Enter: enviar   Esc: cancelar",
     },
 };
 const LEFT = 36;
@@ -312,3 +314,112 @@ export class LibraryView {
         this.o.redraw?.();
     }
 }
+export function choiceLines(o) {
+    const g = o.glyphs ?? UNICODE;
+    const p = o.paint;
+    const w = Math.max(20, o.width);
+    const words = SCREEN_WORDS[o.lang];
+    const room = Math.max(1, o.rows - 4);
+    const out = [p.mark(cut(` ${o.title}`, w)) + (o.filter ? p.muted(cut(`   ${words.filter}: ${o.filter}`, Math.max(0, w - o.title.length - 1))) : ""), rule(w, "solid", p.muted, g)];
+    if (!o.choices.length)
+        out.push(p.muted(cut(`  ${words.noChoice}`, w)));
+    const start = Math.max(0, Math.min(o.selected - Math.floor(room / 2), o.choices.length - room));
+    for (const [k, c] of o.choices.slice(start, start + room).entries()) {
+        const chosen = start + k === o.selected;
+        const hint = c.hint ? `  ${c.hint}` : "";
+        const label = cut(c.label, Math.max(8, w - 2 - hint.length));
+        out.push(`${chosen ? p.mark(g.pointer) : " "} ${chosen ? p.text(label) : p.muted(label)}${p.dim(cut(hint, Math.max(0, w - 2 - label.length)))}`);
+    }
+    out.push(rule(w, "solid", p.muted, g), ...wrapTextWithAnsi(` ${words.hintChoice}`, w).map((l) => p.muted(l)));
+    return out;
+}
+export class ChoiceView {
+    o;
+    filter = "";
+    selected = 0;
+    answered = false;
+    constructor(o) {
+        this.o = o;
+    }
+    shown() {
+        const f = this.filter.toLowerCase();
+        return f ? this.o.choices.filter((c) => `${c.label} ${c.hint ?? ""}`.toLowerCase().includes(f)) : this.o.choices;
+    }
+    render(width) {
+        const rows = Math.max(8, Math.floor(((this.o.rows?.() ?? 24) * 8) / 10));
+        return fill(choiceLines({ title: this.o.title, choices: this.shown(), selected: this.selected, filter: this.filter, width, rows, lang: this.o.lang, paint: this.o.paint, glyphs: this.o.glyphs }), width);
+    }
+    invalidate() { }
+    handleInput(data) {
+        if (this.answered)
+            return;
+        const list = this.shown();
+        if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+            this.answered = true;
+            return this.o.cancel();
+        }
+        if (matchesKey(data, "enter")) {
+            const c = list[this.selected];
+            if (!c)
+                return;
+            this.answered = true;
+            return this.o.choose(c.value);
+        }
+        if (matchesKey(data, "up"))
+            this.selected = Math.max(0, this.selected - 1);
+        else if (matchesKey(data, "down"))
+            this.selected = Math.min(Math.max(0, list.length - 1), this.selected + 1);
+        else if (matchesKey(data, "backspace")) {
+            this.filter = this.filter.slice(0, -1);
+            this.selected = 0;
+        }
+        else if (printable(data)) {
+            this.filter += data;
+            this.selected = 0;
+        }
+        else
+            return;
+        this.o.redraw?.();
+    }
+}
+export function inputLines(o) {
+    const g = o.glyphs ?? UNICODE;
+    const p = o.paint;
+    const w = Math.max(20, o.width);
+    const shown = o.text ? p.text(cut(o.text, w - 5)) + p.mark("_") : p.dim(cut(o.placeholder ?? "", w - 5)) + p.mark("_");
+    return [p.mark(cut(` ${o.title}`, w)), rule(w, "solid", p.muted, g), ` ${p.muted(">")} ${shown}`, rule(w, "solid", p.muted, g), p.muted(cut(` ${SCREEN_WORDS[o.lang].hintInput}`, w))];
+}
+export class InputView {
+    o;
+    text;
+    answered = false;
+    constructor(o) {
+        this.o = o;
+        this.text = o.prefill ?? "";
+    }
+    render(width) {
+        return fill(inputLines({ title: this.o.title, placeholder: this.o.placeholder, text: this.text, width, lang: this.o.lang, paint: this.o.paint, glyphs: this.o.glyphs }), width);
+    }
+    invalidate() { }
+    handleInput(data) {
+        if (this.answered)
+            return;
+        if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+            this.answered = true;
+            return this.o.cancel();
+        }
+        if (matchesKey(data, "enter")) {
+            this.answered = true;
+            return this.o.submit(this.text);
+        }
+        if (matchesKey(data, "backspace"))
+            this.text = this.text.slice(0, -1);
+        else if (matchesKey(data, "ctrl+u"))
+            this.text = "";
+        else if (printable(data))
+            this.text += data;
+        else
+            return;
+        this.o.redraw?.();
+    }
+}

package/dist/subsub.js

@@ -143,6 +143,8 @@ export async function createSubsub(pi, deps = {}) {
     const lookOn = (ctx) => standalone && cfg.look !== false && ctx.mode === "tui";
     /** True under `subsub web`: pi runs in RPC mode and the web view shows the state that the terminal header shows. */
     const webView = process.env.SUBSUB_WEB === "1";
+    /** The state of the library goes to the client as a status text: for the web view and for the full-screen terminal client (subsub tui). */
+    const sideChannel = webView || process.env.SUBSUB_TUI === "1";
     let lastError;
     /** The last provider or tool error of the session, for /feedback. */
     let recentError;
@@ -153,7 +155,7 @@ export async function createSubsub(pi, deps = {}) {
     let webCtx;
     function emitWeb() {
         const ctx = webCtx;
-        if (!webView || !ctx || ctx.mode !== "rpc")
+        if (!sideChannel || !ctx || ctx.mode !== "rpc")
             return;
         const down = bridge ? Object.keys(bridge.errors) : ["zotero", "scholar"];
         const state = {
@@ -418,7 +420,7 @@ export async function createSubsub(pi, deps = {}) {
             setFooter(ctx);
             void refreshLibrary();
         }
-        else if (webView) {
+        else if (sideChannel) {
             void refreshLibrary();
         }
         if (!ctx.model && !webView)
@@ -784,10 +786,15 @@ export async function createSubsub(pi, deps = {}) {
         pi.registerCommand("notes", { description: "Sub-Sub: the notes in your Sub-Sub folder", handler: async (_args, ctx) => openNotes(ctx) });
         pi.registerCommand("library", { description: "Sub-Sub: search your Zotero library as you type", handler: async (_args, ctx) => openLibrary(ctx) });
         pi.registerCommand("actions", { description: "Sub-Sub: the actions of the web view, as a list", handler: async (_args, ctx) => openActions(ctx) });
-        pi.registerShortcut?.("alt+n", { description: "Sub-Sub: notes", handler: (ctx) => openNotes(ctx) });
-        pi.registerShortcut?.("alt+l", { description: "Sub-Sub: library search", handler: (ctx) => openLibrary(ctx) });
-        pi.registerShortcut?.("alt+a", { description: "Sub-Sub: actions", handler: (ctx) => openActions(ctx) });
-        pi.registerShortcut?.("alt+m", { description: "Sub-Sub: switch between the Researcher and the Librarian", handler: (ctx) => switchTo(ctx, mode === "researcher" ? "librarian" : "researcher") });
+        // Alt works when the terminal sends it as Escape plus the letter; macOS Terminal and iTerm2 do not by default (Option types a symbol), so each also has a function key.
+        const keys = (names, description, handler) => {
+            for (const k of names)
+                pi.registerShortcut?.(k, { description, handler });
+        };
+        keys(["alt+n", "f2"], "Sub-Sub: notes", (ctx) => openNotes(ctx));
+        keys(["alt+l", "f3"], "Sub-Sub: library search", (ctx) => openLibrary(ctx));
+        keys(["alt+a", "f4"], "Sub-Sub: actions", (ctx) => openActions(ctx));
+        keys(["alt+m", "f5"], "Sub-Sub: switch between the Researcher and the Librarian", (ctx) => switchTo(ctx, mode === "researcher" ? "librarian" : "researcher"));
     }
     pi.registerCommand("subsub", {
         description: "Sub-Sub: Zotero connection and library overview",