@jeffober/thatch 0.2.3 → 0.2.4

package/bin/thatch

@@ -8,7 +8,7 @@ import { detectRepo } from "../src/git";
 import { BgeEmbeddingModel } from "../src/embeddings";
 import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
-import { setupClaudeCode, setupCursor, registerClaudeMcpServer } from "../src/setup";
+import { setupClaudeCode, setupCursor, setupSkillsOnly, registerClaudeMcpServer } from "../src/setup";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
 import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailJsonl, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, CHAT_STALE_MS, CHAT_RENUDGE_MINUTES, chatLiveness, humanAge, splitChatRoster, sortChatRoster, mcpSessionID, isoMinutesAgo, renderChatParticipant, resolveRegisteredPredecessor, type ChatSessionRow, type ChatTailFilter } from "../src/chat";
 import { chatEnabled, loadConfig } from "../src/config";
@@ -38,8 +38,10 @@ function usage(): never {
   thatch flush-tools [--json]      Peek the queue + print an extraction nudge (hook only)
   thatch chat-notify               Print a chat follow-up message when mail is unread (Cursor stop hook)
   thatch flush-predictions [--json] Query predictions for the prompt (hook only)
-  thatch setup --claude [--cursor] [--local|--global]
-                                   Install config + instructions + hooks + skills
+  thatch setup --claude [--cursor] [--local|--global] [--skills-only]
+                                   Install config + instructions + hooks + skills.
+                                   --skills-only refreshes just the skill files
+                                   (skips MCP config, instructions, hooks, commands)
   thatch session list -s <id> [--after T] [--before T]
                                    JSONL timeline of a session's parts (one line per part)
   thatch session get --id <part_id|msg_id>
@@ -839,6 +841,10 @@ switch (command) {
     const isLocal = args.includes("--local");
     const isClaude = args.includes("--claude");
     const isCursor = args.includes("--cursor");
+    // --skills-only narrows the run to the skill install: same host and
+    // scope rules, but MCP config, instructions, hooks, and commands are
+    // left untouched.
+    const skillsOnly = args.includes("--skills-only");
 
     if (isGlobal && isLocal) {
       console.error("Choose one scope: --local or --global.");
@@ -875,52 +881,73 @@ switch (command) {
     };
 
     if (isClaude) {
-      const result = setupClaudeCode(thatchBin, isGlobal, dir);
+      if (skillsOnly) {
+        const result = setupSkillsOnly("claude", isGlobal, dir);
 
-      console.log(`Thatch setup complete for Claude Code (${isGlobal ? "global" : "project-local"}).`);
-      console.log();
-      if (result.mcpConfig) {
-        console.log(`  MCP config:    ${result.mcpConfig}`);
-      }
-      console.log(`  Instructions:  ${result.claudeMd}`);
-      console.log(`  Hooks:         ${result.settings}`);
-      printSkills(result);
-      if (result.commands.length > 0) {
-        console.log(`  Commands:      ${result.commands.length} written (${result.commands.map((p) => p.split("/").pop()).join(", ")})`);
-      }
-      console.log();
-      if (result.mcpAddCommand) {
-        // Global setup cannot write ~/.claude.json directly, so run the
-        // registration on the user's behalf. Idempotent: an existing
-        // registration is left alone; a missing or failing claude CLI
-        // falls back to printing the manual command.
-        const reg = await registerClaudeMcpServer(thatchBin);
-        if (reg.status === "registered") {
-          console.log(`  MCP server:    ${reg.detail}`);
-        } else if (reg.status === "already-registered") {
-          console.log(`  MCP server:    already registered (claude mcp get thatch to inspect)`);
-        } else {
-          console.log("To register the MCP server globally, run:");
-          console.log(`  ${result.mcpAddCommand}`);
-          console.log(`  (${reg.detail})`);
+        console.log(`Thatch skills updated for Claude Code (${isGlobal ? "global" : "project-local"}).`);
+        console.log();
+        printSkills(result);
+        console.log();
+        console.log("Restart Claude Code for the changes to take effect.");
+      } else {
+        const result = setupClaudeCode(thatchBin, isGlobal, dir);
+
+        console.log(`Thatch setup complete for Claude Code (${isGlobal ? "global" : "project-local"}).`);
+        console.log();
+        if (result.mcpConfig) {
+          console.log(`  MCP config:    ${result.mcpConfig}`);
+        }
+        console.log(`  Instructions:  ${result.claudeMd}`);
+        console.log(`  Hooks:         ${result.settings}`);
+        printSkills(result);
+        if (result.commands.length > 0) {
+          console.log(`  Commands:      ${result.commands.length} written (${result.commands.map((p) => p.split("/").pop()).join(", ")})`);
         }
         console.log();
+        if (result.mcpAddCommand) {
+          // Global setup cannot write ~/.claude.json directly, so run the
+          // registration on the user's behalf. Idempotent: an existing
+          // registration is left alone; a missing or failing claude CLI
+          // falls back to printing the manual command.
+          const reg = await registerClaudeMcpServer(thatchBin);
+          if (reg.status === "registered") {
+            console.log(`  MCP server:    ${reg.detail}`);
+          } else if (reg.status === "already-registered") {
+            console.log(`  MCP server:    already registered (claude mcp get thatch to inspect)`);
+          } else {
+            console.log("To register the MCP server globally, run:");
+            console.log(`  ${result.mcpAddCommand}`);
+            console.log(`  (${reg.detail})`);
+          }
+          console.log();
+        }
+        console.log("Restart Claude Code for the changes to take effect.");
       }
-      console.log("Restart Claude Code for the changes to take effect.");
     }
 
     if (isCursor) {
-      const result = setupCursor(thatchBin, isGlobal, dir);
+      if (skillsOnly) {
+        const result = setupSkillsOnly("cursor", isGlobal, dir);
 
-      console.log();
-      console.log(`Thatch setup complete for Cursor (${isGlobal ? "global" : "project-local"}).`);
-      console.log();
-      console.log(`  MCP config:    ${result.mcpConfig}`);
-      console.log(`  Instructions:  ${result.agentsMd}`);
-      console.log(`  Hooks:         ${result.hooks}`);
-      printSkills(result);
-      console.log();
-      console.log("Restart Cursor for the changes to take effect.");
+        console.log();
+        console.log(`Thatch skills updated for Cursor (${isGlobal ? "global" : "project-local"}).`);
+        console.log();
+        printSkills(result);
+        console.log();
+        console.log("Restart Cursor for the changes to take effect.");
+      } else {
+        const result = setupCursor(thatchBin, isGlobal, dir);
+
+        console.log();
+        console.log(`Thatch setup complete for Cursor (${isGlobal ? "global" : "project-local"}).`);
+        console.log();
+        console.log(`  MCP config:    ${result.mcpConfig}`);
+        console.log(`  Instructions:  ${result.agentsMd}`);
+        console.log(`  Hooks:         ${result.hooks}`);
+        printSkills(result);
+        console.log();
+        console.log("Restart Cursor for the changes to take effect.");
+      }
     }
     break;
   }

package/docs/dev/features/setup.md

@@ -18,6 +18,8 @@ resolution fit together.
   hooks, and skills for Cursor
 - `--global` flag --- installs to user-scoped config dirs instead of
   project-local
+- `--skills-only` flag --- refreshes just the skill files (same host and
+  scope rules), skipping MCP config, instructions, hooks, and commands
 - **Marker system** --- idempotent replacement of the thatch instruction block
   in `CLAUDE.md` or `AGENTS.md` via start/end markers
 - **`checkSetup`** --- detects installed, not-installed, or markers-broken at
@@ -35,6 +37,11 @@ resolution fit together.
 
 At least one of `--claude` or `--cursor` is required. Both can be passed
 together. `--global` applies to whichever host or hosts are selected.
+`--skills-only` narrows the run to the skill install (`setupSkillsOnly`
+in `src/setup.ts`): it reuses the same path resolution and other-scope
+probe as the full setup paths but only calls `installSkills`, so it is
+safe to run in an already-set-up host when only the skill files need
+refreshing.
 
 ### Claude Code setup (`setupClaudeCode` in `src/setup.ts`)
 

package/docs/user/cli.md

@@ -148,7 +148,8 @@ thatch buffer-batch             # append tool batch to queue (Claude Code hook)
 thatch buffer-tool              # append single tool to queue (Cursor hook)
 thatch flush-tools [--json]     # peek queue + print nudges (hook)
 thatch flush-predictions [--json]  # prediction-only nudge (hook)
-thatch setup --claude [--cursor] [--global]  # install config + hooks + skills
+thatch setup --claude [--cursor] [--global]     # install config + hooks + skills
+thatch setup --claude --skills-only             # refresh just the skill files
 ```
 
 ## Environment variables

package/docs/user/setup.md

@@ -60,6 +60,16 @@ Skills follow the install scope: project-local installs them to the
 repo's `.claude/skills/` so they version with the project; `--global`
 installs them to `~/.claude/skills/` (or `$CLAUDE_CONFIG_DIR/skills/`).
 
+To refresh just the skill files without rewriting anything else, add
+`--skills-only`:
+
+```bash
+thatch setup --claude --skills-only
+```
+
+This skips the MCP config, instructions, hooks, and commands, and
+reports the same skills directory and install counts as a full run.
+
 `bun` must be on PATH (the thatch binary runs under bun). Setup is
 idempotent. Re-running it updates drifted content without clobbering
 unrelated config, and reports what it did: the skills directory plus
@@ -84,6 +94,9 @@ thatch setup --cursor --global   # user-scoped (~/.cursor/)
 Skills follow the install scope: project-local installs them to the
 repo's `.cursor/skills/`; `--global` installs them to `~/.cursor/skills/`.
 
+As with Claude Code, `--skills-only` refreshes just the skill files and
+skips the MCP config, instructions, and hooks.
+
 Cursor uses a flat hooks format (`{version, hooks:{event:[{command}]}}`)
 and `--json` output for hook commands.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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/setup.ts

@@ -643,6 +643,56 @@ export function setupCursor(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Skills-only setup - refresh skill files without touching anything else
+// ---------------------------------------------------------------------------
+
+export interface SkillsOnlyResult {
+  /** Skill install report for the directory this run wrote to. */
+  skills: InstallReport;
+  /** Thatch skills in the opposite scope's dir, if any; never written by this run. */
+  otherScopeSkills: OtherScopeSkills | null;
+  global: boolean;
+}
+
+/**
+ * Installs only the skill files, skipping MCP config, instructions, hooks,
+ * and commands. Intended for refreshing skills in an already-set-up host
+ * without rewriting the rest of the configuration. Same scope rules as full
+ * setup: project-local runs write to the repo's host skills dir, global runs
+ * to the host config dir, and the other scope is probed (surfaced in the
+ * report) but never written.
+ */
+export function setupSkillsOnly(
+  host: HostKind,
+  global: boolean,
+  projectDir: string,
+  homeDir?: string,
+): SkillsOnlyResult {
+  const { homedir } = require("node:os");
+  const home = homeDir ?? homedir();
+
+  const skillsDir = host === "claude"
+    ? resolvePaths(global, projectDir, home).skillsDir
+    : resolveCursorPaths(global, projectDir, home).skillsDir;
+
+  // Same other-scope logic as the full setup paths: surface skills this run
+  // did not touch so the CLI can warn about leftovers.
+  const otherDir = host === "claude"
+    ? (global
+      ? join(projectDir, ".claude", "skills")
+      : join(claudeConfigDir(home), "skills"))
+    : (global
+      ? join(projectDir, ".cursor", "skills")
+      : join(cursorConfigDir(home), "skills"));
+
+  return {
+    skills: installSkills(skillsDir),
+    otherScopeSkills: otherScopeInfo(otherDir),
+    global,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Setup detection - check whether setup was completed for the current host
 // ---------------------------------------------------------------------------