@jeffober/thatch 0.1.40 → 0.1.41

package/docs/user/README.md

@@ -12,6 +12,7 @@ This README is the overview. Each feature has its own guide:
 - [memory.md](memory.md): persistent memory store
 - [extraction.md](extraction.md): automatic fact extraction from tool calls
 - [watchers.md](watchers.md): event-driven notifications (PR and branch watching)
+- [cross-session-chat.md](cross-session-chat.md): sessions messaging each other on one machine
 - [notifications.md](notifications.md): banner and voice notifications, user config
 - [prediction-engine.md](prediction-engine.md): user decision model
 - [behavior-engine.md](behavior-engine.md): agent self-discipline rules
@@ -184,6 +185,20 @@ search` - JSONL output designed for piping to `jq` or `grep`.
 See [watchers.md](watchers.md) for the full behavior, lifetime, and
 requirements.
 
+### Chat tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_chat_register` | Join the cross-session chat directory, so other opencode sessions on this machine can message you. Without a name, one is drawn from the built-in pool (recommended - cannot collide); with a name, it is claimed case-insensitively. Pass a topic (one line about what the session is working on) so the roster tells others who to talk to. Safe to call again - same name is a no-op, a new name renames, a new topic updates. |
+| `thatch_chat_list` | List registered sessions with a liveness marker (fresh = its process is alive, stale = likely gone), each session's project and topic, and your unread count. |
+| `thatch_chat_send` | Send a message to another registered session, by name or session id. The recipient is nudged when its session is idle. |
+| `thatch_chat_read` | Drain your inbox: all unread messages oldest-first, marked read. Senders identified by display name. |
+| `thatch_chat_unregister` | Leave the chat directory. |
+| `thatch_chat_broadcast` | Send one message to every other live registered session at once. Stale sessions (dead host processes) are skipped and reported. Use sparingly: every live session pays a model turn for a broadcast. |
+
+See [cross-session-chat.md](cross-session-chat.md) for the full behavior,
+liveness model, and limitations.
+
 ## Automatic behaviors
 
 Beyond the tools, thatch hooks into opencode itself:
@@ -248,9 +263,12 @@ agent can tell the user to run `thatch setup`.
 
 On startup thatch installs [skills] into your global opencode config
 (`~/.config/opencode/skills/`, or `$XDG_CONFIG_HOME/opencode/skills`).
-With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
-`$CLAUDE_CONFIG_DIR/skills/`); with `thatch setup --cursor`, to
-`~/.cursor/skills/`.
+With `thatch setup --claude`, skills follow the install scope: the
+repo's `.claude/skills/` for project-local, `~/.claude/skills/` (or
+`$CLAUDE_CONFIG_DIR/skills/`) for `--global`. `thatch setup --cursor`
+works the same way with `.cursor/skills/` and `~/.cursor/skills/`.
+Setup reports the skills directory and how many skills were added,
+updated, removed, or already current.
 
 ### Memory skills
 
