botholomew 0.7.0 → 0.7.1

package/README.md

@@ -6,4 +6,221 @@
   " "
 ```
 
-An AI agent for knowledge work.
+**A local-first AI agent for knowledge work.** Botholomew is a long-running
+autonomous agent that works its way through a task queue — reading email,
+summarizing documents, researching topics, organizing notes, and maintaining
+context over time — while you sleep, work, or chat with it.
+
+Unlike coding agents, Botholomew has **no shell, no filesystem, and no network
+tools** by default. Everything it touches lives inside a single DuckDB database
+at `.botholomew/data.duckdb` and a handful of markdown files. External access
+is granted deliberately, per project, through MCP servers.
+
+---
+
+## Why Botholomew?
+
+- **Autonomous.** A background daemon ticks on a schedule, claims tasks,
+  works them with Claude, and logs every interaction. You can close the
+  terminal and come back later.
+- **Portable.** Each project is a `.botholomew/` directory — markdown +
+  DuckDB. Copy it, share it, check it in (or `.gitignore` it).
+- **Local-first.** All data stays on your machine. Embeddings are indexed in
+  DuckDB's native vector store with HNSW. Model calls go direct to Anthropic
+  and OpenAI.
+- **Extensible.** External tools come from MCP servers via
+  [MCPX](https://github.com/evantahler/mcpx) — run them locally (Gmail,
+  Slack, GitHub) or connect through an MCP gateway like
+  [Arcade.dev](https://www.arcade.dev/) to reach hundreds of
+  authenticated services without managing each server yourself.
+  Reusable workflows are defined as markdown "skills" (slash commands).
+- **Safe by default.** The agent has no shell, no network, and no
+  filesystem access of its own. Everything it can touch lives in
+  `.botholomew/` — and every external capability is something you
+  explicitly add.
+- **Self-healing.** An OS-level watchdog (launchd on macOS, systemd on Linux)
+  restarts the daemon if it dies, rotates logs, and runs on boot.
+- **Self-modifying.** The agent maintains its own `beliefs.md` and
+  `goals.md` — it learns, updates its priors, and revises its goals as it
+  works.
+
+---
+
+## Install
+
+Requires [Bun](https://bun.sh) 1.1+.
+
+```bash
+bun install -g botholomew
+```
+
+Or run the dev build from a checkout:
+
+```bash
+git clone https://github.com/evantahler/botholomew
+cd botholomew
+bun install
+bun run dev -- --help
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Initialize a project in the current directory
+botholomew init
+
+# 2. Add your API keys to .botholomew/config.json, or export env vars
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...     # used for embeddings
+
+# 3. Queue some work
+botholomew task add "Summarize every markdown file in ~/notes"
+
+# 4. Start the daemon (foreground — watch it work)
+botholomew daemon start --foreground
+
+# 5. Or chat with the agent interactively
+botholomew chat
+```
+
+---
+
+## What a project looks like
+
+```
+my-project/
+  .botholomew/
+    soul.md               # always-loaded identity (not agent-editable)
+    beliefs.md            # always-loaded, agent-editable priors
+    goals.md              # always-loaded, agent-editable goals
+    config.json           # models, tick interval, API keys
+    data.duckdb           # tasks, schedules, context, embeddings, logs
+    mcpx/servers.json     # external MCP servers (Gmail, Slack, …)
+    skills/               # user-defined slash commands
+      summarize.md
+      standup.md
+    daemon.pid            # PID file for the running daemon
+    daemon.log            # rotating daemon logs
+```
+
+Everything the agent can touch is here. No surprises.
+
+---
+
+## The CLI
+
+| Command | Purpose |
+|---|---|
+| `botholomew init` | Create `.botholomew/` with templates and a fresh database |
+| `botholomew daemon start\|stop\|status` | Run, stop, or inspect the daemon |
+| `botholomew daemon install\|uninstall` | Register/remove the OS watchdog |
+| `botholomew daemon list` | List all Botholomew projects on this machine |
+| `botholomew chat` | Interactive Ink/React TUI |
+| `botholomew task list\|add\|view\|update\|reset\|delete` | Manage the task queue |
+| `botholomew schedule list\|add\|enable\|trigger\|delete` | Recurring work |
+| `botholomew context add\|list\|view\|search\|refresh\|remove` | Ingest & browse knowledge (files, folders, URLs) |
+| `botholomew mcpx add\|list\|tools\|test` | Configure external MCP servers |
+| `botholomew skill list\|show\|create` | Manage slash-command skills |
+| `botholomew file\|dir\|search ...` | Direct access to the agent's virtual filesystem |
+| `botholomew thread list\|view` | Browse the agent's interaction history |
+| `botholomew upgrade` | Self-update |
+
+---
+
+## How it works
+
+```
+ ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
+ │    Chat      │         │   Daemon     │         │  Watchdog    │
+ │   (Ink TUI)  │         │  (tick loop) │         │ launchd/     │
+ │              │         │              │         │ systemd      │
+ └──────┬───────┘         └──────┬───────┘         └──────┬───────┘
+        │                        │                        │
+        │ enqueue tasks          │ claims tasks           │ every 60s:
+        │ browse history         │ runs LLM tool loops    │ check PID
+        │ invoke skills          │ updates status         │ restart if
+        │                        │ logs to threads        │ dead
+        │                        │                        │
+        └────────────┬───────────┴────────────┬───────────┘
+                     │                        │
+               ┌─────▼────────────────────────▼─────┐
+               │        DuckDB                       │
+               │  ┌───────────┐ ┌──────────────┐    │
+               │  │  tasks    │ │ context_items│    │
+               │  │ schedules │ │  embeddings  │    │
+               │  │  threads  │ │   (HNSW)     │    │
+               │  └───────────┘ └──────────────┘    │
+               └─────┬───────────────────────────────┘
+                     │
+                     ▼
+              MCPX ─► Gmail, Slack, GitHub, Firecrawl, …
+```
+
+See [docs/architecture.md](docs/architecture.md) for a deeper tour.
+
+---
+
+## Deep dives
+
+Topics worth understanding in detail:
+
+- **[Architecture](docs/architecture.md)** — daemon, chat, watchdog, and how
+  they share a database.
+- **[The virtual filesystem](docs/virtual-filesystem.md)** — why the agent's
+  "files" are actually DuckDB rows, and how `file_read`/`file_write` work.
+- **[Context & hybrid search](docs/context-and-search.md)** — LLM-driven
+  chunking, OpenAI embeddings, and DuckDB's HNSW-accelerated keyword +
+  vector search.
+- **[Tasks & schedules](docs/tasks-and-schedules.md)** — the claim loop, DAG
+  validation, stale-task recovery, and natural-language recurring schedules.
+- **[The Tool class](docs/tools.md)** — one Zod definition, three consumers
+  (Anthropic tool-use, Commander CLI, tests).
+- **[Persistent context](docs/persistent-context.md)** — `soul.md`,
+  `beliefs.md`, `goals.md`, frontmatter flags, and agent self-modification.
+- **[Skills (slash commands)](docs/skills.md)** — reusable prompt templates
+  with positional arguments and tab completion.
+- **[MCPX integration](docs/mcpx.md)** — configuring external servers and
+  how MCP tools are merged into the agent's toolset.
+- **[The watchdog](docs/watchdog.md)** — launchd plists, systemd units, and
+  multi-project service naming.
+- **[Configuration](docs/configuration.md)** — every key in `config.json`
+  and its default.
+
+---
+
+## Tech stack
+
+- **[Bun](https://bun.sh)** + TypeScript
+- **[DuckDB](https://duckdb.org)** via `@duckdb/node-api`, with the
+  **[VSS extension](https://duckdb.org/docs/stable/extensions/vss)** for
+  native vector search
+- **[Anthropic SDK](https://docs.anthropic.com/en/api/client-sdks)** for
+  Claude — the reasoning model
+- **OpenAI embeddings API** (`text-embedding-3-small`, 1536-dim) for
+  semantic search
+- **[MCPX](https://github.com/evantahler/mcpx)** for external tools
+- **[Ink 6](https://github.com/vadimdemedes/ink)** + **React 19** for the
+  terminal UI
+- **[Commander.js](https://github.com/tj/commander.js)** for the CLI
+- **[Zod](https://zod.dev)** for tool input/output schemas
+
+---
+
+## Contributing
+
+```bash
+bun install
+bun test
+bun run lint            # tsc --noEmit + biome check
+```
+
+See [CLAUDE.md](CLAUDE.md) for conventions (always use `bun`, bump the
+version in `package.json` on every merge to `main`, etc.).
+
+---
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "An AI agent for knowledge work",
   "type": "module",
   "bin": {

package/src/commands/chat.ts

@@ -12,7 +12,7 @@ export function registerChatCommand(program: Command) {
         "  Commands:\n" +
         "    /help           Show keyboard shortcuts\n" +
         "    /tools          Open tool call inspector\n" +
-        "    /quit, /exit    End the chat session",
+        "    /exit           End the chat session",
     )
     .option("--thread-id <id>", "Resume an existing chat thread")
     .option("-p, --prompt <text>", "Start chat with an initial prompt")

package/src/skills/commands.ts

@@ -1,6 +1,17 @@
 import type { SkillDefinition } from "./parser.ts";
 import { renderSkill } from "./parser.ts";
 
+export interface SlashCommand {
+  name: string;
+  description: string;
+}
+
+export const BUILTIN_SLASH_COMMANDS: SlashCommand[] = [
+  { name: "help", description: "Show command reference and shortcuts" },
+  { name: "skills", description: "List available skills" },
+  { name: "exit", description: "End the chat session" },
+];
+
 export interface SlashCommandContext {
   skills: Map<string, SkillDefinition>;
   addSystemMessage: (content: string) => void;
@@ -22,7 +33,7 @@ export function handleSlashCommand(
   const name = commandPart.slice(1).toLowerCase(); // remove leading /
 
   // Built-in commands
-  if (name === "quit" || name === "exit") {
+  if (name === "exit") {
     ctx.exit();
     return true;
   }

package/src/tui/App.tsx

@@ -9,7 +9,11 @@ import {
 import { MAX_INLINE_CHARS, PAGE_SIZE_CHARS } from "../daemon/large-results.ts";
 import type { Interaction } from "../db/threads.ts";
 import { getThread } from "../db/threads.ts";
-import { handleSlashCommand } from "../skills/commands.ts";
+import {
+  BUILTIN_SLASH_COMMANDS,
+  handleSlashCommand,
+  type SlashCommand,
+} from "../skills/commands.ts";
 import { ContextPanel } from "./components/ContextPanel.tsx";
 import { HelpPanel } from "./components/HelpPanel.tsx";
 import { InputBar } from "./components/InputBar.tsx";
@@ -27,6 +31,7 @@ import { TaskPanel } from "./components/TaskPanel.tsx";
 import { ThreadPanel } from "./components/ThreadPanel.tsx";
 import type { ToolCallData } from "./components/ToolCall.tsx";
 import { ToolPanel } from "./components/ToolPanel.tsx";
+import { buildSlashCommands, getSlashMatches } from "./slashCompletion.ts";
 import { ansi } from "./theme.ts";
 
 interface AppProps {
@@ -210,10 +215,8 @@ export function App({
   queuedMessagesRef.current = queuedMessages;
   selectedQueueIndexRef.current = selectedQueueIndex;
 
-  const tabConsumedRef = useRef(false);
-  const handleTabConsumed = useCallback(() => {
-    tabConsumedRef.current = true;
-  }, []);
+  const slashCommandsRef = useRef<SlashCommand[]>([]);
+  const inputValueRef = useRef("");
 
   const stableAppHandler = useCallback(
     // biome-ignore lint/suspicious/noExplicitAny: Ink's Key type is not exported
@@ -224,11 +227,15 @@ export function App({
         return;
       }
 
-      // Tab key cycles tabs — unless InputBar consumed it for completion
+      // Tab key cycles tabs — but on the Chat tab, let InputBar consume it
+      // whenever the slash autocomplete popup would be open.
       if (key.tab && !key.shift) {
-        if (tabConsumedRef.current) {
-          tabConsumedRef.current = false;
-          return;
+        if (activeTabRef.current === 1) {
+          const popupOpen = getSlashMatches(
+            inputValueRef.current,
+            slashCommandsRef.current,
+          );
+          if (popupOpen) return;
         }
         setActiveTab((t) => ((t % 7) + 1) as TabId);
         return;
@@ -454,6 +461,10 @@ export function App({
             "  Enter          Send message",
             "  ⌥+Enter        Insert newline",
             "  ↑/↓            Browse input history",
+            "  /              Open slash-command autocomplete",
+            "  Tab/Enter      Accept highlighted command (popup open)",
+            "  ↑/↓            Move highlight (popup open)",
+            "  Esc            Close popup",
             "",
             "Tools (Tab 2):",
             "  ↑/↓            Select tool call",
@@ -495,7 +506,7 @@ export function App({
             "Commands:",
             "  /help           Show this help",
             "  /skills         List available skills",
-            "  /quit, /exit    End the chat session",
+            "  /exit           End the chat session",
             ...skillLines,
           ].join("\n"),
           timestamp: new Date(),
@@ -551,14 +562,19 @@ export function App({
   );
 
   const sessionSkills = ready ? sessionRef.current?.skills : undefined;
-  const skillCompletions = useMemo(() => {
-    const builtins = ["/help", "/quit", "/exit", "/skills"];
-    const skillNames = Array.from(sessionSkills?.keys() ?? []).map(
-      (name) => `/${name}`,
-    );
-    return [...builtins, ...skillNames];
+  const slashCommands = useMemo<SlashCommand[]>(() => {
+    const skillList = sessionSkills
+      ? Array.from(sessionSkills.values()).map((s) => ({
+          name: s.name,
+          description: s.description,
+        }))
+      : [];
+    return buildSlashCommands(BUILTIN_SLASH_COMMANDS, skillList);
   }, [sessionSkills]);
 
+  slashCommandsRef.current = slashCommands;
+  inputValueRef.current = inputValue;
+
   const allToolCalls = useMemo(
     () => messages.flatMap((m) => m.toolCalls ?? []),
     [messages],
@@ -681,8 +697,7 @@ export function App({
         disabled={activeTab !== 1}
         history={inputHistory}
         header={inputBarHeader}
-        completions={skillCompletions}
-        onTabConsumed={handleTabConsumed}
+        slashCommands={slashCommands}
       />
       <TabBar activeTab={activeTab} />
     </Box>

package/src/tui/components/HelpPanel.tsx

@@ -136,7 +136,7 @@ export const HelpPanel = memo(function HelpPanel({
           {"  "}/help{"          "}Show help in chat
         </Text>
         <Text>
-          {"  "}/quit, /exit{"   "}End the chat session
+          {"  "}/exit{"          "}End the chat session
         </Text>
       </Box>
 

package/src/tui/components/InputBar.tsx

@@ -4,9 +4,13 @@ import {
   type ReactNode,
   useCallback,
   useEffect,
+  useMemo,
   useRef,
   useState,
 } from "react";
+import type { SlashCommand } from "../../skills/commands.ts";
+import { getSlashMatches } from "../slashCompletion.ts";
+import { SlashCommandPopup } from "./SlashCommandPopup.tsx";
 
 interface InputBarProps {
   value: string;
@@ -15,8 +19,7 @@ interface InputBarProps {
   disabled: boolean;
   history: string[];
   header?: ReactNode;
-  completions?: string[];
-  onTabConsumed?: () => void;
+  slashCommands?: SlashCommand[];
 }
 
 export const InputBar = memo(function InputBar({
@@ -26,12 +29,13 @@ export const InputBar = memo(function InputBar({
   disabled,
   history,
   header,
-  completions,
-  onTabConsumed,
+  slashCommands,
 }: InputBarProps) {
   const [historyIndex, setHistoryIndex] = useState(-1);
   const [cursorPos, setCursorPos] = useState(0);
   const [cursorVisible, setCursorVisible] = useState(true);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [popupDismissed, setPopupDismissed] = useState(false);
   const savedInput = useRef("");
   const lastActivity = useRef(Date.now());
 
@@ -43,9 +47,9 @@ export const InputBar = memo(function InputBar({
   const onChangeRef = useRef(onChange);
   const onSubmitRef = useRef(onSubmit);
   const historyRef = useRef(history);
-  const completionsRef = useRef(completions);
-  const onTabConsumedRef = useRef(onTabConsumed);
-  const tabCycleRef = useRef(-1);
+  const slashCommandsRef = useRef(slashCommands);
+  const selectedIndexRef = useRef(selectedIndex);
+  const popupDismissedRef = useRef(popupDismissed);
 
   valueRef.current = value;
   cursorPosRef.current = cursorPos;
@@ -53,8 +57,39 @@ export const InputBar = memo(function InputBar({
   onChangeRef.current = onChange;
   onSubmitRef.current = onSubmit;
   historyRef.current = history;
-  completionsRef.current = completions;
-  onTabConsumedRef.current = onTabConsumed;
+  slashCommandsRef.current = slashCommands;
+  selectedIndexRef.current = selectedIndex;
+  popupDismissedRef.current = popupDismissed;
+
+  // Matches visible in the autocomplete popup, or null when it should be
+  // hidden (non-slash input, space typed, no matches, or user escaped).
+  const popupMatches = useMemo(() => {
+    if (popupDismissed) return null;
+    return getSlashMatches(value, slashCommands ?? []);
+  }, [value, slashCommands, popupDismissed]);
+
+  // Reset highlight to top whenever the match list changes.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally reset on match-list change, not value change
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [popupMatches?.length]);
+
+  // Clamp highlight if the list shrank (defensive — the effect above usually handles it).
+  useEffect(() => {
+    if (popupMatches && selectedIndex >= popupMatches.length) {
+      setSelectedIndex(Math.max(0, popupMatches.length - 1));
+    }
+  }, [popupMatches, selectedIndex]);
+
+  // Clear the dismissed flag as soon as the user edits the value,
+  // so a fresh "/" reopens the popup.
+  const prevValueRef = useRef(value);
+  useEffect(() => {
+    if (prevValueRef.current !== value && popupDismissed) {
+      setPopupDismissed(false);
+    }
+    prevValueRef.current = value;
+  }, [value, popupDismissed]);
 
   // Blink cursor when input is active — skip ticks while typing so the
   // cursor stays solid and we avoid unnecessary renders during rapid input.
@@ -87,8 +122,43 @@ export const InputBar = memo(function InputBar({
       const hIdx = historyIndexRef.current;
       const hist = historyRef.current;
 
-      // Enter: submit (shift+enter or opt+enter inserts newline)
+      // Is the slash popup visible right now? Recompute from the authoritative
+      // ref-state so we don't depend on stale closure values.
+      const popupOpen = !popupDismissedRef.current
+        ? getSlashMatches(val, slashCommandsRef.current ?? [])
+        : null;
+
+      const acceptSelection = () => {
+        if (!popupOpen) return false;
+        const chosen =
+          popupOpen[Math.min(selectedIndexRef.current, popupOpen.length - 1)];
+        if (!chosen) return false;
+        const completed = `/${chosen.name} `;
+        valueRef.current = completed;
+        cursorPosRef.current = completed.length;
+        onChangeRef.current(completed);
+        setCursorPos(completed.length);
+        // A trailing space makes the popup disappear naturally via regex,
+        // but set dismissed too so stray state can't re-open it.
+        setPopupDismissed(true);
+        return true;
+      };
+
+      // Escape: close popup if open, keep value untouched
+      if (key.escape) {
+        if (popupOpen) {
+          setPopupDismissed(true);
+        }
+        return;
+      }
+
+      // Enter: if popup is open, accept selection (do not submit).
+      // Otherwise submit as before.
       if (key.return) {
+        if (popupOpen && !key.shift && !key.meta) {
+          acceptSelection();
+          return;
+        }
         if (key.shift || key.meta) {
           const before = val.slice(0, pos);
           const after = val.slice(pos);
@@ -109,6 +179,14 @@ export const InputBar = memo(function InputBar({
         return;
       }
 
+      // Tab: accept popup selection if open. No-op otherwise.
+      if (key.tab) {
+        if (popupOpen) {
+          acceptSelection();
+        }
+        return;
+      }
+
       // Backspace
       if (key.backspace || key.delete) {
         if (pos > 0) {
@@ -138,81 +216,71 @@ export const InputBar = memo(function InputBar({
         return;
       }
 
-      // History navigation
-      if (key.upArrow && hist.length > 0) {
-        const nextIndex = hIdx + 1;
-        if (nextIndex < hist.length) {
-          if (hIdx === -1) {
-            savedInput.current = val;
-          }
-          historyIndexRef.current = nextIndex;
-          setHistoryIndex(nextIndex);
-          const entry = hist[hist.length - 1 - nextIndex];
-          if (entry !== undefined) {
-            valueRef.current = entry;
-            cursorPosRef.current = entry.length;
-            onChangeRef.current(entry);
-            setCursorPos(entry.length);
-          }
+      // Up/Down: popup navigation when open, history otherwise
+      if (key.upArrow) {
+        if (popupOpen) {
+          const next = Math.max(0, selectedIndexRef.current - 1);
+          selectedIndexRef.current = next;
+          setSelectedIndex(next);
+          return;
         }
-        return;
-      }
-
-      if (key.downArrow && hist.length > 0) {
-        if (hIdx > 0) {
-          const nextIndex = hIdx - 1;
-          historyIndexRef.current = nextIndex;
-          setHistoryIndex(nextIndex);
-          const entry = hist[hist.length - 1 - nextIndex];
-          if (entry !== undefined) {
-            valueRef.current = entry;
-            cursorPosRef.current = entry.length;
-            onChangeRef.current(entry);
-            setCursorPos(entry.length);
+        if (hist.length > 0) {
+          const nextIndex = hIdx + 1;
+          if (nextIndex < hist.length) {
+            if (hIdx === -1) {
+              savedInput.current = val;
+            }
+            historyIndexRef.current = nextIndex;
+            setHistoryIndex(nextIndex);
+            const entry = hist[hist.length - 1 - nextIndex];
+            if (entry !== undefined) {
+              valueRef.current = entry;
+              cursorPosRef.current = entry.length;
+              onChangeRef.current(entry);
+              setCursorPos(entry.length);
+            }
           }
-        } else if (hIdx === 0) {
-          historyIndexRef.current = -1;
-          setHistoryIndex(-1);
-          const saved = savedInput.current;
-          valueRef.current = saved;
-          cursorPosRef.current = saved.length;
-          onChangeRef.current(saved);
-          setCursorPos(saved.length);
         }
         return;
       }
 
-      // Tab-completion for slash commands
-      if (key.tab) {
-        const comps = completionsRef.current;
-        if (val.startsWith("/") && comps && comps.length > 0) {
-          const matches = comps.filter((c) => c.startsWith(val));
-          if (matches.length === 1) {
-            const completed = `${matches[0] ?? ""} `;
-            valueRef.current = completed;
-            cursorPosRef.current = completed.length;
-            onChangeRef.current(completed);
-            setCursorPos(completed.length);
-            tabCycleRef.current = -1;
-          } else if (matches.length > 1) {
-            const idx = (tabCycleRef.current + 1) % matches.length;
-            tabCycleRef.current = idx;
-            const completed = matches[idx] ?? "";
-            valueRef.current = completed;
-            cursorPosRef.current = completed.length;
-            onChangeRef.current(completed);
-            setCursorPos(completed.length);
+      if (key.downArrow) {
+        if (popupOpen) {
+          const next = Math.min(
+            popupOpen.length - 1,
+            selectedIndexRef.current + 1,
+          );
+          selectedIndexRef.current = next;
+          setSelectedIndex(next);
+          return;
+        }
+        if (hist.length > 0) {
+          if (hIdx > 0) {
+            const nextIndex = hIdx - 1;
+            historyIndexRef.current = nextIndex;
+            setHistoryIndex(nextIndex);
+            const entry = hist[hist.length - 1 - nextIndex];
+            if (entry !== undefined) {
+              valueRef.current = entry;
+              cursorPosRef.current = entry.length;
+              onChangeRef.current(entry);
+              setCursorPos(entry.length);
+            }
+          } else if (hIdx === 0) {
+            historyIndexRef.current = -1;
+            setHistoryIndex(-1);
+            const saved = savedInput.current;
+            valueRef.current = saved;
+            cursorPosRef.current = saved.length;
+            onChangeRef.current(saved);
+            setCursorPos(saved.length);
           }
-          onTabConsumedRef.current?.();
         }
         return;
       }
 
-      // Reset tab cycle on any non-tab key
-      tabCycleRef.current = -1;
-
       // Ignore other control keys
-      if (key.ctrl || key.escape) {
+      if (key.ctrl) {
         return;
       }
 
@@ -239,36 +307,45 @@ export const InputBar = memo(function InputBar({
 
   const isMultiline = value.includes("\n");
   const placeholder = !value && !disabled;
+  const showPopup = !disabled && popupMatches !== null;
 
   return (
-    <Box
-      flexDirection="column"
-      borderStyle="single"
-      borderColor={disabled ? "gray" : "green"}
-      paddingX={1}
-    >
-      {header}
-      {!disabled && (
-        <Box flexDirection="column">
-          <Box>
-            <Text color="green">{"› "}</Text>
-            {placeholder ? (
-              <Text dimColor>Type a message...</Text>
-            ) : (
-              <Text>
-                {value.slice(0, cursorPos)}
-                <Text inverse={cursorVisible}>{value[cursorPos] ?? " "}</Text>
-                {value.slice(cursorPos + 1)}
-              </Text>
-            )}
-          </Box>
-          {isMultiline && (
+    <Box flexDirection="column">
+      {showPopup && popupMatches && (
+        <SlashCommandPopup
+          matches={popupMatches}
+          selectedIndex={selectedIndex}
+        />
+      )}
+      <Box
+        flexDirection="column"
+        borderStyle="single"
+        borderColor={disabled ? "gray" : "green"}
+        paddingX={1}
+      >
+        {header}
+        {!disabled && (
+          <Box flexDirection="column">
             <Box>
-              <Text dimColor> alt+return for newline, return to send</Text>
+              <Text color="green">{"› "}</Text>
+              {placeholder ? (
+                <Text dimColor>Type a message...</Text>
+              ) : (
+                <Text>
+                  {value.slice(0, cursorPos)}
+                  <Text inverse={cursorVisible}>{value[cursorPos] ?? " "}</Text>
+                  {value.slice(cursorPos + 1)}
+                </Text>
+              )}
             </Box>
-          )}
-        </Box>
-      )}
+            {isMultiline && (
+              <Box>
+                <Text dimColor> alt+return for newline, return to send</Text>
+              </Box>
+            )}
+          </Box>
+        )}
+      </Box>
     </Box>
   );
 });

package/src/tui/components/SlashCommandPopup.tsx

@@ -0,0 +1,50 @@
+import { Box, Text } from "ink";
+import { memo } from "react";
+import type { SlashCommand } from "../../skills/commands.ts";
+
+interface SlashCommandPopupProps {
+  matches: SlashCommand[];
+  selectedIndex: number;
+}
+
+export const SlashCommandPopup = memo(function SlashCommandPopup({
+  matches,
+  selectedIndex,
+}: SlashCommandPopupProps) {
+  if (matches.length === 0) return null;
+
+  const nameWidth = matches.reduce(
+    (max, c) => Math.max(max, c.name.length + 1),
+    0,
+  );
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor="gray"
+      paddingX={1}
+    >
+      {matches.map((cmd, i) => {
+        const active = i === selectedIndex;
+        const marker = active ? "›" : " ";
+        const padded = `/${cmd.name}`.padEnd(nameWidth + 1);
+        return (
+          <Box key={cmd.name}>
+            <Text color={active ? "green" : undefined} bold={active}>
+              {marker} {padded}
+            </Text>
+            <Text dimColor={!active}>
+              {cmd.description || "(no description)"}
+            </Text>
+          </Box>
+        );
+      })}
+      <Box marginTop={0}>
+        <Text dimColor>
+          ↑↓ to navigate · tab/return to accept · esc to close
+        </Text>
+      </Box>
+    </Box>
+  );
+});

package/src/tui/slashCompletion.ts

@@ -0,0 +1,38 @@
+import type { SlashCommand } from "../skills/commands.ts";
+
+export const MAX_VISIBLE_COMPLETIONS = 8;
+
+const SLASH_QUERY = /^\/([\w-]*)$/;
+
+/**
+ * Given the current input value, return the list of slash commands that
+ * should appear in the autocomplete popup. Returns `null` when the popup
+ * should not be shown at all (e.g. the input isn't a slash query, or the
+ * user has already typed a space to start writing arguments).
+ */
+export function getSlashMatches(
+  value: string,
+  commands: SlashCommand[],
+): SlashCommand[] | null {
+  const match = SLASH_QUERY.exec(value);
+  if (!match) return null;
+
+  const query = (match[1] ?? "").toLowerCase();
+  const filtered = commands.filter((c) =>
+    c.name.toLowerCase().startsWith(query),
+  );
+  if (filtered.length === 0) return null;
+
+  return filtered.slice(0, MAX_VISIBLE_COMPLETIONS);
+}
+
+export function buildSlashCommands(
+  builtins: SlashCommand[],
+  skills: Iterable<{ name: string; description: string }>,
+): SlashCommand[] {
+  const out: SlashCommand[] = [...builtins];
+  for (const s of skills) {
+    out.push({ name: s.name, description: s.description });
+  }
+  return out;
+}