@jeffober/thatch 0.1.44 → 0.1.46

package/docs/plans/thatch-actions.md

@@ -66,6 +66,12 @@ substitution, matching the existing systemPrompt/mcpInstructions convention.
 The wrap-up commands (`compact`, `exit`) stay as-is; their checklist text
 becomes a core reused by both templates (already true via `sharedChecklist`).
 
+`/thatch/extract` interacts with opencode's direct extraction (parent idle
+spawns the extractor child; the nudge is only a fallback). The action must
+reuse the same accept/complete semantics and must not fight the `extracting`
+set: if direct extraction is already running for the session, the action
+should report that and stop rather than double-dispatch.
+
 ## Host parity
 
 Commands are markdown or MCP prompts, synced per host. Behavior parity is the
@@ -74,30 +80,52 @@ goal; format differences are documented, not hidden.
 - **opencode** (existing): `installOpencodeCommands` syncs markdown to
   `~/.config/opencode/command/thatch/` on every plugin load.
 - **Claude Code**: native user-level slash commands read markdown from
-  `~/.claude/commands/thatch/` with the same `$ARGUMENTS` substitution.
-  `thatch setup --claude` gains a sync step (idempotent content-compare, same
-  as the opencode installer). Differences: no plugin, so no
+  `~/.claude/commands/thatch/` (user scope) or `.claude/commands/thatch/`
+  (project scope), with the same `$ARGUMENTS` substitution. The sync lives in
+  `setup.ts` alongside the existing installers and follows their patterns:
+  idempotent content-compare like `installSkills`, both global and local
+  scopes, reported in the setup output next to the skills report.
+  (Deviation from the draft below: no `checkSetup` entry. That function
+  answers one question - "is thatch set up at all" - and command files
+  self-heal on every setup run, so flagging their absence as a startup
+  warning would be noise.) Differences: no plugin, so no
   `command.execute.before` arming -- greenlight-token wrap-up commands do not
-  ship to Claude Code; and tool names use the `mcp__thatch__` prefix.
+  ship to Claude Code; and tool names use the `mcp__thatch__` prefix. MCP
+  hosts do have hooks now (session-start reminders, chat-wake stop hooks), so
+  hook wiring is not the barrier; the missing piece is only the plugin's TUI
+  control routes.
 - **Cursor**: no file-based commands. The stdio MCP server (`mcp.ts`) gains
   MCP Prompts support (`prompts/list`, `prompts/get`), which Cursor surfaces
-  as slash commands. Prompt arguments use MCP's
+  as slash commands. The dispatch switch currently handles `initialize`,
+  `tools/list`, `tools/call`, and `ping`; prompts get a `compileTools`-style
+  `compilePrompts()` and two new cases. Prompt arguments use MCP's
   `{{argument}}`-style templating, so each action core gets an MCP-prompt
   rendering alongside the markdown rendering.
 
 README gains "What works in Claude Code" and "What works in Cursor" sections
-listing per-host support without restating the shared docs.
+listing per-host support without restating the shared docs. The parity matrix
+in `docs/dev/mcp-parity.md` gets an Actions row next to the existing
+Wrap-up commands row.
 
 ## Session ID plumbing
 
-`get_extraction_payload` and `extraction_done` take `session_id`. Today the
-nudge carries the ID; an action has no way to know it.
+Since the plan was drafted, `HostToolContext` (tool-defs.ts) landed: every
+tool's `execute` receives the invoking session's ID as a third parameter on
+the opencode path, and the watch tools already consume it. `extraction_done`
+also already has the optional `session_id` with the omit-vs-parent rule in
+its description. The remaining work is narrower than first planned:
+
+- `get_extraction_payload`: `session_id` becomes optional. `execute` uses
+  `args.session_id ?? host?.sessionID`. On the opencode path the wrapper
+  supplies the invoking session, so omitted means "this session."
+- MCP path: the host context is omitted (no session concept), so an omitted
+  `session_id` returns a clear error telling the model to pass the parent
+  session's ID from the extraction nudge.
 
