summon-cli 0.2.0 → 0.4.0

package/README.md

@@ -6,36 +6,134 @@
 
 Terminal launcher for local AI CLIs. Run `summon`, pick a tool, launch it.
 
-Supported: Codex CLI, Claude Code, Antigravity CLI, Cursor CLI, GitHub Copilot CLI, opencode CLI. Missing tools show dimmed.
+Built-in: Codex CLI, Claude Code, Antigravity CLI, Cursor CLI, GitHub Copilot CLI, opencode CLI. Missing tools show dimmed. Add your own with `--add`.
 
-> Pre-release (0.1.0).
+> Pre-release (0.4.0).
 
 ## Install
 
 ```sh
 npm install -g summon-cli
+```
+
+## First run
+
+The first launch walks you through a one-time setup (and keeps asking until you finish it):
+
+```sh
 summon
 ```
 
-Move with arrows or `j/k` or `1-9`. `Enter` launches, `Esc` quits.
+Two steps:
+
+1. **Command name** — pick what you'll type to open the launcher. The default is `cli`; `summon` always keeps working. Picking `cli` (or a custom name) installs a small shim in `~/.local/bin`.
+2. **Side logo** — show the animated logo next to the menu, or keep it compact.
+
+Your choices are saved to the [config](#config). Re-run the wizard anytime:
+
+```sh
+summon setup
+```
+
+> If `~/.local/bin` isn't on your `PATH`, the wizard tells you — add it so your new command name resolves:
+> ```sh
+> export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc
+> ```
+
+## Daily use
+
+Open the picker and launch a tool:
+
+```sh
+cli            # or: summon
+```
+
+- **Move** — `↑/↓`, `j/k`, or `1`–`9`
+- **Launch** — `Enter`
+- **Quit** — `Esc`
+
+Missing tools show dimmed. The side logo hides automatically on small terminals.
 
-## Commands
+Pass arguments straight through to the launched tool with `--`:
 
-- `summon` open the picker
-- `summon reorder` set the order
-- `summon default <tool>` start the cursor on it (`off` clears, no arg = pick)
-- `summon alias <name>` add another command name (e.g. `summon alias cli`), or shortcut `summon --add <name>`
-- `summon help`
+```sh
+cli -- --version
+```
+
+## Customize
 
-Flags: `--no-logo` / `--logo` toggle the side logo (remembered). Args after `--` go to the launched tool.
+Add your own CLI with an interactive form (one field at a time — command, name, subtitle):
+
+```sh
+cli add
+```
+
+<p align="center">
+  <img src="assets/add-form.png" alt="Filling in the add form" width="640">
+  <br>
+  <em>Fill each field, then <code>Enter</code> on the last one to save…</em>
+  <br><br>
+  <img src="assets/add-result.png" alt="The new shortcut in the picker" width="640">
+  <br>
+  <em>…and it shows up in the picker.</em>
+</p>
+
+Or add one in a single line:
+
+```sh
+cli --add grok "Grok Build"     # runs `grok`, shows as "Grok Build"
+cli --remove grok               # remove it again
+```
+
+Set the order tools appear in, or where the cursor starts:
+
+```sh
+cli reorder                     # arrange the list
+cli default claude              # open with the cursor on Claude
+cli default off                 # clear it
+```
+
+Toggle the side logo without re-running setup (remembered):
+
+```sh
+cli --logo
+cli --no-logo
+```
+
+Install an extra command name for the launcher at any time:
+
+```sh
+cli alias zap                   # now `zap` opens it too
+```
+
+## Commands & flags
+
+```text
+cli                  open the picker
+cli reorder          set the order tools appear in
+cli default [tool]   start the cursor on <tool> (off clears, no arg = pick)
+cli alias <name>     install another shell command name for the launcher
+cli add              add a custom CLI via an interactive form
+cli setup            re-run the first-run setup (command name + logo)
+cli help             show help
+
+--add [cmd] [label]  add a custom CLI (no args opens the form)
+--remove <id>        remove a custom CLI
+--logo / --no-logo   show / hide the side logo (remembered)
+-- <args...>         pass everything after -- to the launched tool
+```
 
 ## Config
 
-`~/.config/summon-cli/config.json`
+```text
+~/.config/summon-cli/config.json
+```
+
+Holds your order, default tool, custom tools, logo preference, and the setup flag. Safe to delete — the next run rebuilds it and re-runs setup.
 
 ## Requirements
 
-Node 18+, a TrueColor terminal, the target CLIs on PATH.
+Node 18+, a TrueColor terminal, and the target CLIs on your `PATH`.
 
 ## Trademarks
 

package/bin/cli.mjs

@@ -8,12 +8,19 @@ import {join} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import React from 'react';
 import {render} from 'ink';
-import {App, ReorderApp, renderSnapshot, tools, orderTools} from '../src/app.mjs';
+import {App, ReorderApp, SetupApp, AddApp, renderSnapshot, tools, orderTools} from '../src/app.mjs';
 import {loadConfig, saveConfig, configLocation} from '../src/config.mjs';
 
 const PROG = process.env.CLI_LEVEL_NAME || 'summon';
 const SCRIPT = fileURLToPath(import.meta.url);
 
+const ALIAS_OPTIONS = [
+  {name: 'summon', hint: 'the original name'},
+  {name: 'cli', hint: 'short', default: true},
+  {kind: 'custom', label: 'Custom…', hint: 'type your own'},
+  {kind: 'skip', label: 'Skip', hint: 'set one up later'}
+];
+
 const passthroughIndex = process.argv.indexOf('--');
 const forwardedArgs = passthroughIndex === -1 ? [] : process.argv.slice(passthroughIndex + 1);
 const rawArgs = passthroughIndex === -1 ? process.argv.slice(2) : process.argv.slice(2, passthroughIndex);
@@ -31,10 +38,11 @@ if (flags.has('--no-logo')) {
   logo = true;
   saveConfig({logo: true});
 }
-const items = orderTools(config.order);
+const items = orderTools(config.order, config.customTools);
+const canRenderTui = Boolean(process.stdin.isTTY && process.stdout.isTTY && process.env.TERM !== 'dumb');
 
 if (process.env.CLI_LEVEL_SNAPSHOT === '1') {
-  process.stdout.write(renderSnapshot(Number(process.env.CLI_LEVEL_ACTIVE || 0)));
+  process.stdout.write(renderSnapshot(Number(process.env.CLI_LEVEL_ACTIVE || 0), items));
   process.exit(0);
 }
 
@@ -44,11 +52,18 @@ if (flags.has('--help') || flags.has('-h') || command === 'help') {
 }
 
 if (flags.has('--add')) {
-  runAlias(args[0]);
+  if (args[0]) {
+    addCustomTool(args[0], args[1]);
+    process.exit(0);
+  }
+  await runAddForm();
   process.exit(0);
 }
 
-const canRenderTui = Boolean(process.stdin.isTTY && process.stdout.isTTY && process.env.TERM !== 'dumb');
+if (flags.has('--remove') || flags.has('--rm')) {
+  runRemove(args[0]);
+  process.exit(0);
+}
 
 switch (command) {
   case 'reorder':
@@ -60,6 +75,12 @@ switch (command) {
   case 'alias':
     runAlias(args[1]);
     break;
+  case 'add':
+    await runAddForm();
+    break;
+  case 'setup':
+    await runSetupCommand();
+    break;
   case undefined:
     await runMenu();
     break;
@@ -70,11 +91,13 @@ switch (command) {
 
 async function runMenu() {
   if (!canRenderTui) {
-    process.stdout.write(renderSnapshot(0));
+    process.stdout.write(renderSnapshot(0, items));
     process.stderr.write(`${PROG}: interactive terminal required for selection.\n`);
     process.exit(2);
   }
 
+  await maybeFirstRunSetup();
+
   clearScreen();
   const selected = await chooseTool();
   if (!selected) {
@@ -91,6 +114,7 @@ async function runReorder() {
   const order = await new Promise(resolve => {
     let instance;
     instance = render(React.createElement(ReorderApp, {
+      items,
       onCancel: () => {
         instance.unmount();
         resolve(null);
@@ -140,9 +164,143 @@ async function runDefault(target) {
   process.stdout.write(`Default set to ${selected.label}. The menu now opens with the cursor on it.\n`);
 }
 
+async function runAddForm() {
+  requireTui('add');
+  clearScreen();
+  const result = await new Promise(resolve => {
+    let instance;
+    instance = render(React.createElement(AddApp, {
+      onSubmit: data => {
+        instance.unmount();
+        resolve(data);
+      },
+      onCancel: () => {
+        instance.unmount();
+        resolve(null);
+      }
+    }));
+  });
+
+  if (!result) {
+    process.stdout.write('Add cancelled.\n');
+    return;
+  }
+
+  addCustomTool(result.command, result.label, result.hint);
+}
+
+function addCustomTool(name, label, hint) {
+  if (!name || !/^[a-zA-Z0-9._-]+$/.test(name)) {
+    process.stderr.write(`${PROG}: usage: ${PROG} --add <command> [label]\n`);
+    process.exit(2);
+  }
+
+  const id = name.toLowerCase();
+  if (tools.some(t => t.id === id)) {
+    process.stderr.write(`${PROG}: '${id}' is a built-in tool already.\n`);
+    process.exit(2);
+  }
+
+  const current = loadConfig().customTools || [];
+  if (current.some(t => t.id === id)) {
+    process.stderr.write(`${PROG}: '${id}' is already in your list.\n`);
+    process.exit(2);
+  }
+
+  const labelText = label || (name.charAt(0).toUpperCase() + name.slice(1));
+  const entry = {id, label: labelText, command: name, hint: hint || 'Custom provider'};
+  saveConfig({customTools: [...current, entry]});
+  process.stdout.write(`Added '${labelText}' (command: ${name}) to the menu.\n`);
+}
+
+function runRemove(name) {
+  if (!name) {
+    process.stderr.write(`${PROG}: usage: ${PROG} --remove <id>\n`);
+    process.exit(2);
+  }
+
+  const id = name.toLowerCase();
+  const current = loadConfig().customTools || [];
+  const next = current.filter(t => t.id !== id);
+  if (next.length === current.length) {
+    process.stderr.write(`${PROG}: no custom tool '${id}'. List: ${current.map(t => t.id).join(', ') || '(none)'}.\n`);
+    process.exit(2);
+  }
+
+  saveConfig({customTools: next});
+  process.stdout.write(`Removed '${id}'.\n`);
+}
+
+function runSetup() {
+  return new Promise(resolve => {
+    let instance;
+    instance = render(React.createElement(SetupApp, {
+      aliasOptions: ALIAS_OPTIONS,
+      onComplete: result => {
+        instance.unmount();
+        resolve(result);
+      },
+      onCancel: () => {
+        instance.unmount();
+        resolve(null);
+      }
+    }));
+  });
+}
+
+async function maybeFirstRunSetup() {
+  // Already launched through an installed alias shim — nothing to set up.
+  if (process.env.CLI_LEVEL_NAME) {
+    saveConfig({setupDone: true});
+    return;
+  }
+  if (loadConfig().setupDone) {
+    return;
+  }
+
+  const result = await runSetup();
+  if (!result) {
+    // Bailed out without finishing — leave setupDone false so we ask again next launch.
+    return;
+  }
+  saveConfig({setupDone: true});
+
+  // Installing a brand-new alias prints instructions — stop before the menu so they stay visible.
+  if (applySetup(result)) {
+    process.exit(0);
+  }
+}
+
+async function runSetupCommand() {
+  requireTui('setup');
+  clearScreen();
+  const result = await runSetup();
+  if (!result) {
+    process.stdout.write('Setup cancelled.\n');
+    return;
+  }
+  saveConfig({setupDone: true});
+  applySetup(result);
+  process.stdout.write('Setup saved.\n');
+}
+
+// Persist the wizard's choices. Returns true if a new alias shim was installed.
+function applySetup(result) {
+  saveConfig({logo: result.logo});
+  logo = result.logo;
+
+  const chosen = result.alias;
+  if (chosen && chosen.name && !commandExists(chosen.name)) {
+    runAlias(chosen.name);
+    process.stdout.write(`\nStart it with: ${chosen.name}\n`);
+    return true;
+  }
+  return false;
+}
+
 function runAlias(name) {
   if (!name || !/^[a-zA-Z0-9._-]+$/.test(name)) {
-    process.stderr.write(`${PROG}: usage: ${PROG} alias <name>  (or ${PROG} --add <name>)\n`);
+    process.stderr.write(`${PROG}: usage: ${PROG} alias <name>\n`);
     process.exit(2);
   }
 
@@ -243,12 +401,14 @@ Commands:
   (none)            Open the picker
   reorder           Set the order tools appear in
   default [tool]    Start the cursor on <tool>; no tool = pick one; 'off' clears
-  alias <name>      Install a second command name for this launcher
-                    (shortcut: ${PROG} --add <name>)
+  alias <name>      Install a second shell command name for this launcher
+  add               Add a custom CLI via an interactive form
+  setup             Re-run the first-run setup (command name + logo)
   help              Show this help
 
 Options:
-  --add <name>      Install a second command name (same as 'alias')
+  --add [cmd] [lbl] Add a custom CLI (no args opens the form; e.g. --add grok "Grok Build")
+  --remove <id>     Remove a custom CLI from the menu
   --no-logo         Hide the side logo and remember it
   --logo            Show the side logo and remember it
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "summon-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Summon your AI CLI. Terminal launcher for Codex CLI, Claude Code, Antigravity CLI, Cursor CLI, GitHub Copilot CLI, and opencode CLI.",
   "type": "module",
   "bin": {
-    "summon": "./bin/cli.mjs"
+    "summon": "bin/cli.mjs"
   },
   "files": [
     "bin",

package/src/app.mjs

@@ -12,13 +12,6 @@ const dimGray = '#3f4348';
 const white = '#ffffff';
 
 export const tools = [
-  {
-    id: 'codex',
-    label: 'Codex',
-    command: 'codex',
-    hint: 'OpenAI',
-    palette: ['#4750d8', '#6b75f2', '#9aa2ff', '#cdd2ff', '#5b63e6', '#3d44c4']
-  },
   {
     id: 'claude',
     label: 'Claude',
@@ -27,11 +20,11 @@ export const tools = [
     palette: ['#ca7c5e', '#e3a888', '#b5654a']
   },
   {
-    id: 'antigravity',
-    label: 'Antigravity',
-    command: 'agy',
-    hint: 'Google',
-    palette: ['#2e88f5', '#3fb0a0', '#66b37f', '#f0883e', '#e15550', '#8d77c4', '#4f7ce0']
+    id: 'codex',
+    label: 'Codex',
+    command: 'codex',
+    hint: 'OpenAI',
+    palette: ['#4750d8', '#6b75f2', '#9aa2ff', '#cdd2ff', '#5b63e6', '#3d44c4']
   },
   {
     id: 'cursor',
@@ -40,6 +33,13 @@ export const tools = [
     hint: 'Anysphere',
     palette: ['#ffffff', '#111111']
   },
+  {
+    id: 'antigravity',
+    label: 'Antigravity',
+    command: 'agy',
+    hint: 'Google',
+    palette: ['#2e88f5', '#3fb0a0', '#66b37f', '#f0883e', '#e15550', '#8d77c4', '#4f7ce0']
+  },
   {
     id: 'copilot',
     label: 'Copilot',
@@ -85,22 +85,6 @@ const LOGO_DATA = {
     [g('▄', '#6dc694'), g('▀', '#61c37d', '#62bad5'), g('▀', '#43aeab', '#47a8dc'), g(' '), g(' '), g(' '), g(' '), g('▀', '#4a80ea', '#3d89fb'), g('▀', '#6c73d8', '#4a81f0'), g('▄', '#6579e1')],
     [g('▄', '#67b9f4'), g('▀', '#6bc7a3', '#64b6f6'), g('▀', '#64b6f6'), g(' '), g(' '), g(' '), g(' '), g(' '), g(' '), g('▀', '#3886fb'), g('▀', '#4881f4', '#3883f9'), g('▄', '#3d85fc')]
   ],
-  cursor: [
-    shade('        ▓███▓        '),
-    shade('     ▒█████████▒     '),
-    shade('  ░███████████████░  '),
-    shade(' ███████████████████ '),
-    shade('░███░             ▒█░'),
-    shade('░█████▓          ░██░'),
-    shade('░████████▒      ░███░'),
-    shade('░█████████▓     ████░'),
-    shade('░█████████▓    █████░'),
-    shade('░█████████▓   ██████░'),
-    shade(' █████████▓  ███████ '),
-    shade('  ░███████▓ ██████░  '),
-    shade('     ▒████▓▓███▒     '),
-    shade('        ▓███▓        ')
-  ],
   copilot: [
     solid('╭─╮╭─╮', '#99dbdf'),
     solid('╰─╯╰─╯', '#99dbdf'),
@@ -165,6 +149,7 @@ export function App({items = tools, logo = false, initialId = null, onSelect, on
   }, [items]);
 
   const width = stdout?.columns || 80;
+  const height = stdout?.rows || 24;
 
   useEffect(() => {
     const timer = setInterval(() => setTick(value => value + 1), 110);
@@ -221,7 +206,8 @@ export function App({items = tools, logo = false, initialId = null, onSelect, on
     }
   });
 
-  const showLogo = logo && width >= 74;
+  // Compact mode: skip the logo when the terminal can't comfortably hold it.
+  const showLogo = logo && width >= 74 && height >= LOGO_H + 6;
 
   return (
     React.createElement(Box, {flexDirection: 'column', paddingX: 2, paddingY: 1},
@@ -249,15 +235,15 @@ export function App({items = tools, logo = false, initialId = null, onSelect, on
   );
 }
 
-export function ReorderApp({onDone, onCancel}) {
+export function ReorderApp({items = tools, onDone, onCancel}) {
   const {exit} = useApp();
   const [order, setOrder] = useState([]);
   const [active, setActive] = useState(0);
 
   const seekUnpicked = (from, dir, taken) => {
-    for (let step = 0; step <= tools.length; step += 1) {
-      const index = (from + dir * step + tools.length * (step + 1)) % tools.length;
-      if (!taken.has(tools[index].id)) {
+    for (let step = 0; step <= items.length; step += 1) {
+      const index = (from + dir * step + items.length * (step + 1)) % items.length;
+      if (!taken.has(items[index].id)) {
         return index;
       }
     }
@@ -290,13 +276,13 @@ export function ReorderApp({onDone, onCancel}) {
     }
 
     if (key.return) {
-      const id = tools[active].id;
+      const id = items[active].id;
       if (taken.has(id)) {
         return;
       }
 
       const next = [...order, id];
-      if (next.length === tools.length) {
+      if (next.length === items.length) {
         exit();
         onDone(next);
         return;
@@ -314,7 +300,7 @@ export function ReorderApp({onDone, onCancel}) {
         React.createElement(Text, {color: dimGray}, '  pick first to last')
       ),
       React.createElement(Box, {flexDirection: 'column', gap: 0},
-        tools.map((tool, index) => {
+        items.map((tool, index) => {
           const pos = order.indexOf(tool.id);
           const picked = pos >= 0;
           const isActive = index === active && !picked;
@@ -339,6 +325,267 @@ export function ReorderApp({onDone, onCancel}) {
   );
 }
 
+// First-run wizard: step 1 picks the command name to install, step 2 toggles the logo.
+export function SetupApp({aliasOptions, onComplete, onCancel}) {
+  const {exit} = useApp();
+  const [phase, setPhase] = useState('alias');
+  const [active, setActive] = useState(() => {
+    const index = aliasOptions.findIndex(option => option.default);
+    return index >= 0 ? index : 0;
+  });
+  const [text, setText] = useState('');
+  const [error, setError] = useState(false);
+  const [alias, setAlias] = useState(null);
+  const [logoActive, setLogoActive] = useState(0);
+
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') {
+      exit();
+      onCancel();
+      return;
+    }
+
+    if (phase === 'custom') {
+      if (key.escape) {
+        setPhase('alias');
+        setText('');
+        setError(false);
+        return;
+      }
+      if (key.return) {
+        const name = text.trim();
+        if (/^[a-zA-Z0-9._-]+$/.test(name)) {
+          setAlias({name});
+          setPhase('logo');
+        } else {
+          setError(true);
+        }
+        return;
+      }
+      if (key.backspace || key.delete) {
+        setText(value => value.slice(0, -1));
+        setError(false);
+        return;
+      }
+      if (input && !key.ctrl && !key.meta) {
+        setText(value => value + input);
+        setError(false);
+      }
+      return;
+    }
+
+    if (phase === 'logo') {
+      if (key.escape) {
+        setPhase('alias');
+        return;
+      }
+      if (key.upArrow || key.downArrow || input === 'j' || input === 'k') {
+        setLogoActive(value => (value + 1) % 2);
+        return;
+      }
+      if (key.return) {
+        exit();
+        onComplete({alias, logo: logoActive === 0});
+      }
+      return;
+    }
+
+    // phase === 'alias'
+    if (key.escape) {
+      setAlias({skip: true});
+      setPhase('logo');
+      return;
+    }
+    if (key.upArrow || input === 'k') {
+      setActive(value => (value - 1 + aliasOptions.length) % aliasOptions.length);
+      return;
+    }
+    if (key.downArrow || input === 'j') {
+      setActive(value => (value + 1) % aliasOptions.length);
+      return;
+    }
+    if (key.return) {
+      const option = aliasOptions[active];
+      if (option.kind === 'custom') {
+        setPhase('custom');
+        return;
+      }
+      if (option.kind === 'skip') {
+        setAlias({skip: true});
+        setPhase('logo');
+        return;
+      }
+      setAlias({name: option.name});
+      setPhase('logo');
+    }
+  });
+
+  const frame = children => React.createElement(Box, {flexDirection: 'column', paddingX: 2, paddingY: 1}, children);
+
+  if (phase === 'custom') {
+    return frame([
+      React.createElement(Box, {key: 'h', marginBottom: 1},
+        React.createElement(Text, {bold: true, color: white}, 'Custom command name')
+      ),
+      React.createElement(Box, {key: 'i'},
+        React.createElement(Text, {color: gray}, 'name '),
+        React.createElement(Text, {bold: true, color: white}, '› '),
+        React.createElement(Text, {color: white}, text),
+        React.createElement(Text, {color: dimGray}, '▌')
+      ),
+      React.createElement(Box, {key: 'f', marginTop: 1},
+        React.createElement(Text, {color: error ? '#d96570' : dimGray},
+          error ? 'letters, digits, . _ - only' : 'enter confirm · esc back')
+      )
+    ]);
+  }
+
+  if (phase === 'logo') {
+    const logoOpts = [
+      {label: 'Show logo', hint: 'animated art beside the menu'},
+      {label: 'Hide logo', hint: 'compact, just the list'}
+    ];
+    return frame([
+      React.createElement(Box, {key: 'h', marginBottom: 1, flexDirection: 'column'},
+        React.createElement(Text, {bold: true, color: white}, 'Side logo'),
+        React.createElement(Text, {color: dimGray}, 'step 2 of 2')
+      ),
+      React.createElement(Box, {key: 'l', flexDirection: 'column'},
+        logoOpts.map((opt, index) => {
+          const isActive = index === logoActive;
+          return React.createElement(Box, {key: opt.label, height: 1},
+            React.createElement(Box, {width: 2},
+              React.createElement(Text, {bold: isActive, color: isActive ? white : dimGray}, isActive ? '›' : ' ')
+            ),
+            React.createElement(Box, {width: 12},
+              React.createElement(Text, {bold: isActive, color: isActive ? white : gray}, opt.label)
+            ),
+            React.createElement(Text, {color: dimGray}, opt.hint)
+          );
+        })
+      ),
+      React.createElement(Box, {key: 'f', marginTop: 1},
+        React.createElement(Text, {color: dimGray}, 'enter pick · ↑/↓ move · esc back')
+      )
+    ]);
+  }
+
+  // phase === 'alias'
+  return frame([
+    React.createElement(Box, {key: 'h', marginBottom: 1, flexDirection: 'column'},
+      React.createElement(Text, {bold: true, color: white}, 'Pick the command you’ll type'),
+      React.createElement(Text, {color: dimGray}, 'step 1 of 2 · installs a short name for this launcher')
+    ),
+    React.createElement(Box, {key: 'o', flexDirection: 'column'},
+      aliasOptions.map((option, index) => {
+        const isActive = index === active;
+        const label = option.name || option.label;
+        return React.createElement(Box, {key: label, height: 1},
+          React.createElement(Box, {width: 2},
+            React.createElement(Text, {bold: isActive, color: isActive ? white : dimGray}, isActive ? '›' : ' ')
+          ),
+          React.createElement(Box, {width: 14},
+            React.createElement(Text, {bold: isActive, color: isActive ? white : gray}, label)
+          ),
+          React.createElement(Text, {color: dimGray}, option.hint || '')
+        );
+      })
+    ),
+    React.createElement(Box, {key: 'f', marginTop: 1},
+      React.createElement(Text, {color: dimGray}, 'enter pick · ↑/↓ move · esc skip')
+    )
+  ]);
+}
+
+// Interactive form to add a custom shortcut: one editable field per value.
+export function AddApp({onSubmit, onCancel}) {
+  const {exit} = useApp();
+  const fields = [
+    {key: 'command', label: 'Command', placeholder: 'binary to run, e.g. grok'},
+    {key: 'label', label: 'Name', placeholder: 'shown in the menu (optional)'},
+    {key: 'hint', label: 'Subtitle', placeholder: 'right-side text (optional)'}
+  ];
+  const [values, setValues] = useState({command: '', label: '', hint: ''});
+  const [active, setActive] = useState(0);
+  const [error, setError] = useState('');
+
+  const submit = () => {
+    const command = values.command.trim();
+    if (!/^[a-zA-Z0-9._-]+$/.test(command)) {
+      setError('command: letters, digits, . _ - only');
+      setActive(0);
+      return;
+    }
+    exit();
+    onSubmit({command, label: values.label.trim(), hint: values.hint.trim()});
+  };
+
+  useInput((input, key) => {
+    if (key.escape || (key.ctrl && input === 'c')) {
+      exit();
+      onCancel();
+      return;
+    }
+    if (key.tab || key.downArrow) {
+      setActive(value => (value + 1) % fields.length);
+      return;
+    }
+    if (key.upArrow) {
+      setActive(value => (value - 1 + fields.length) % fields.length);
+      return;
+    }
+    if (key.return) {
+      if (active < fields.length - 1) {
+        setActive(active + 1);
+      } else {
+        submit();
+      }
+      return;
+    }
+    const fieldKey = fields[active].key;
+    if (key.backspace || key.delete) {
+      setValues(value => ({...value, [fieldKey]: value[fieldKey].slice(0, -1)}));
+      setError('');
+      return;
+    }
+    if (input && !key.ctrl && !key.meta) {
+      setValues(value => ({...value, [fieldKey]: value[fieldKey] + input}));
+      setError('');
+    }
+  });
+
+  return React.createElement(Box, {flexDirection: 'column', paddingX: 2, paddingY: 1},
+    React.createElement(Box, {key: 'h', marginBottom: 1, flexDirection: 'column'},
+      React.createElement(Text, {bold: true, color: white}, 'Add a shortcut'),
+      React.createElement(Text, {color: dimGray}, 'tab/↑↓ move · enter next · enter on last saves · esc cancel')
+    ),
+    React.createElement(Box, {key: 'fields', flexDirection: 'column'},
+      fields.map((field, index) => {
+        const isActive = index === active;
+        const value = values[field.key];
+        return React.createElement(Box, {key: field.key, height: 1},
+          React.createElement(Box, {width: 2},
+            React.createElement(Text, {bold: isActive, color: isActive ? white : dimGray}, isActive ? '›' : ' ')
+          ),
+          React.createElement(Box, {width: 10},
+            React.createElement(Text, {color: isActive ? white : gray}, field.label)
+          ),
+          isActive
+            ? React.createElement(Box, null,
+                React.createElement(Text, {color: white}, value),
+                React.createElement(Text, {color: dimGray}, '▌'),
+                value ? null : React.createElement(Text, {color: dimGray}, ` ${field.placeholder}`)
+              )
+            : React.createElement(Text, {color: value ? gray : dimGray}, value || field.placeholder)
+        );
+      })
+    ),
+    React.createElement(Box, {key: 'f', marginTop: 1},
+      React.createElement(Text, {color: error ? '#d96570' : dimGray}, error || 'command is required')
+    )
+  );
+}
+
 function Header({title, tick}) {
   return (
     React.createElement(Box, {marginBottom: 1},
@@ -509,9 +756,10 @@ function renderPlainLine(tool, index, activeIndex) {
   return `${arrow} ${label.padEnd(16)} ${tool.hint}`;
 }
 
-export function renderSnapshot(activeIndex = 0) {
-  const bounded = Math.max(0, Math.min(tools.length - 1, activeIndex));
-  return `${tools.map((tool, index) => renderPlainLine(tool, index, bounded)).join('\n')}\n`;
+export function renderSnapshot(activeIndex = 0, items = null) {
+  const list = items || tools;
+  const bounded = Math.max(0, Math.min(list.length - 1, activeIndex));
+  return `${list.map((tool, index) => renderPlainLine(tool, index, bounded)).join('\n')}\n`;
 }
 
 function commandExists(command) {
@@ -545,8 +793,26 @@ function nextAvailable(current, availability, items) {
 }
 
 // Reorder canonical tools by an array of ids; unknown ids ignored, missing appended.
-export function orderTools(order = []) {
-  const byId = new Map(tools.map(tool => [tool.id, tool]));
+export function buildCustomTool({id, label, command, hint, palette} = {}) {
+  if (!id) return null;
+  return {
+    id,
+    label: label || id,
+    command: command || id,
+    hint: hint || 'Custom provider',
+    palette: palette && palette.length ? palette : ['#9aa0a6', '#cdcdcd']
+  };
+}
+
+export function orderTools(order = [], customTools = []) {
+  const all = [...tools];
+  for (const raw of customTools) {
+    const tool = buildCustomTool(raw);
+    if (!tool) continue;
+    if (all.some(t => t.id === tool.id)) continue;
+    all.push(tool);
+  }
+  const byId = new Map(all.map(tool => [tool.id, tool]));
   const result = [];
   for (const id of order) {
     if (byId.has(id)) {
@@ -554,7 +820,7 @@ export function orderTools(order = []) {
       byId.delete(id);
     }
   }
-  for (const tool of tools) {
+  for (const tool of all) {
     if (byId.has(tool.id)) {
       result.push(tool);
     }

package/src/config.mjs

@@ -8,7 +8,9 @@ const configPath = join(baseDir, 'summon-cli', 'config.json');
 const DEFAULTS = {
   order: [],
   logo: true,
-  default: null
+  default: null,
+  customTools: [],
+  setupDone: false
 };
 
 export function loadConfig() {