@jeffober/thatch 0.1.40 → 0.1.42

package/docs/user/setup.md

@@ -48,13 +48,24 @@ Thatch runs as an MCP server. The setup command installs the server
 config, instructions, hooks, and skills:
 
 ```bash
-thatch setup --claude            # project-local (writes .mcp.json, CLAUDE.md, .claude/)
+thatch setup --claude            # project-local (.mcp.json, CLAUDE.md, .claude/)
 thatch setup --claude --global   # user-scoped (~/.claude/)
 ```
 
+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/`).
+
 `bun` must be on PATH (the thatch binary runs under bun). Setup is
 idempotent. Re-running it updates drifted content without clobbering
-unrelated config.
+unrelated config, and reports what it did: the skills directory plus
+how many skills were added, updated (replaced with a newer version),
+removed (retired), or already current.
+
+If thatch skills exist in the scope you did not install to (for
+example, `~/.claude/skills/` copies left over from before a repo moved
+to project-local skills), setup prints a note naming that directory.
+It never touches the other scope.
 
 For a global install, setup prints the `claude mcp add --scope user`
 command to run instead of writing a project `.mcp.json`.
@@ -66,6 +77,9 @@ thatch setup --cursor            # project-local (.cursor/mcp.json, AGENTS.md, .
 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/`.
+
 Cursor uses a flat hooks format (`{version, hooks:{event:[{command}]}}`)
 and `--json` output for hook commands.
 

package/docs/user/skills.md

@@ -7,11 +7,12 @@ frontmatter (name, description) that opencode auto-discovers.
 
 ## How they work
 
-On startup, thatch installs skill files into your global config
-(`~/.config/opencode/skills/` for opencode, `~/.claude/skills/` for
-Claude Code, `~/.cursor/skills/` for Cursor). The host's skill
-discovery scans these directories and presents them to the agent as
-available skills.
+On startup, thatch installs skill files into the host's skills
+directory: the repo's `.claude/skills/` or `.cursor/skills/` for
+project-local `thatch setup`, `~/.claude/skills/` or `~/.cursor/skills/`
+for `--global`, and `~/.config/opencode/skills/` for the opencode
+plugin. The host's skill discovery scans these directories and
+presents them to the agent as available skills.
 
 The agent loads a skill when the user's request matches the skill's
 description, or when another skill or the system prompt directs the