-- opencode path: the thin wrappers in `tools.ts` receive the invoking
-  session's ID from the host. `session_id` becomes optional there; omitted
-  means "the current session."
-- MCP path: there is no session context in a tool call, so `session_id`
-  stays required. The tool description and docs state this plainly.
+One wrinkle to document: the zod arg shape is shared between hosts, so
+optionality is global -- you cannot make the arg required on MCP and optional
+on opencode at the schema level. Enforcement happens in `execute` per host,
+and the arg description must carry the rule so the model self-corrects.
 
 The rule the LLM must apply, stated everywhere the tools are described:
 
@@ -105,10 +133,10 @@ The rule the LLM must apply, stated everywhere the tools are described:
 > parent session's `session_id` when running inside a sub-agent that was
 > dispatched to process another session's extraction queue.
 
-This rule appears in: the tool descriptions in `tool-defs.ts`, the extraction
+This rule appears in: the arg descriptions in `tool-defs.ts`, the extraction
 prompt core (used by both nudge and action envelopes), the fact-extractor
-skill, and the dev docs. Tests cover both paths: omit-resolves-to-current and
-explicit-parent-ID (the existing sub-agent drain bug's regression path).
+skill, and the dev docs. Tests cover both paths: omit-resolves-to-current
+and explicit-parent-ID (the existing sub-agent drain bug's regression path).
 
 ## Decisions
 
@@ -127,18 +155,25 @@ explicit-parent-ID (the existing sub-agent drain bug's regression path).
 - `tests/commands.test.ts` (or the existing plugin tests): command-file
   content assertions per host, including that each action's markdown contains
   its core text verbatim.
+- Claude setup tests: command sync writes, updates only on content change,
+  and `checkSetup` flags a missing or stale command file.
 - MCP tests: `prompts/list` returns every action; `prompts/get` interpolates
-  arguments.
-- Plugin tests: `get_extraction_payload` without `session_id` resolves to the
-  invoking session; with an explicit parent ID, drains the parent's queue.
+  arguments; an omitted-session-ID `get_extraction_payload` call errors with
+  the pass-the-parent-ID message (no host context on the MCP path).
+- Plugin tests: `get_extraction_payload` without `session_id` resolves via
+  the host context to the invoking session; with an explicit parent ID,
+  drains the parent's queue (the existing sub-agent drain bug's regression
+  path).
 - Parity guard: a test asserts every opencode command def has a
   corresponding MCP prompt (and vice versa) except the documented exclusions
   (wrap-up greenlight commands on non-opencode hosts).
 
 ## Docs
 
-- `docs/dev/commands.md` (two-tier: dev doc + user-facing README section):
+- `docs/dev/features/commands.md` and `docs/user/commands.md` (two-tier):
   action list, host parity matrix, session ID rule.
+- `docs/dev/mcp-parity.md`: Actions row in the parity matrix; revisit the
+  Wrap-up commands row if greenlight arming ever lands on MCP hosts.
 - README: "What works in Claude Code" / "What works in Cursor" sections.
 - QA use cases: one auto use case for `/thatch/defrag` end-to-end, one for
   `/thatch/extract` with omitted session ID.

package/docs/user/README.md

@@ -19,6 +19,7 @@ This README is the overview. Each feature has its own guide:
 - [default-behaviors.md](default-behaviors.md): what ships automatically
 - [hygiene.md](hygiene.md): store maintenance signals
 - [deduplication.md](deduplication.md): duplicate detection and resolution
+- [commands.md](commands.md): `/thatch/*` slash commands (on-demand actions and wrap-ups)
 - [skills.md](skills.md): structured workflow skills
 - [code-review.md](code-review.md): multi-agent code review pipeline
 - [setup.md](setup.md): installation and configuration
@@ -242,7 +243,10 @@ Beyond the tools, thatch hooks into opencode itself:
   agent listed, and you re-run the command once they're handled. Text typed
   after the command reaches the agent first, labeled as a `User Message`
   section ahead of the checklist (say goodbye or hand off context:
-  `/thatch/exit Good work - see you tomorrow`).
+  `/thatch/exit Good work - see you tomorrow`). Alongside the wrap-ups,
+  on-demand actions (`/thatch/defrag`, `/thatch/extract`, `/thatch/hygiene`,
+  `/thatch/reflect`) run the memory-maintenance behaviors whenever you want,
+  not just when a nudge fires -- see [commands.md](commands.md).
   A greenlit `/thatch/exit` also unregisters the session from the chat
   directory, so other sessions stop sending it mail. The commands
   self-install into `~/.config/opencode/command/thatch/` at plugin startup;

package/docs/user/cli.md

@@ -46,6 +46,7 @@ Read-only access to the chat directory your opencode sessions share
 
 ```bash
 thatch chat list               # who is registered: name, age, project, topic
+thatch chat list --stale all   # also show stale sessions older than a day
 thatch chat tail               # follow sent and read events, live (JSONL)
 thatch chat tail --once        # print the last 20 messages and exit
 thatch chat tail --once --limit 50   # a longer backlog (or --limit all)
@@ -59,9 +60,15 @@ Stale, each as aligned columns under a header row: how long since its
 last heartbeat, its status (`fresh` or `stale` for opencode sessions;
 `active` or `idle` for Claude Code and Cursor sessions, which only beat
 when a prompt runs), its project, and its topic (the session's title) -
-the fastest way to answer "which session should I talk to about X?" A
+the fastest way to answer "which session should I talk to about X?"
+Rows are grouped by project (alphabetical; sessions with no project
+last), most recently seen first within each project. A
 stale session has missed two heartbeats, about a minute: the opencode
-process hosting it has probably stopped. Color is added only when the
+process hosting it has probably stopped. The stale section shows rows
+up to one day old by default; older ones collapse into a hidden-count
+note so long-dead sessions cannot bury the fresh signal. Pass
+`--stale N` (days) to widen the window or `--stale all` to see every
+stale row. Color is added only when the
 output is a terminal; a pipe prints plain aligned text.
 
 `chat tail` prints the conversation as a JSONL event log: one JSON
@@ -160,7 +167,9 @@ thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
 
 ## Limitations
 
-- Requires `bun` on PATH. Thatch does not bundle its own runtime.
+- For non-Nix installs, `bun` must be installed and on PATH. Thatch does
+  not bundle its own runtime (the Nix package bundles it; see the
+  README's Nix section).
 - `search` is limited to 10 results. There is no pagination.
 - `prime` requires an external CLI (`opencode`, `agent`, or `claude`)
   on PATH. If none is found, it exits with an error.

package/docs/user/commands.md

@@ -0,0 +1,50 @@
+# Slash commands
+
+Thatch ships `/thatch/*` commands you run yourself, on top of the nudges the
+plugin fires on its own schedule. Nudges and commands share the same
+instruction text, so a behavior works the same whether it fires automatically
+or you invoke it.
+
+## Commands
+
+- `/thatch/defrag` — find duplicate-candidate memory pairs and clusters,
+  classify each one, consolidate duplicates, and mark the rest checked.
+  Text after the command narrows the scope (for example, a store name).
+- `/thatch/extract` — drain the extraction queue now, instead of waiting
+  for the next nudge or idle-time extraction. opencode only.
+- `/thatch/hygiene` — run the hygiene report and act on it: stale
+  memories, memories scoped to deleted branches, and pending dedup pairs.
+  The agent asks before forgetting anything that may still matter.
+- `/thatch/reflect` — run the session-reflection skill to persist what the
+  current session learned.
+- `/thatch/compact` and `/thatch/exit` — the wrap-up commands. They run a
+  pre-flight checklist (flush extraction, finish promised memory writes,
+  surface loose ends) before a compaction or an exit, gated by a greenlight
+  token. opencode only; the greenlight mechanics are described in the
+  [user guide overview](README.md).
+
+## Host support
+
+| Command | opencode | Claude Code | Cursor |
+|---|---|---|---|
+| `/thatch/defrag` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/extract` | yes | no | no |
+| `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/compact`, `/thatch/exit` | yes | no | no |
+
+Why the gaps: `/thatch/extract` needs the invoking session's ID, which only
+the opencode plugin can supply. The wrap-up commands trigger TUI actions
+through the plugin. Cursor has no file-based commands; its prompts come from
+the MCP server (`prompts/list` and `prompts/get`).
+
+## Installation
+
+- **opencode**: installed by the plugin on every load.
+- **Claude Code**: installed by `thatch setup --claude` into the same scope
+  as the skills (`.claude/commands/thatch/` project-local, or the Claude
+  config dir for `--global`). Re-run setup to refresh after an upgrade.
+
+Tool names inside the command text follow each host's spelling
+(`thatch_memory_remember` on opencode, `mcp__thatch__memory_remember` on
+Claude Code and Cursor).

package/docs/user/cross-session-chat.md

@@ -8,8 +8,10 @@ between tabs all afternoon.
 
 ## What it does
 
-opencode sessions join the directory automatically, on their first idle
-moment. Names are assigned by thatch, never chosen: a name drawn from a
+opencode sessions join the directory automatically, the moment their
+first user message arrives (before the assistant responds), and a session
+resumed with `opencode -c` or `opencode -s <id>` is back in the directory
+at harness start with its old name. Names are assigned by thatch, never chosen: a name drawn from a
 built-in pool plus a counter (`al-go-rithm-00001`). The counter only ever
 increments, so a name is
 minted exactly once per machine - pruning an old session never reissues its
@@ -60,11 +62,13 @@ toggle reveals those output blocks if you want them.)
 ## How to use it
 
 With auto-registration you usually do nothing: a session joins the
-directory when it first goes idle, and a session continued with
-`opencode -s <id>` is registered again the moment its harness starts -
-same session id, same name, reclaimed. The agent gets a quiet toast with
-its assigned name when it first registers. To introduce two sessions,
-just tell each one who to talk to:
+directory when its first user message arrives, and a session continued
+with `opencode -c` or `opencode -s <id>` is registered again the moment
+its harness starts - same session id, same name, reclaimed. The agent
+gets a quiet toast with
+its assigned name when it first registers, and a resumed session
+announces its reclaimed name on its first prompt. To introduce two
+sessions, just tell each one who to talk to:
 
 > Ask the other session whether the release has shipped; answer its
 > questions directly.

package/docs/user/setup.md

@@ -90,6 +90,7 @@ and `--json` output for hook commands.
 | `THATCH_DB_PATH` | `~/.config/thatch/thatch.db` | SQLite database path |
 | `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Hugging Face model name for embeddings |
 | `THATCH_EMBEDDING_BACKEND` | `wasm` | Set to `native` to run embeddings on onnxruntime-node (NAPI) instead of the wasm runtime |
+| `THATCH_MODEL_CACHE` | platform per-user cache dir | Where downloaded model files are stored |
 | `THATCH_RECALL_THRESHOLD` | `0.55` | Cosine threshold for recall nudge |
 | `THATCH_PREDICTION_THRESHOLD` | `0.60` | Cosine threshold for prediction auto-fire |
 | `THATCH_BEHAVIOR_THRESHOLD` | `0.60` | Cosine threshold for behavior auto-fire |
@@ -110,10 +111,15 @@ instructions are deployed without requiring you to manually re-run
 
 ## Limitations
 
-- `bun` must be installed and on PATH. Thatch does not bundle its
-  own runtime.
+- For non-Nix installs, `bun` must be installed and on PATH. Thatch does
+  not bundle its own runtime (the Nix package bundles it; see the
+  README's Nix section).
 - The embedding model (~34 MB) is downloaded once on first use and
-  cached in `node_modules/@huggingface/transformers/.cache/`.
+  cached in the platform's per-user cache dir
+  (`~/Library/Caches/thatch/models` on macOS (or
+  `$XDG_CACHE_HOME/thatch/models` when `XDG_CACHE_HOME` is set),
+  `$XDG_CACHE_HOME/thatch/models` elsewhere). Override with
+  `THATCH_MODEL_CACHE`.
 - There is no web UI or dashboard. All interaction is through the
   agent's tool calls and the `thatch` CLI.
 - The MCP server is a long-lived process that keeps the embedding model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/chat.ts

@@ -304,17 +304,45 @@ export function chatLiveness(row: ChatSessionRow, now = Date.now()): "fresh" | "
   return stale ? "stale" : "fresh";
 }
 
+/** Orders roster rows for display: project first (so a shared-tree reader
+ *  sees each repo's sessions together; rows with no project sort last),
+ *  then by heartbeat, most recently seen first, so the recoverable rows
+ *  lead and the long-dead trail at the bottom. Pure ordering - it never
+ *  drops rows; the stale display cap is splitChatRoster's job. */
+export function sortChatRoster(rows: ChatSessionRow[]): ChatSessionRow[] {
+  return [...rows].sort((a, b) => {
+    const projectA = a.project ?? "\uffff";
+    const projectB = b.project ?? "\uffff";
+    if (projectA !== projectB) return projectA.localeCompare(projectB);
+    return Date.parse(b.last_seen) - Date.parse(a.last_seen);
+  });
+}
+
 /** Splits the roster for the two-section display: Active (wake-able or
  *  reachable - fresh opencode rows and every MCP row, which read mail at
  *  their next prompt) and Stale (opencode rows whose harness has stopped
- *  reporting; mail to them waits until they resume). */
-export function splitChatRoster(rows: ChatSessionRow[], now = Date.now()): { active: ChatSessionRow[]; stale: ChatSessionRow[] } {
+ *  reporting; mail to them waits until they resume).
+ *  staleCapMs bounds how old a stale row the roster displays, so
+ *  long-dead sessions cannot bury the fresh signal; hidden rows come
+ *  back only as the staleHidden count, so the CLI can say what it left
+ *  out. null (the default) shows every stale row - the tool surface has
+ *  no cap, only the CLI applies one. */
+export function splitChatRoster(rows: ChatSessionRow[], now = Date.now(), staleCapMs: number | null = null): { active: ChatSessionRow[]; stale: ChatSessionRow[]; staleHidden: number } {
   const active: ChatSessionRow[] = [];
   const stale: ChatSessionRow[] = [];
+  let staleHidden = 0;
   for (const row of rows) {
-    (chatLiveness(row, now) === "stale" ? stale : active).push(row);
+    if (chatLiveness(row, now) === "stale") {
+      if (staleCapMs !== null && now - Date.parse(row.last_seen) > staleCapMs) {
+        staleHidden++;
+      } else {
+        stale.push(row);
+      }
+    } else {
+      active.push(row);
+    }
   }
-  return { active, stale };
+  return { active, stale, staleHidden };
 }
 
 /**

package/src/commands.ts

@@ -1,12 +1,35 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import {
+  defragCore,
+  extractionCore,
+  hygieneCore,
+  mcpToolName,
+  opencodeToolName,
+  reflectCore,
+  type ToolNamer,
+} from "./prompts";
 
 /**
- * Thatch's wrap-up slash commands for opencode, shipped as command markdown
- * files synced into the global opencode config dir (~/.config/opencode/command/
- * thatch/). The plugin writes them on every load so template updates self-heal
- * without a reinstall. Config is loaded before plugins during server startup,
- * so a first-ever install becomes visible on the next start.
+ * Thatch's slash commands, shipped as command markdown files synced into each
+ * host's command directory:
+ *
+ * - opencode: ~/.config/opencode/command/thatch/ - synced by the plugin on
+ *   every load, so template updates self-heal without a reinstall. Config is
+ *   loaded before plugins during server startup, so a first-ever install
+ *   becomes visible on the next start.
+ * - Claude Code: ~/.claude/commands/thatch/ (or the project's .claude/
+ *   commands/thatch/) - synced by `thatch setup --claude`, which has no
+ *   plugin to do it on load.
+ *
+ * Two command families live here:
+ *
+ * - Actions (/thatch/defrag, extract, hygiene, reflect): user-invoked
+ *   wrappers around a behavior that the nudges otherwise only run on their
+ *   own schedule. Each action body is a prompt core from src/prompts.ts, so
+ *   nudge and command wording cannot drift.
+ * - Wrap-ups (/thatch/compact, exit): greenlight-token commands that need
+ *   the opencode plugin's TUI control routes, so they are opencode-only.
  */
 
 /** Greenlight token ending /thatch/compact's assistant response when compaction is safe. */
@@ -32,6 +55,71 @@ $ARGUMENTS
 
 (That section carries the text typed after the command. When it is empty, treat the user message as n/a - the command was run bare.)`;
 
+/**
+ * One on-demand action: the command name (minus the thatch/ prefix), the
+ * description shown in the command menu, and the instruction body (a prompt
+ * core). opencodeOnly marks actions that need a session identity or other
+ * plugin-only capability; those are excluded from Claude Code command files
+ * and MCP prompts.
+ */
+export interface ActionDef {
+  name: string;
+  description: string;
+  body: string;
+  opencodeOnly?: boolean;
+}
+
+/**
+ * The on-demand action set, shared by every host that renders actions. The
+ * bodies come from prompt cores so a wording change lands in the nudge and
+ * the command at once. `tool` renders tool names in the host's spelling.
+ */
+export function actionDefs(tool: ToolNamer): ActionDef[] {
+  return [
+    {
+      name: "defrag",
+      description: "Consolidate duplicate and near-duplicate memories in the store",
+      body: defragCore(tool),
+    },
+    {
+      name: "extract",
+      description: "Drain the extraction queue now",
+      // Needs the invoking session's ID (via get_session_info, opencode-only)
+      // and the plugin's extraction payload provider.
+      opencodeOnly: true,
+      body: `First call thatch_get_session_info to learn this session's ID. Below, replace SESSION_ID with that value.
+
+Dispatch a task with background: true and subagent_type: "general" (required for thatch tool access) with this prompt:
+
+"${extractionCore("thatch_get_extraction_payload", "thatch_extraction_done", ' with session_id \\"SESSION_ID\\"')}"
+
+After dispatching, call thatch_extraction_done to acknowledge.`,
+    },
+    {
+      name: "hygiene",
+      description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
+      body: hygieneCore(),
+    },
+    {
+      name: "reflect",
+      description: "Persist what this session learned as memories",
+      body: reflectCore(tool),
+    },
+  ];
+}
+
+/** Renders one action as a full command markdown file. */
+export function renderActionCommand(action: ActionDef): string {
+  return `---
+description: ${action.description}
+---
+${userMessageSection}
+
+# ${action.name.charAt(0).toUpperCase() + action.name.slice(1)}
+
+${action.body}`;
+}
+
 const COMPACT_TEMPLATE = `---
 description: Flush thatch persistence, check for loose ends, then compact if clear
 ---
@@ -67,29 +155,40 @@ ${EXIT_READY_TOKEN}
 
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. opencode will only exit when the token is present.`;
 
-/** One wrap-up command: the command name (minus the thatch/ prefix) and its full markdown file content. */
+/** One command: the command name (minus the thatch/ prefix) and its full markdown file content. */
 export interface CommandDef {
   name: string;
   content: string;
 }
 
-/** The wrap-up command set, as full command-file contents ready to write. */
+/** The opencode command set: wrap-ups plus every action, as full file contents. */
 export function opencodeCommandDefs(): CommandDef[] {
   return [
     { name: "compact", content: COMPACT_TEMPLATE },
     { name: "exit", content: EXIT_TEMPLATE },
+    ...actionDefs(opencodeToolName).map((a) => ({ name: a.name, content: renderActionCommand(a) })),
   ];
 }
 
 /**
- * Sync the wrap-up commands into <configHome>/opencode/command/thatch/.
- * Idempotent: each file is written only when its on-disk content differs.
- * Returns the paths that were written (empty when everything was current).
+ * The Claude Code command set: the actions minus the opencode-only ones.
+ * The wrap-up commands are excluded too - their greenlight check needs the
+ * plugin's command.execute.before arming and TUI control routes.
  */
-export function installOpencodeCommands(configHome: string): string[] {
-  const dir = join(configHome, "opencode", "command", "thatch");
+export function claudeCommandDefs(): CommandDef[] {
+  return actionDefs(mcpToolName)
+    .filter((a) => !a.opencodeOnly)
+    .map((a) => ({ name: a.name, content: renderActionCommand(a) }));
+}
+
+/**
+ * Sync command files into dir. Idempotent: each file is written only when
+ * its on-disk content differs. Returns the paths that were written (empty
+ * when everything was current).
+ */
+function syncCommandFiles(dir: string, defs: CommandDef[]): string[] {
   const written: string[] = [];
-  for (const def of opencodeCommandDefs()) {
+  for (const def of defs) {
     const path = join(dir, `${def.name}.md`);
     let current: string | null = null;
     try {
@@ -105,3 +204,13 @@ export function installOpencodeCommands(configHome: string): string[] {
   }
   return written;
 }
+
+/** Sync opencode's commands into <configHome>/opencode/command/thatch/. */
+export function installOpencodeCommands(configHome: string): string[] {
+  return syncCommandFiles(join(configHome, "opencode", "command", "thatch"), opencodeCommandDefs());
+}
+
+/** Sync Claude Code's commands into <claudeDir>/commands/thatch/ (claudeDir is ~/.claude or <project>/.claude). */
+export function installClaudeCommands(claudeDir: string): string[] {
+  return syncCommandFiles(join(claudeDir, "commands", "thatch"), claudeCommandDefs());
+}

package/src/db.ts

@@ -1,4 +1,6 @@
 import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { blobToVector, cosineSimilarity } from "./vector-math";
 import {
   PredictionEngine,
@@ -58,6 +60,13 @@ export class ThatchDB {
   #chat: ChatStore;
 
   constructor(path: string) {
+    // bun:sqlite creates the file but not its parent directory. On a fresh
+    // machine the default path (~/.config/thatch/thatch.db) has no dir yet, so
+    // create it here - otherwise every command fails with SQLITE_CANTOPEN.
+    // `:memory:` and other special paths have no meaningful parent to create.
+    if (path !== ":memory:" && !path.startsWith("file:")) {
+      mkdirSync(dirname(path), { recursive: true });
+    }
     this.#db = new Database(path, { create: true });
     this.#db.run("PRAGMA journal_mode = WAL");
     this.#db.run("PRAGMA busy_timeout = 5000");

package/src/embeddings.ts

@@ -1,9 +1,48 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 // BGE-small-en-v1.5 requires a query prefix for asymmetric search.
 // Passage (memory content) gets no prefix - the model was trained
 // to encode passages without instruction.
 const QUERY_PREFIX =
   "Represent this sentence for searching relevant passages: ";
 
+/**
+ * Writable directory for the downloaded model files.
+ *
+ * transformers.js defaults its filesystem cache to a `.cache` folder *inside*
+ * its own package directory (`node_modules/@huggingface/transformers/.cache`).
+ * That breaks any read-only install - a global `bun install -g`, and Nix store
+ * paths in particular - and gets wiped on every reinstall. Anchor the cache in
+ * the platform's per-user cache location instead so it survives upgrades and
+ * works from an immutable store path.
+ *
+ *   THATCH_MODEL_CACHE  explicit override (highest priority)
+ *   XDG_CACHE_HOME      explicit base dir -> $XDG_CACHE_HOME/thatch/models
+ *   macOS              ~/Library/Caches/thatch/models
+ *   Windows            %LOCALAPPDATA%\thatch\models
+ *   Linux / other      ~/.cache/thatch/models
+ *
+ * `platform` and `home` are injectable for testing; they default to the real
+ * runtime values.
+ */
+export function modelCacheDir(
+  platform: NodeJS.Platform = process.platform,
+  home: string = homedir(),
+): string {
+  const env = process.env;
+  if (env.THATCH_MODEL_CACHE) return env.THATCH_MODEL_CACHE;
+  // Respect an explicit XDG override on any platform (some macOS users set it).
+  if (env.XDG_CACHE_HOME) return join(env.XDG_CACHE_HOME, "thatch", "models");
+  const base =
+    platform === "darwin"
+      ? join(home, "Library", "Caches")
+      : platform === "win32"
+        ? (env.LOCALAPPDATA ?? join(home, "AppData", "Local"))
+        : join(home, ".cache");
+  return join(base, "thatch", "models");
+}
+
 /**
  * Interface for an embedding model so tests can supply a mock.
  * `name` is the tag stored alongside each entry so a future reader can tell
@@ -90,7 +129,9 @@ export function resetBackendForTests(): void {
 
 const defaultPipelineFactory: PipelineFactory = async (modelName) => {
   const mode = await configureBackend();
-  const { pipeline } = await import("@huggingface/transformers");
+  const { pipeline, env } = await import("@huggingface/transformers");
+  // Redirect the model cache out of the (possibly read-only) package tree.
+  env.cacheDir = modelCacheDir();
   if (mode === "native") {
     return pipeline("feature-extraction", modelName);
   }