@jeffober/thatch 0.1.19 → 0.1.21

package/README.md

@@ -2,24 +2,14 @@
 
 [![CI](https://github.com/sysread/thatch/actions/workflows/ci.yml/badge.svg)](https://github.com/sysread/thatch/actions/workflows/ci.yml)
 
-## Synopsis
+Persistent memory and useful dev skills for AI coding agents. Works with
+**OpenCode** (as a plugin), **Claude Code** (as a local MCP server), and
+**Cursor** (as a local MCP server).
 
-Persistent memory and useful dev skills for AI coding agents that requires zero
-manual config.
-
-Works with **OpenCode** (as a plugin), **Claude Code** (as a local `stdio` MCP
-server), and **Cursor** (as a local `stdio` MCP server).
-
-Each session inherits the accumulated knowledge of every session before it —
-project architecture, conventions, gotchas, user preferences — so your agent
-starts with context instead of a blank slate. Stores are per-repo with a shared
-`global` store.
-
-On top of the memory layer, thatch ships a suite of skills for managing
-memories, performing in-depth, structured code reviews, managing the software
-development life cycle, and researching your code base.
-
-No API keys, no cloud services; everything runs on your machine.
+Each session inherits the accumulated knowledge of every session before it:
+project architecture, conventions, gotchas, user preferences. Your agent
+starts with context instead of a blank slate. No API keys, no cloud services;
+everything runs on your machine.
 
 ## Quick start
 
@@ -30,304 +20,86 @@ No API keys, no cloud services; everything runs on your machine.
 { "plugin": ["@jeffober/thatch"] }
 ```
 
-On next start, OpenCode npm-installs thatch (putting the `thatch` CLI on your
-PATH as a side effect) and its tools are available immediately.
-
-Set this environment variable so the extraction nudge can run the fact-extractor
-as a **background** sub-agent instead of blocking your turn:
+On next start, OpenCode npm-installs thatch and its tools are available
+immediately. For background extraction sub-agents:
 
 ```bash
 export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
 ```
 
-Without it, opencode hides the task tool's `background` parameter and every
-extraction nudge runs synchronously. Put it in your shell rc, `mise.toml`
-`[env]`, or `.envrc`.
-
-**Self-hosting** (local development):
-
-```jsonc
-{ "plugin": ["./path/to/thatch/src/index.ts"] }
-```
-
-Or place the repo under `.opencode/plugins/` and OpenCode auto-loads it.
+Then **prime your project memory** with by running `thatch prime` in your project directory.
+This will launch an `opencode` session to build an initial map of the code base and its architecture to seed the memory.
 
-### Claude Code
+### Claude Code and Cursor
 
-**Install thatch globally:**
+Install globally, then run setup in your project:
 
 ```bash
 npm install -g @jeffober/thatch
-```
-
-This puts the `thatch` binary on your PATH. It requires [Bun] to be installed
-(`curl -fsSL https://bun.sh/install | bash` if you don't have it).
-
-**Set up Claude Code in your project:**
-
-```bash
 cd /path/to/your/project
-thatch setup --claude
-```
-
-`setup` does four things:
-1. Writes `.mcp.json` — registers the MCP server (Claude Code spawns `thatch mcp` as a stdio process)
-2. Appends instructions to `CLAUDE.md` — session startup, when to write, what to store
-3. Installs hooks in `.claude/settings.json` — `SessionStart` runs `thatch reminder` (recall nudge + hygiene), `PostToolBatch` feeds the extraction queue, `UserPromptSubmit` peeks the queue and nudges you to save new knowledge
-4. Installs skill files to `~/.claude/skills/` — memory workflow skills (project primer, fact extractor, dedup classifier, session reflection), code review skills (6 review specialists + synthesizer + context + workflow research), walkthrough skills, and writing skills. See [Skills](#skills) below.
-
-Restart Claude Code and thatch's tools are available as `mcp__thatch__*`.
+thatch setup --claude    # or --cursor
 
-**Global setup** (all projects at once, no per-project config):
-
-```bash
-thatch setup --claude --global
+# set up in your global config for all projects
+thatch setup --claude --global  # or --cursor --global
 ```
 
-This writes to `~/.claude/CLAUDE.md` and `~/.claude/settings.json`, then prints
-the `claude mcp add` command to register the MCP server at user scope.
-
-**Local development** (from a thatch repo checkout):
-
-```bash
-cd /path/to/thatch
-bun run bin/thatch setup --claude
-```
-
-When `thatch` is not on PATH, setup uses the absolute path to `bin/thatch` in
-the hooks and MCP config. When it is on PATH (npm global install), setup uses
-the bare `thatch` command so the config survives updates.
+`setup` installs the MCP server config, hooks, instructions, and skills.
+Restart your editor and thatch's tools are available as `mcp__thatch__*`.
+Requires [Bun] on PATH.
 
 ### Other MCP-compatible harnesses
 
-Thatch works as a `stdio` MCP server with any MCP client. Register it in your
-harness's MCP config by pointing to the `thatch` binary:
-
 ```json
 {
   "mcpServers": {
-    "thatch": {
-      "command": "thatch",
-      "args": ["mcp"]
-    }
+    "thatch": { "command": "thatch", "args": ["mcp"] }
   }
 }
 ```
 
-No `setup` step is needed for bare MCP usage; `setup` installs hooks and
-instructions specific to Claude Code and Cursor. For other harnesses, add the
-MCP server config above and include thatch's tools/instructions in your agent's
-system prompt manually (see [docs/dev/mcp-parity.md](docs/dev/mcp-parity.md)
-for the prompt text). [Bun] must be on PATH.
-
-## Tools
-
-| Tool (opencode) | Tool (MCP) | What it does |
-|------------------|------------|-------------|
-| `thatch_memory_remember` | `mcp__thatch__memory_remember` | Save a memory with an embedding for later recall |
-| `thatch_memory_recall` | `mcp__thatch__memory_recall` | Semantic search across project + global stores |
-| `thatch_memory_list` | `mcp__thatch__memory_list` | List labels and metadata in a store |
-| `thatch_memory_show` | `mcp__thatch__memory_show` | Read full content by exact label |
-| `thatch_memory_forget` | `mcp__thatch__memory_forget` | Delete a memory |
-| `thatch_store_list` | `mcp__thatch__store_list` | List all stores |
-| `thatch_find_duplicates` | `mcp__thatch__find_duplicates` | Surface pairs of suspiciously similar memories |
-| `thatch_dedup_mark_checked` | `mcp__thatch__dedup_mark_checked` | Record a reviewed pair so it stops being re-reported |
-| `thatch_extraction_done` | `mcp__thatch__extraction_done` | Acknowledge extraction nudge was dispatched to a sub-agent; drains the buffer |
-| `thatch_prediction_query` | `mcp__thatch__prediction_query` | Query the user decision model for scored predictions matching a context |
-| `thatch_prediction_update` | `mcp__thatch__prediction_update` | Create, reinforce, or weaken a prediction about user preferences |
-| `thatch_prediction_list` | `mcp__thatch__prediction_list` | List all predictions with matchers, confidence, evidence, and provenance |
-| `thatch_prediction_delete` | `mcp__thatch__prediction_delete` | Delete a prediction created in error (cascades to edges and provenance) |
-
-## Prediction engine
-
-Thatch maintains a statistical model of the user's decision-making preferences.
-When the user sends a prompt, the engine embeds it (sharing the embedding
-already computed for memory recall) and searches for **matchers** — context
-patterns that describe situations where the user has expressed preferences.
-Matching matchers fire linked **predictions** (scored by cosine similarity,
-edge weight, and Bayesian confidence), and a nudge is injected alongside the
-recall nudge:
-
-```text
-[thatch] User decision model
-- [0.72 conf, 4 tests] When X: you tend to Y
-- [0.50 conf, 0 tests] When Z: you may prefer W
-```
-
-The nudge is descriptive, not directive. The system prompt instructions tell
-the agent to follow strong predictions, surface uncertainty when confidence is
-thin, and update the model when the user responds. Predictions use a Bayesian
-posterior with a Beta prior (K=5, P0=0.5); signals are `confirm`,
-`disconfirm`, `soft` (weak disconfirm, weight 0.25), and `create`.
-
-The MCP path (Claude Code, Cursor) fires predictions via the same sideband
-socket used for recall nudges. The `flush-predictions` CLI subcommand provides
-standalone prediction-only output for testing.
-
-## Skills
-
-Thatch ships skills that encode operational methodology — practices your
-agent follows to maintain its own memory and review code systematically.
-
-### Memory workflows
-
-| Skill | What it does |
-|-------|-------------|
-| `thatch-project-primer` | Bootstrap a project's memory store by investigating the codebase and writing foundational memories |
-| `thatch-fact-extractor` | Extract durable facts from recent tool interactions and persist them to memory |
-| `thatch-dedup-classifier` | Classify and consolidate similar memories surfaced by `thatch_find_duplicates` |
-| `thatch-session-reflection` | Record what was learned during a session — project facts, user preferences, tool tips |
-
-### Code review
-
-| Skill | What it does |
-|-------|-------------|
-| `thatch-review-pedantic` | Mechanical correctness — spelling, naming, doc accuracy, specs, stale artifacts |
-| `thatch-review-acceptance` | Behavioral and product review — UX coherency, behavioral delta, integration effects |
-| `thatch-review-state-flow` | Data flow and contracts — module boundaries, implicit state machines, error propagation |
-| `thatch-review-no-slop` | AI writing anti-pattern detection — change narration, fourth wall breaks, hedging |
-| `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-synthesizer` | Verify specialist findings against actual code, deduplicate, produce severity-grouped report |
-| `thatch-review-context` | Gather project/feature context (PRs, tickets, TODOs, deferred work) before a review |
-| `thatch-workflow-research` | Research code workflows affected by a change or planned change, before reviewing or planning |
-| `thatch-change-walkthrough` | Explain a change as a teaching walkthrough with file:line citations |
-| `thatch-code-walkthrough` | Explain a feature, module, or workflow as a teaching walkthrough; also drafts high-level docs |
-
-### Writing
-
-| Skill | What it does |
-|-------|-------------|
-| `pr-description` | Draft PR descriptions using instructional-design scaffolding with bold/italic emphasis for scanning |
-| `ticket-description` | Draft ticket or issue descriptions (Linear or Jira) with instructional-design scaffolding |
-| `split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs |
-
-### opencode-only
-
-| Skill | What it does |
-|-------|-------------|
-| `thatch-code-review` | Multi-agent review coordinator — triage, partition, dispatch specialists in parallel |
-
-The six review specialists run independently and can be used standalone. The
-synthesizer verifies their findings against the actual code — reading each
-cited location to confirm the evidence matches — before producing a final
-report. The coordinator (opencode only) orchestrates the full pipeline by
-dispatching specialist sub-agents in parallel.
-
-## CLI
-
-The `thatch` CLI ships with the package (installed to your npm global bin by
-`npm install -g`). It requires [Bun] on your PATH — the bin script uses
-`#!/usr/bin/env bun` and all internal modules depend on `bun:sqlite`.
-
-```bash
-thatch stores                    List all stores
-thatch list   [store]            List memory labels in a store
-thatch show   <label> [store]    Display a memory by label
-thatch forget <label> [store]    Remove a memory by label
-thatch search <query> [store]    Semantic search (cosine similarity)
-thatch prime                     Prime project memory (runs via opencode, Cursor, or claude)
-thatch mcp                       Start the stdio MCP server (for Claude Code and Cursor)
-thatch reminder [--json]         Print session-start reminder (for hooks)
-thatch hygiene                   Print the hygiene report (standalone)
-thatch buffer-batch              Append Claude Code PostToolBatch output to extraction queue
-thatch buffer-tool               Append Cursor postToolUse output to extraction queue
-thatch flush-tools [--json]      Peek extraction queue; print extraction + recall nudges
-thatch flush-predictions [--json]  Query predictions for the prompt (hook or standalone)
-thatch setup --claude [--cursor] [--global] Install config + instructions + hooks + skills
-```
-
-Stores default to the repo detected from `git remote`. Use `global` for the
-global store. Use `all` with `search` to search project + global together.
+Include thatch's instructions in your agent's system prompt manually; see
+[docs/dev/mcp-parity.md](docs/dev/mcp-parity.md) for the prompt text.
 
-### Priming a new project
+## What's inside
 
-`thatch prime` bootstraps your project's memory store by having the agent
-investigate the codebase and write foundational memories:
+- **Memory tools**: save, search, list, show, and forget memories with
+  semantic search (local embeddings, SQLite, brute-force cosine).
+- **Prediction engine**: a statistical model of user decision-making
+  preferences. When a prompt matches learned contexts, predictions fire
+  alongside the recall nudge.
+- **Skills**: 19 skills for memory workflows, structured multi-specialist
+  code review, change walkthroughs, and writing tasks (PR descriptions,
+  tickets, PR splitting).
 
-```bash
-cd /path/to/your/project
-thatch prime
-```
-
-This detects `opencode`, Cursor, or `claude` on your PATH and runs the
-`thatch-project-primer` skill, which guides the agent to:
-
-1. Recall any existing project memories
-2. Investigate docs, layout, architecture, commands, and conventions
-3. Write focused memories with clear labels
-4. Reconcile contradictions with existing knowledge
-5. Run dedup to check for overlap
-
-After priming, your agent has context about the project's purpose, structure,
-tech stack, development commands, and conventions — reducing the need to
-re-research these topics in future sessions.
-
-## How it works
-
-Thatch auto-detects your repo identity from `git remote get-url origin`
-(e.g., `sysread/thatch`). Memories are embedded with
-[bge-small-en-v1.5][bge] (384-dimensional vectors, ~34 MB model, cached
-locally) and stored in `~/.config/thatch/thatch.db` (SQLite, WAL mode).
-Search is brute-force cosine similarity — fast enough for thousands of entries.
-
-### Memory capture
-
-Thatch doesn't call an LLM to extract facts. Instead, it buffers recent tool
-interactions and nudges the host agent to persist durable knowledge itself,
-using the `thatch-fact-extractor` skill. The agent's own model decides what's
-worth remembering — keeping thatch dependency-free and the agent in control.
-On OpenCode, the plugin hooks `tool.execute.after` and `chat.message` to
-buffer and peek (the buffer persists until the agent writes a memory). On
-Claude Code, `PostToolBatch` and `UserPromptSubmit` hooks drive a file-backed
-queue with the same peek-not-drain semantics. Both paths produce the same
-payload for the fact-extractor skill.
-
-## OpenCode vs Claude Code vs Cursor parity
-
-| Feature | OpenCode (plugin) | Claude Code (MCP + hooks) | Cursor (MCP + hooks) |
-|---------|-------------------|--------------------------|---------------------|
-| Tools | Plugin tool registration | MCP `tools/list` + `tools/call` | MCP `tools/list` + `tools/call` |
-| System prompt | Injected at runtime with repo name | Static CLAUDE.md (repo auto-detected by MCP server) | Static AGENTS.md (repo auto-detected at startup) |
-| Session-start reminder | `session.created` event | `SessionStart` hook → `thatch reminder` | `sessionStart` hook → `thatch reminder --json` |
-| Compaction context | `experimental.session.compacting` hook | **Gap**: no equivalent (CLAUDE.md persists) | **Gap**: no equivalent |
-| Extraction nudge | `tool.execute.after` + `chat.message` | `PostToolBatch` + `UserPromptSubmit` (file-backed queue) | `postToolUse` + `beforeSubmitPrompt` (file-backed queue) |
-| Prediction auto-fire | `chat.message` hook, separate try/catch from recall | `flush-tools` tier 2 (sideband socket) | `flush-tools` tier 2 (sideband socket) |
-| Setup detection at startup | n/a (plugin auto-installs) | `checkSetup` in MCP server: detects missing/broken instructions | Same as Claude Code |
-| Skills | 19 (18 shared + coordinator) | 18 (shared only) | 18 (shared only) |
-| Store detection | `worktree` param from plugin | `CLAUDE_PROJECT_DIR` env var | `CURSOR_PROJECT_DIR` then `CLAUDE_PROJECT_DIR` |
-
-See [docs/dev/mcp-parity.md](docs/dev/mcp-parity.md) for the full analysis.
+See the [user guide](docs/user/README.md) for the full tool list, CLI
+commands, configuration, environment variables, and detailed setup for each
+host.
 
 ## Privacy
 
 Everything is local. The embedding model downloads once from Hugging Face Hub
 and is cached. No data leaves your machine.
 
-## Docs
-
-- [User guide](docs/user/README.md) — setup, tools, configuration
-- [Development](docs/dev/README.md) — architecture, module responsibilities, data flow
-- [MCP parity](docs/dev/mcp-parity.md) — OpenCode plugin vs Claude Code MCP feature comparison
-- [QA & tests](docs/qa/README.md) — test conventions, categories, use case format
-- [Plans](docs/plans/) — numbered design documents capturing decisions
-
 ## Development
 
 ```bash
-bun install        # deps
-bun test           # full suite: zero network, zero external deps
-bun test --watch   # watch mode
+bun install
 mise run check     # typecheck + bun test + markdownlint (the CI gate)
 ```
 
 Tests never reach outside the sandbox: temp-directory SQLite files, mock
-embeddings, no network. `mise run check` is the full quality gate; `mise run
-typecheck` or `mise run lint-md` run those alone.
+embeddings, no network.
+
+## Docs
+
+- [User guide](docs/user/README.md) -- setup, tools, configuration, CLI
+- [Development](docs/dev/README.md) -- architecture, module responsibilities
+- [MCP parity](docs/dev/mcp-parity.md) -- OpenCode plugin vs MCP feature comparison
+- [QA & tests](docs/qa/README.md) -- test conventions, use cases
+- [Design docs](docs/in-progress/) -- in-progress design notes
 
 ## License
 
 MIT
 
 [Bun]: https://bun.sh
-[bge]: https://huggingface.co/BAAI/bge-small-en-v1.5