@@ -45,7 +46,7 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar. |
-| `thatch-review-mentorship` | Peer-mentorship lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, never blocking. |
+| `thatch-review-technique` | Technique lens: teaching-grade notes on unseen helpers/internal packages, companion techniques, house patterns, test-craft, API-shape principles, next-reader discoverability. Informational only, never blocking. |
 | `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a deduplicated, severity-grouped report. |
 | `thatch-review-context` | Gathers project context (PRs, tickets, linked docs/designs followed from the change, TODOs, deferred work) before a review. Prevents false positives about intentionally deferred work. |
 | `thatch-code-archaeology` | Investigates an existing feature, debugs an unfamiliar area, or begins a new ticket. The research skill; pair with `thatch-coding-workflow`. |

package/docs/user/watchers.md

@@ -1,10 +1,11 @@
 # Watchers
 
-Watchers monitor external sources - today, GitHub pull requests and
-branches - and inject a notification into the conversation when
-something happens. You ask the agent to watch a PR or a branch; thatch
-polls it in the background; the agent gets woken up when a watched
-event occurs. No one has to keep asking "any updates yet?"
+Watchers monitor external sources - today, GitHub pull requests,
+branches, and local shell commands - and inject a notification into
+the conversation when something happens. You ask the agent to watch a
+PR, a branch, or a command; thatch polls it in the background; the
+agent gets woken up when a watched event occurs. No one has to keep
+asking "any updates yet?"
 
 ## What it does
 
@@ -34,18 +35,47 @@ Branch watched events:
   on the branch, optionally filtered by workflow name (substring,
   case-insensitive)
 
+Command watched events:
+
+- `command_success` - the watched command exited 0. The agent calls
+  `thatch_watch_command_create` with a shell command that works as a
+  **condition variable, not a data pipe**: the watcher re-runs it every
+  poll and reads only the exit code - the command's output is
+  discarded, never delivered. A command watch is one-shot by design:
+  the first exit 0 fires one notification, then the watcher cancels
+  itself. The command must be a fast, idempotent status check (a
+  marker-file test, a health endpoint curl, a `gh run list` query).
+  Blocking waits like `gh run watch` or `tail -f` are not refused -
+  the tool guidance tells the agent not to use them, and a blocking
+  command is killed at the per-run timeout each cycle and
+  treated as not-done-yet. The command runs once at registration as
+  validation: a command that already exits 0 is refused (the condition
+  is already met), as is a command-not-found.
+
 Notifications are delivered as synthetic parts: the model sees them,
 the transcript does not. A notification triggers a model turn, so the
 agent can act on the event even while you are away.
 
 ## Privacy model
 
-Notifications carry pointer data only: who commented, what happened,
-and a URL. Comment bodies, diff contents, and CI logs never enter the
-context from the notification itself. This is deliberate - GitHub
-comments are written by strangers, and untrusted text flowing into a
-model's context is a prompt-injection vector. The agent fetches details
-on demand with `gh` when it decides to act.
+Notifications carry pointer data and machine status: who acted, what
+happened, a URL, and - for CI - the check or workflow name with its
+conclusion (success, failure). Comment bodies, diff contents, and CI
+logs never enter the context from the notification itself. This is
+deliberate - GitHub comments are written by strangers, and untrusted
+text flowing into a model's context is a prompt-injection vector.
+Machine status fields come from the GitHub API rather than
+user-written text, so they are safe to deliver. The agent fetches
+everything else on demand with `gh` when it decides to act.
+
+Command watches follow the same rule with a stricter boundary: the
+notification carries the exit code and duration only. The command's
+stdout and stderr are discarded - command output can be external
+content (a curl response, a build log), so it never rides a
+notification. The agent re-runs the command or reads logs itself when
+it acts. The command runs in the project directory as the local user;
+each run is killed at a 30-second timeout
+(`THATCH_WATCH_COMMAND_TIMEOUT_SECONDS` overrides it).
 
 ## How to use it
 
@@ -56,13 +86,21 @@ Ask for it in conversation:
 
 The handling policy lives in your instruction. State it when you ask -
 the notification turn reads your policy from the conversation and
-follows it. The notification says what happened and where, not what to
-do about it.
+follows it. The notification says what happened and where, not what
+to do about it.
+
+For waiting on CI, pick the tool that fits the wait. A short bounded
+wait (a couple of minutes) can simply be polled in the conversation.
+Watchers are the better fit for longer or open-ended waits, and for
+post-merge builds on main; the creation output states when the first
+poll lands so the choice compares real numbers.
 
 Other tools:
 
 - `thatch_watch_branch_create` - watch a branch (typically main) for
   commits, CI check runs, and workflow runs
+- `thatch_watch_command_create` - wait on any local condition via a
+  shell command that exits 0 when the wait is over
 - `thatch_watch_list` - shows the session's active watchers
 - `thatch_watch_cancel` - cancels one by id
 
@@ -72,7 +110,13 @@ Watchers are in-memory and process-scoped:
 
 - Ending the opencode process (or restarting it) drops all watchers.
 - A watcher expires after 8 hours by default.
-- Each session can hold up to 5 active watchers.
+- Each session can hold up to 5 active watchers (all sources share
+  the budget).
+- A one-shot watch cancels itself after its first event - a single
+  "tell me when this run finishes" request leaves nothing polling
+  afterwards. Standing watches (the default) keep going until they
+  are cancelled, expire, or the process ends. Command watches are
+  always one-shot.
 
 If opencode restarts while a watch is active, re-register it - the
 session's conversation survives, so the policy you stated is still
@@ -83,8 +127,9 @@ there.
 - **opencode only.** MCP hosts (Claude Code, Cursor) have no way for a
   plugin to start a conversation turn, so the watch tools are not
   available there.
-- **Requires the `gh` CLI** to be installed and authenticated. Watch
-  creation reports a clear error if it is not.
+- **Requires the `gh` CLI** to be installed and authenticated for PR
+  and branch watches. Watch creation reports a clear error if it is
+  not. Command watches need only `bash`, not `gh`.
 - **Polling, not webhooks.** Events appear on the next poll cycle
   (60 seconds by default), not instantly.
 - **No delivery during an active turn.** If the agent is mid-turn when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "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",
@@ -29,6 +29,7 @@
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.13",
+    "@opencode-ai/sdk": "1.17.13",
     "@types/bun": "^1.3.14",
     "markdownlint-cli2": "^0.23.0",
     "typescript": "^5.7.0",

package/src/chat-names.ts

@@ -0,0 +1,120 @@
+/**
+ * Static display-name pool for the cross-session chat directory.
+ *
+ * Style lifted from fnord's Nomenclater (lib/ai/agent/nomenclater.ex): whimsical
+ * geek-culture names in three shapes - "first last", "first the epithet",
+ * "first of the phrase" - spread across themes (Jargon File/BOFH, Zork,
+ * Klingons, Discworld, Sandman, D&D, pulp detectives with software puns,
+ * hackerspeak callsigns, AI puns, golden-age sci-fi, spoofed famous robots,
+ * unnamed-cast extras). fnord generates its names with an LLM at runtime;
+ * thatch bakes the pool in - static contents, no model call.
+ *
+ * The pool is the fallback base for registrations with no usable session
+ * title (ChatStore.register slugifies a random pool name). Pool names are
+ * case-insensitively distinct from each other; slugify is lossy, but a
+ * shared base is harmless - the per-base counter still yields unique
+ * names.
+ *
+ * Names are deliberately short: they appear inside wake prompts and
+ * chat_list output, so every character costs context.
+ */
+
+export const CHAT_NAME_POOL: readonly string[] = [
+  // Jargon File / BOFH
+  "Buck the Bogon Filter",
+  "Phineas the Packet Wrangler",
+  "Octavia of the Lost Backups",
+  "Grumble the Tape Librarian",
+  "Wilhelmina the Password Oracle",
+  "Ned of the Null Modem",
+  "Sydney the Segfault Sage",
+  "Barnaby of the Baud Rate",
+  // Zork
+  "Dimwit the Flathead",
+  "Belboz the Enchanter",
+  "Ellum the Grue Keeper",
+  "Umbra the Grue Baiter",
+  "Piotr of the Platinum Bar",
+  "Zizmo of the Dim Cellar",
+  // Klingons, with dramatic epithets
+  "K'Vir the Unmerged",
+  "Morath the Rebase Survivor",
+  "K'Leth of the Cold Staging",
+  "Duras the Conflict Eater",
+  "B'Etor the Force Pusher",
+  "Gowron of the Green Build",
+  "Kurn the Typechecker",
+  "Martok the Ever Rebased",
+  // Discworld, especially Unseen University faculty
+  "Wenlock the Reader in Recent Runes",
+  "Modo the Compost King",
+  "Victor of Applied Catastrophe",
+  "Dorcas of Indefinite Studies",
+  "Adereth the Invisible Scholar",
+  "Spold the Unseen Porter",
+  "Herrno of the Eighth Level",
+  "Vimes the Deadline Copper",
+  // The Dreaming
+  "Mervyn of the Pumpkin Patch",
+  "Lucien the Dream Librarian",
+  "Abel the Ever Patient",
+  "Shaper of the Facade",
+  "Nada the Restless Wanderer",
+  "Brute the Dream Farrier",
+  // D&D
+  "Therenal Quickblade",
+  "Osgar the Mimic Checker",
+  "Yvaine of the Silver Cache",
+  "Dorn Halfstack",
+  "Elowen Moonpath",
+  "Garrick the Lint Warden",
+  "Sylvara of the Deep Trace",
+  "Haldor Truehex",
+  // Pulp detectives with software names
+  "Dashiell the Deadlocker",
+  "Marlowe the Cherry Picker",
+  "Effie the Ticket Trier",
+  "Brigid the Stale Falcon",
+  "Deb the Debugger Malloy",
+  "Spade the Unallocated",
+  // Hackerspeak callsigns
+  "Crash Override",
+  "Kernel Panic",
+  "Null Terminator",
+  "Cache Money",
+  "Segfault Sammy",
+  "Wardialer Wendy",
+  "Grep Goblin",
+  "Backtrace Betty",
+  // AI puns
+  "Al Go Rithm",
+  "Anna Log",
+  "Otto Mated",
+  "Percy the Perceptron",
+  "Terrence of the Last Epoch",
+  "Emma Bedding",
+  "Quinn Latent",
+  "Dot Matrix",
+  // Golden-age sci-fi
+  "Buzz Megabyte",
+  "Rex Protocol",
+  "Chip Vortexian",
+  "Wanda Warpdrive",
+  "Pete Parallax",
+  "Vera Antimatter",
+  // Spoofed famous AIs and robots
+  "Lrrr of Omicron Persei 8",
+  "Data of the Positronic Brain",
+  "Bishop the Synthetic",
+  "Hal of the Pod Bay",
+  "Rosie Unit One",
+  "Robot Devil",
+  // Unnamed cast
+  "Labcoat 3",
+  "Redshirt 7",
+  "NPC 4",
+  "Villager 2",
+  "Guard 5",
+  "Henchperson 12",
+  "Extra 11",
+];