@jeffober/thatch 0.1.43 → 0.1.45

package/README.md

@@ -51,6 +51,54 @@ thatch setup --claude --global  # or --cursor --global
 Restart your editor and thatch's tools are available as `mcp__thatch__*`.
 Requires [Bun] on PATH.
 
+The embedding model downloads once at first use. It is 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` (default `~/.cache/thatch/models`) elsewhere.
+Set `THATCH_MODEL_CACHE` to override the location. The cache survives
+upgrades and works from read-only installs.
+
+### NixOS / Nix
+
+This repo is a flake. Bun and the native embedding runtime are bundled, so no
+global `npm install` or `bun` on PATH is required.
+
+Try it without installing:
+
+```bash
+nix run github:sysread/thatch -- --version
+```
+
+Install system-wide via the NixOS module (in your flake `configuration.nix`):
+
+```nix
+{
+  inputs.thatch.url = "github:sysread/thatch";
+
+  # in your NixOS system's modules:
+  imports = [ inputs.thatch.nixosModules.default ];
+  programs.thatch.enable = true;   # puts `thatch` on PATH for every user
+}
+```
+
+Or add the package yourself with the overlay
+(`nixpkgs.overlays = [ inputs.thatch.overlays.default ];` then
+`environment.systemPackages = [ pkgs.thatch ];`), or drop
+`inputs.thatch.packages.${system}.default` into a `home.packages` /
+`environment.systemPackages` list directly.
+
+Once `thatch` is on PATH, wire it into your editor as usual:
+
+```bash
+cd /path/to/your/project
+thatch setup --claude --global   # or --cursor
+```
+
+The embedding model still downloads once at first use and is cached in the
+platform's per-user cache dir (the per-platform paths above; override with
+`THATCH_MODEL_CACHE`), so it survives upgrades and works from the read-only
+Nix store.
+
 ### Other MCP-compatible harnesses
 
 ```json
@@ -99,20 +147,26 @@ Thatch gives your agent:
   (opencode, Claude Code, and Cursor; same machine). opencode sessions
   join the directory automatically under an assigned, never-reused name
   (a slug of the session title plus a counter); others see the roster, and
-  messages land in inboxes -- opencode sessions get woken with a prompt
-  when idle, other hosts see pending mail at their next prompt. Loop-safe:
+  messages land in inboxes -- idle opencode sessions get woken with a
+  prompt, and Cursor and Claude Code wake when a turn ends with unread
+  mail (Cursor also at prompt time; Claude Code also at startup and
+  resume). Loop-safe:
   messages are informational to the receiving agent, and wake prompts are
   rate-capped. Delivered messages are framed as untrusted content so a
   hostile message cannot impersonate your instructions. Disable the whole
   feature with `chat.enabled: false` in the thatch config (or just the
   auto-joining with `chat.autoRegister: false`).
-- **Wrap-up commands** (opencode only) -- `/thatch/compact` and `/thatch/exit`
-  run a pre-flight checklist before a compaction or an exit: the agent flushes
-  pending fact extraction, finishes promised memory writes, and surfaces
-  todos or follow-ups it never addressed. It ends its response with a
-  greenlight token only when the checklist is clean; thatch then triggers the
-  compaction or quits opencode. With items outstanding, the agent lists them
-  and nothing fires -- you decide when to retry.
+- **Slash commands** -- `/thatch/defrag` (consolidate duplicate memories),
+  `/thatch/extract` (drain the extraction queue now), `/thatch/hygiene`
+  (tend stale and orphaned memories), and `/thatch/reflect` (persist what
+  the session learned) run on demand the same behaviors the nudges run on
+  their own schedule. Plus the opencode-only wrap-ups: `/thatch/compact` and
+  `/thatch/exit` run a pre-flight checklist before a compaction or an exit:
+  the agent flushes pending fact extraction, finishes promised memory
+  writes, and surfaces todos or follow-ups it never addressed. It ends its
+  response with a greenlight token only when the checklist is clean; thatch
+  then triggers the compaction or quits opencode. With items outstanding,
+  the agent lists them and nothing fires -- you decide when to retry.
 - **Notifications + user config** -- the agent can ping you out-of-band when a
   long-running outcome lands: a desktop banner, a spoken voice
   announcement, or both (macOS and Linux). Preferences live in a
@@ -129,6 +183,24 @@ See the [user guide](docs/user/README.md) for the full tool list, CLI
 commands, configuration, environment variables, and detailed setup for each
 host.
 
+## What works in Claude Code
+
+The memory tools, prediction and behavior engines, conversation search via
+the `thatch session` CLI, cross-session chat (with stop-hook wake), skills,
+and the on-demand actions `/thatch/defrag`, `/thatch/hygiene`, and
+`/thatch/reflect` (synced by `thatch setup --claude`). Not available: the
+wrap-up commands and `/thatch/extract` (they need the opencode plugin's
+session identity and TUI control routes), live recall/prediction nudges
+beyond the hook-based flow, and toast notifications.
+
+## What works in Cursor
+
+The same core set as Claude Code (memory, predictions, behaviors, chat with
+stop-hook wake, skills, and the `defrag`/`hygiene`/`reflect` actions). Cursor
+has no file-based slash commands, so the actions surface through MCP prompts
+instead. Not available: the wrap-up commands, `/thatch/extract`, and toast
+notifications.
+
 ## Privacy
 
 Everything is local. The embedding model downloads once from Hugging Face Hub
@@ -150,6 +222,9 @@ bun install
 mise run check     # typecheck + bun test + markdownlint (the CI gate)
 ```
 
+On Nix, `nix develop` drops you into a shell with bun, mise, and node already
+on PATH -- no system install needed.
+
 Tests never reach outside the sandbox: temp-directory SQLite files, mock
 embeddings, no network.