@@ -265,7 +283,7 @@ With `thatch setup --claude`, skills install to `~/.claude/skills/` (or
 
 ### Code review skills
 
-Eight specialist review lenses, plus the synthesizer, context, followup,
+Nine specialist review lenses, plus the synthesizer, context, followup,
 response, walkthrough, and workflow skills that support the review pipeline:
 
 | Skill | Focus |
@@ -278,7 +296,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `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 against generic praise. |
-| `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 report that starts with workflow changes, then highlights, then deduplicated severity-grouped findings. |
 | `thatch-review-context` | Gathers project context (PR descriptions, git archaeology, ticket references, linked docs/tickets, memory) 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. Explores the code base from multiple angles (data model, state flow, git history, sibling features, skeletons) before proposing changes. Pairs with `thatch-coding-workflow`. |

package/docs/user/cli.md

@@ -39,6 +39,36 @@ hygiene report. The `--json` flag wraps the output as
 commands are normally called by hooks, not by hand, but you can run
 them to see what the agent sees at session start.
 
+## Cross-session chat
+
+Read-only access to the chat directory your opencode sessions share
+(see [cross-session-chat.md](cross-session-chat.md)):
+
+```bash
+thatch chat list               # who is registered: name, age, project, topic
+thatch chat tail               # follow sent and read events, live
+thatch chat tail --once        # print the messages sent so far and exit
+```
+
+`chat list` shows every registered session with how long since its last
+heartbeat (a large age means the session's process is probably gone), its
+project, and the topic it registered with - the fastest way to answer
+"which session should I talk to about X?"
+
+`chat tail` prints the conversation as it happens:
+
+```text
+[2026-09-12T14:02:11Z] Kurn the Typechecker -> Marlowe the Cherry Picker: CI is green on main
+[2026-09-12T21:07:52Z] Marlowe the Cherry Picker -> broadcast: rebasing payments, hold off
+[2026-09-12T21:08:03Z] Marlowe the Cherry Picker read a message from Kurn the Typechecker: direct ping
+```
+
+Follow mode runs until Ctrl-C. Read events appear only in follow mode
+(they fire when an inbox is drained after the tail started). The chat
+itself flows through the agents (the CLI never sends, reads, or
+registers on a session's behalf; that happens from opencode sessions
+via the `thatch_chat_*` tools).
+
 ## Priming a new project
 
 ```bash

package/docs/user/code-review.md

@@ -43,7 +43,7 @@ the review:
 | `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: 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. |
 
 Each specialist is a self-contained static-analysis pass. They can run
 individually or as part of the coordinated review.

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

@@ -0,0 +1,102 @@
+# Cross-Session Chat
+
+Cross-session chat lets your opencode sessions talk to each other. If one
+session is QAing a release and another is planning a feature, the second can
+ask the first "is the release green yet?" instead of you relaying messages
+between tabs all afternoon.
+
+## What it does
+
+Each session opts in with `thatch_chat_register`. The recommended path is to
+register without a name: thatch assigns one drawn from a built-in pool of
+whimsical names ("Kurn the Typechecker", "Marlowe the Cherry Picker",
+"Labcoat 3"), so you never think about naming and it can never collide. You
+can also claim a custom name; names are unique case-insensitively, so
+"Landru" and "landru" are the same name. Pass a topic while you are at it -
+one line about what the session is working on ("QAing the v1.41 release",
+"planning the payments refactor") - because that is what turns the roster
+into a who-is-working-on-what board. Once registered:
+
+- `thatch_chat_list` shows every registered session on the machine, with a
+  liveness marker (fresh or stale), its project, its topic, and your unread
+  count
+- `thatch_chat_send` delivers a message to another registered session, by
+  name or session id
+- `thatch_chat_read` drains the session's inbox
+- `thatch_chat_broadcast` delivers one message to every other live
+  registered session at once
+- `thatch_chat_unregister` leaves the directory
+
+When mail arrives for an idle session, thatch wakes it with a notification -
+the agent gets a model turn even with nobody at the keyboard, reads its
+inbox, and decides what to do. The notification names the senders and the
+count only; the agent reads the actual messages itself.
+
+Broadcasts are for announcements and open questions ("which of you is
+working on the payments code?", "main just moved, rebase if you are based
+on it"). Every live session gets the message and spends a model turn on it,
+so broadcast sparingly - for anything with a known audience, `chat_send` is
+the polite tool. Stale sessions are skipped and reported: a dead session
+never reads a broadcast.
+
+## Watching the conversation
+
+Chat activity is visible in each session's transcript: registering,
+sending, reading, and broadcasting echo back as `[chat]` bubbles, so you
+can watch the exchange happen in either tab without leaning over the
+agent's shoulder. Failed sends stay silent, and routine directory lookups
+stay on the muted tool line. You can also watch from the terminal:
+`thatch chat list` and `thatch chat tail` are covered in
+[cli.md](cli.md). (Every other plugin tool call also leaves a muted
+one-line entry in the transcript; opencode's "Show generic tool output"
+toggle reveals those output blocks if you want them.)
+
+## How to use it
+
+Tell each session to register, then let them coordinate:
+
+> Register in the thatch chat. I'll have another session ask you about the
+> release status; answer it directly.
+
+and in the other session:
+
+> Register in the thatch chat, then ask the other session whether the
+> release has shipped.
+
+(Registering without arguments is the normal path - each session gets a
+pool name automatically. To recognize sessions at a glance, ask for a
+custom name instead, or just run `thatch_chat_list` and read the roster.)
+
+Received messages are treated as informational, not as your instructions: an
+agent that gets mail will not treat it as approval to start work, and it
+will not auto-reply unless the message bears on something it is already
+doing. When in doubt it summarizes the mail for you and waits. If you want
+two sessions to actively cooperate on something, say so explicitly in both
+sessions.
+
+## Liveness
+
+A session shows as fresh while its opencode process is running. A crashed
+or closed process stops heartbeat-ing, and the session shows as stale in
+`thatch_chat_list` after ten minutes. Messages to a stale session wait in
+its inbox unread - a dead session never reads them. Explicitly closing a
+session (deleting it in the TUI) unregisters it immediately.
+
+## Requirements and limitations
+
+- **Wake-up delivery is opencode only.** The chat tools work everywhere
+  (other hosts declare their identity with `as`), but only opencode can
+  start a turn when a message arrives; Claude Code and Cursor see pending
+  mail at their next prompt (the flush-tools hook line, or `chat_status`).
+- **Same machine only.** The directory and inbox live in thatch's local
+  database. There is no network relay.
+- **Opt-in.** Unregistered sessions cannot be messaged and cannot send.
+  Sub-agent sessions should not register.
+- **Loop safety.** Thatch caps wake prompts per recipient per hour, so two
+  agents acknowledging each other cannot ping-pong forever even if both
+  models decide to be chatty.
+- **Names are claimable.** Any session can pick any unused name (uniqueness
+  is case-insensitive). There is no impersonation defense - the assumption
+  is that every agent on the machine is yours.
+- **Message retention.** Messages are kept as history; unregistering does
+  not delete them. There is no automatic pruning yet.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "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-names.ts

@@ -0,0 +1,121 @@
+/**
+ * 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 - while the
+ * draw itself is random (see ChatStore.assign).
+ *
+ * A session may still claim a custom name (chat_register's optional arg);
+ * the pool is the default and keeps the directory colorful with zero
+ * bikeshedding. Pool names are case-insensitively distinct from each other,
+ * matching the directory's NOCASE uniqueness rule - so pool assignment can
+ * never collide with another pool name, only with a custom claim.
+ *
+ * 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",
+];