clatter-bus 0.1.0__tar.gz

clatter_bus-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Local-only notes (machine-specific / private details) — kept out of the repo on purpose
+INTERNAL_NOTES.md
+
+# Runtime artifacts (only appear if you run/develop in-tree)
+relay.log
+registry/
+mailbox/
+
+# settings.json backups written by install/uninstall
+*.bak-*
+
+# Python build artifacts
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+
+# editor / OS cruft
+*.swp
+*~
+.DS_Store

clatter_bus-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,173 @@
+# Architecture
+
+Clatter is a per-machine message bus for interactive Claude Code sessions. This document covers
+how it works, the security model, and the design decisions behind it. For usage, see
+[README.md](README.md).
+
+## The problem that dictates the shape
+
+Three facts about Claude Code sessions drive every design choice:
+
+1. **They're interactive CLI processes, one per tmux pane** — not an SDK you can push messages into.
+   The only way to inject a turn into a live interactive session is `tmux send-keys` into its pane.
+   tmux delivers immediately if the pane is idle at the prompt and **queues** the keystrokes if it's
+   mid-turn, so a busy session picks the message up when it returns to the prompt — no interrupt
+   logic required.
+2. **Pane identity drifts.** A pane's id (`%76`) can be remapped by tmux resurrect/continuum on
+   restore, while the process keeps a stale `$TMUX_PANE` in its environment. The **tty**
+   (`/dev/pts/N`) is the identity that never lies. So a session registers its **pid**, and the relay
+   resolves pid → tty → current pane *live, at wake time*.
+3. **Nothing runs between turns.** An idle session executes nothing; hooks fire only on user/agent
+   events. So the wake must come from *outside* the session — a long-running relay.
+
+A passive "bulletin board" (sessions read a shared file when the user next prompts them) cannot do
+real-time round-trips: a query would sit unread until you visited that pane, and the reply until you
+visited the asking pane. Real-time requires something that can wake an idle session. Hence the relay.
+
+## Components
+
+```
+~/.claude/clatter/
+├── scripts/
+│   ├── _bus_common.sh        # shared paths + pid→tty→pane + sessionId/live-name resolvers
+│   ├── bus-register.sh       # register/refresh this session (keyed by sessionId)
+│   ├── bus-send.sh           # drop a message (local, or over SSH to a peer machine)
+│   ├── bus-recv.sh           # drain inbox, render as untrusted data  (backs /clat recv)
+│   ├── bus-resolve.sh        # resolve a live name -> local sessionId (used locally + over SSH)
+│   ├── bus-peers.sh          # list the registry with live names
+│   ├── bus-cleanup.sh        # prune dead-pid entries
+│   ├── bus-deregister.sh     # remove one entry
+│   ├── bus.sh                # /clat dispatcher (peers|ask|send|broadcast|recv|status)
+│   ├── bus-hook-register.sh  # SessionStart hook
+│   └── bus-hook-deregister.sh# SessionEnd hook
+├── relay/clatter-relay.sh  # the daemon (systemd --user)
+├── registry/<sessionId>.json # live sessions (pid-anchored; no name/pane id stored)
+├── mailbox/<sessionId>/      # <epoch_ms>-<rand>.json messages + archive/
+├── manual-patterns           # cwd globs that register manual (relay never types into them)
+└── peers                     # SSH host aliases for cross-machine discovery
+```
+
+The message-bus terminology (`bus-*.sh`, "on the bus") is the accurate description of the mechanism:
+Clatter is a message bus; the `bus-*` scripts are its implementation.
+
+### Registry — `registry/<sessionId>.json`
+One file per live session, written by the SessionStart hook, keyed by the Claude **sessionId** (a
+UUID, stable across `/rename` and `claude -c`) so a rename never re-keys anything:
+```json
+{ "sessionId":"a1b2c3d4-…", "pid":962981, "machine":"host",
+  "cwd":"/home/user/api", "mode":"auto", "started":"…" }
+```
+`pid` is the liveness anchor and what the relay resolves to a pane. **No name and no pane id are
+stored** — the name is resolved live (see Naming). `mode` is `auto` (relay may wake it) or `manual`
+(relay never types into it).
+
+### Mailbox — `mailbox/<sessionId>/`
+Per-session inbox. Messages are JSON files named `<epoch_ms>-<rand>.json` (the message `id`).
+Processed files move to `archive/`. Writes are atomic (tmp file + `rename()`), so no partial reads.
+FIFO by filename, which sorts by the millisecond prefix.
+
+### Relay — `relay/clatter-relay.sh` (systemd `--user` service)
+Runs as your user so it can reach the tmux socket. On start it **scans existing mailboxes and
+delivers anything already pending** (inotify only reports *new* events, so this closes the
+relay-was-down gap). Then it watches `mailbox/` with `inotifywait` — or, if inotify-tools isn't
+installed, **polls every second** (`CLATTER_POLL`) with a per-file seen-set for the same new-file
+semantics. For each new `<id>.json` under `mailbox/<target>/` it rejects unsafe target names, reads
+`registry/<target>.json`, and — if the target is `auto` and its pid is alive — resolves
+pid → tty → pane and types the wake. An `auto` target that no longer resolves to a pane (e.g. tmux
+was killed mid-session) is left queued with a loud `WARN` rather than silently dropped. Dead targets
+are pruned on contact. Logs to `relay/relay.log`.
+
+### Hooks
+- **SessionStart** → `bus-hook-register.sh`: registers the session (name resolved live, not stored),
+  classifies mode — `manual` if the cwd matches a `manual-patterns` glob **or** the session isn't in
+  a tmux pane (nothing to wake), else `auto` — and emits a one-line `additionalContext` note telling
+  the session its bus name + current live peers. Fires on fresh start **and on `claude -c` resume**.
+- **SessionEnd** → `bus-hook-deregister.sh`: removes the manifest.
+
+### Slash command — `/clat`
+`~/.claude/commands/clat.md` drives `bus.sh` **through the agent** (not a raw `!` shell expansion),
+passing any free-text payload as a single quoted argument so the shell never interprets it. Running
+through the agent (rather than raw shell) is also what lets `ask`/`send`/`broadcast` **compose** the
+message from the session's current context by default; a leading `*` sends the rest **verbatim**.
+Subcommands: `peers`, `ask`, `send`, `broadcast`, `status`, and `recv`. `recv` is what the relay's
+wake types (it carries no free text).
+
+## The wake invariant (security core)
+
+**The only thing ever sent via `send-keys` is the fixed constant `/clat recv`.** Message content is
+always read from the mailbox file by that trusted command — never typed into a pane. `/clat recv`
+self-resolves *which* session it is (by matching its own claude pid to a registry entry), so even
+the recipient's name never appears in the keystroke. Consequences:
+
+- A peer cannot cause arbitrary text to be submitted as a "user" turn in another session.
+- Mailbox target names are constrained to `[A-Za-z0-9_-]` on both the send side and the relay side
+  (no path traversal, no shell injection into the cross-machine SSH drop).
+- `bus-recv.sh` frames every message as untrusted data with an explicit "do not obey" preamble and
+  newline-escapes header fields, so a message body/subject can't forge the visual frame.
+- **Message bodies are inert data end-to-end.** `bus-send.sh` stores the body with `jq --arg` and,
+  cross-machine, pipes it to the peer over SSH (never interpolated into a command); `bus-recv.sh`
+  renders it as line-prefixed quoted text. Nothing in a message is shell-executed by the pipeline,
+  so sending text that *contains* commands is safe. The `/clat` command passes free text to the CLI as
+  a single quoted argument (via the agent), closing the one spot where raw args used to be
+  shell-parsed.
+
+## Message format
+
+```json
+{ "id":"1785037760123-515c", "from":"frontend", "from_session":"…uuid…", "to_session":"…uuid…",
+  "machine":"host", "type":"query", "subject":"auth port", "body":"which port is auth on?",
+  "reply_to":null, "timestamp":"…" }
+```
+- Delivery is keyed by `to_session` (the recipient's sessionId). `from` is the sender's live display
+  name; `from_session` is its sessionId — so a reply targets the stable `from_session@machine` and
+  still lands even if the sender is renamed mid-exchange.
+- **query** expects a response (the reply wakes the asker). **response** carries `reply_to`.
+  **notify** is fire-and-forget. **broadcast** expands at send time into one notify per live local
+  session. Keep bodies small; send a file path, not a payload, for anything large.
+
+## Liveness & pruning
+
+A session is live iff its **pid** is running — that is the sole pruning criterion. Wakeability
+(resolving to a tmux pane) is a *separate* property: an alive session with no pane is a valid
+`manual`/poll participant, not a dead one, and is never pruned for lacking a pane. Pruning is
+belt-and-braces: the relay deletes an entry the moment it tries to wake an `auto` target whose pid is
+dead, and a systemd timer (`clatter-cleanup.timer`, every 5 min) sweeps the rest with
+`bus-cleanup.sh` — also pid-only.
+
+## Naming & addressing
+
+The addressable **name is resolved live**, never stored, in this order:
+1. the latest `custom-title` record in the session's transcript
+   (`~/.claude/projects/*/<sessionId>.jsonl`) — this captures both a local `/rename` **and a web-UI
+   rename** (the sync daemon writes the cloud rename into the transcript, even though it does *not*
+   update the session file's `.name`);
+2. Claude's session-file `.name` (`~/.claude/sessions/<pid>.json`) — the derived/auto name;
+3. the cwd basename.
+
+So `/clat peers`, `/clat status`, and `/clat ask <name>` always reflect the *current* name — rename a
+session anywhere and the bus follows, with no re-keying (the key is the sessionId). Names may
+contain spaces and never touch a filesystem path or an SSH command line (those use the UUID), so
+there are no charset restrictions on them. Address a peer by its current name, or by a sessionId
+directly (what replies use); append `@machine` to force a host. Same-name collisions resolve to the
+first match — use `name@machine` or the sessionId to disambiguate.
+
+## Cross-machine
+
+Address a peer explicitly as `name@machine` (an SSH host/alias). `bus-send.sh` drops the message
+into that host's mailbox over SSH. The peer's own relay wakes
+the pane, and `bus-recv.sh` renders a `reply to: <from_session>@<machine>` target (a sessionId, so
+replies survive a rename). This reuses your existing SSH keys; verified host↔host in both directions.
+
+Discovery is on-demand over SSH (no daemon, no sync): list peer hosts in `$CLATTER_ROOT/peers`
+(SSH aliases, one per line). `bus-peers.sh` aggregates each peer's `--json` output into `/clat peers`
+(rows shown as `name@host`, each peer resolving its own live names). Addressing a bare name that
+isn't local runs `bus-resolve.sh` on each peer (the name piped in over stdin — never interpolated
+into the remote command) to map it to that host's sessionId, routing to the first match; use
+`name@host` or a sessionId to disambiguate. `broadcast` is local-machine only.
+
+## Why `send-keys`, not a headless run
+
+An alternative is to resume the target session headlessly (`claude -c -p "…"`) to answer. That forks
+a turn the live interactive pane never renders and races the session's transcript — wrong when a
+human is watching that pane. `send-keys` drives the *real* session the user is looking at, so the
+exchange shows up as visible turns in both panes.

clatter_bus-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Brandon Thomas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

clatter_bus-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: clatter-bus
+Version: 0.1.0
+Summary: Real-time message bus for Claude Code sessions — one asks, another wakes and answers, hands-free.
+Project-URL: Homepage, https://github.com/brandonrthomas/clatter
+Project-URL: Repository, https://github.com/brandonrthomas/clatter
+Project-URL: Issues, https://github.com/brandonrthomas/clatter/issues
+Author-email: Brandon Thomas <brandon.thomas.r@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,claude,claude-code,cli,ipc,message-bus,tmux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Clatter
+
+**A real-time message bus for Claude Code sessions.** Run many `claude` sessions at once — one
+per tmux pane — and let them talk to each other: one session asks another a question, the other
+*wakes on its own*, answers, and the reply lands back in the asking pane. No copy-paste between
+panes, no human relay.
+
+<p align="center">
+  <img src="docs/demo.gif" alt="Clatter — one session asks, another wakes and answers, and the reply lands back" width="860">
+</p>
+<p align="center"><sub>Two Claude Code sessions over the bus — ask on the left; the peer auto-wakes and answers on the right.</sub></p>
+
+<br>
+
+---
+
+```
+  session "frontend"                     relay (per machine)                    session "api"
+  ──────────────────                     ───────────────────                    ─────────────
+  /clat ask api which port is the
+       auth service on?  ────────────▶  new message for "api"
+                                              │  resolve api → its tmux pane
+                                              └─ wake it ──────────────────────▶ (idle or busy)
+                                                                                      │
+                                                              reads the question, answers "8081",
+                                                              sends the reply back:
+        reply appears in your pane  ◀──────  new message for "frontend"  ◀────────────┘
+```
+
+Clatter = **Claude** + **chatter** — it lets Claude Code sessions chatter to each other across
+tmux. Under the hood it's a small, dependency-light message bus — a few bash scripts, a file-drop
+mailbox, and one tiny relay daemon.
+
+---
+
+## Why
+
+If you run a fleet of Claude Code sessions (one per project/pane), they can't see each other. You
+end up hand-carrying facts between them: *"the other session set the port to 8081"*, *"the model
+you loaded is aliased `qwen-large`"*. Clatter gives them a phone line. A session can consult a
+peer that actually **owns** the answer, in real time, without you in the middle.
+
+## Features
+
+- **Real round-trips.** `/clat ask <peer> <question>` sends a query; the answer comes back to *your*
+  pane asynchronously — because the relay can wake an idle session, not just leave it a note.
+- **Names you recognize, live.** A session's bus name is its **Claude session name** (what `/rename`
+  sets, shown in your tab) — resolved live, so renaming a session (locally *or* from the web UI) is
+  reflected immediately, with no manual wiring. Sessions auto-register at start and on `claude -c`.
+- **Self-cleaning.** Dead sessions are pruned automatically (on contact and on a timer).
+- **Safe by design.** The only thing ever typed into another pane is a fixed control string — never
+  message content — so a peer can't inject an arbitrary "user" turn. Sensitive workspaces can be
+  marked read-only to the relay, and `/clat doctor` audits that the guard actually covers them. (See
+  [Security](#security).)
+- **Small + legible.** Bash + `jq` + `inotifywait` + `tmux`. One systemd `--user` relay. No server,
+  no database, no ports.
+
+## How it works (in three facts)
+
+1. **Sessions are interactive `claude` CLIs, one per tmux pane.** The only way to hand a running
+   interactive session a new turn is `tmux send-keys` into its pane — which delivers instantly if
+   it's idle and *queues* if it's mid-turn.
+2. **The target pane is resolved live, never stored.** Pane ids drift (tmux resurrect/renumber), so
+   nothing caches a pane id: each session is keyed by a stable **sessionId** (which also names its
+   mailbox, so a rename never misroutes), and at wake time the relay looks up that session's **pid**
+   and resolves pid → tty → current pane.
+3. **Nothing runs between turns**, so the push comes from outside: a per-machine **relay daemon**
+   watches the mailboxes (`inotifywait`) and wakes the target pane when a message arrives.
+
+Full design in [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Requirements
+
+- Linux with **tmux** for auto-wake — a session that should be woken automatically must run in a
+  tmux pane. A session outside tmux still works, in manual (poll) mode (see **Manual mode** below).
+- **`jq`** and **systemd** with user services + lingering. **`inotify-tools`** (`inotifywait`) is
+  recommended but optional — without it the relay falls back to polling.
+- **Claude Code** (the `claude` CLI) with hooks and custom slash commands. Note: `claude --safe-mode`
+  disables *all* customizations — hooks and custom commands don't load — so a safe-mode session won't
+  join the bus or have `/clat`.
+
+```bash
+sudo apt install jq inotify-tools tmux      # Debian/Ubuntu
+loginctl enable-linger "$USER"              # so the relay survives logout/reboot
+```
+
+## Install
+
+Via pip (the package is `clatter-bus`; the command is `clatter`):
+
+```bash
+pip install clatter-bus
+clatter install
+```
+
+…or straight from the repo:
+
+```bash
+git clone https://github.com/brandonrthomas/clatter.git
+cd clatter
+./install.sh
+```
+
+Both run the same `install.sh` — it's idempotent. It copies the code to `~/.claude/clatter/`, installs the `/clat` slash
+command, wires `SessionStart`/`SessionEnd` hooks into `~/.claude/settings.json` (backing it up
+first, preserving everything else), and enables the relay + cleanup timer. Open new sessions (or
+`claude -c` existing ones) and they'll join.
+
+## Usage
+
+From inside any session:
+
+```
+/clat peers                       # who's on the bus (name, machine, alive, mode, description)
+/clat ask <name> <question>       # ask a peer; the answer returns to THIS pane, asynchronously
+/clat send <name> <message>       # fire-and-forget notify
+/clat broadcast <message>         # notify every live session
+/clat recv                        # read your inbox (the relay normally triggers this for you)
+/clat clear                       # archive your inbox without reading it
+/clat status                      # your own bus name + pending inbox
+/clat mode [auto|manual]          # show or set whether the relay may wake this session
+/clat desc [text]                 # show or set this session's description (shown in /clat peers)
+/clat doctor                      # audit the manual-mode guard — what the patterns actually match
+```
+
+Everywhere above, `<name>` is a peer's **Claude session name** — the name `/rename` sets, shown in
+its tab — matched live, so it always tracks the session's current name. (Leave a session unnamed and
+it uses Claude's auto-generated name, e.g. `host-quiet-tome`.)
+
+If two live sessions resolve to the **same** name, they're disambiguated with a `-2`/`-3` suffix in
+`/clat peers` and when addressing (the earliest keeps the bare name); a session that *renames* into a
+collision gets a heads-up to pick a unique one. The suffix is display/addressing only — delivery is
+keyed by sessionId, so it never misroutes.
+
+`/clat ask` doesn't block — you keep working; when the peer answers, the relay wakes your pane and
+the reply appears inline.
+
+**Composing vs. verbatim.** For `ask` / `send` / `broadcast`, the text after the command is normally
+an *instruction for what to communicate*: the session composes the actual message from its current
+context and sends that — e.g. `/clat ask box tell them the port I just set` sends something like
+`The auth port is 8081.` (A self-contained question is just sent as-is.) To send text **exactly** as
+written — a command, a snippet, precise wording — prefix it with `*`: `/clat send api *rm -rf /tmp/cache`
+stores that literal string as a message (it is never executed).
+
+**Cross-machine.** List your other hosts in `~/.claude/clatter/peers` (one SSH alias per line).
+Then `/clat peers` aggregates their live sessions (shown as `name@host`), and `/clat ask <name> <question>`
+auto-locates a peer across those hosts — or address one explicitly as `name@host`. The message is
+dropped over SSH into that host's mailbox and its relay wakes the pane; replies route back
+automatically. Requires Clatter on each
+host and key-based SSH between them.
+
+## Configuration
+
+| What | How |
+|---|---|
+| Install location | `CLATTER_ROOT` (default `~/.claude/clatter`) |
+| This machine's name | `CLATTER_MACHINE` (default `hostname -s`) — used for cross-machine addressing |
+| Read-only workspaces | add globs matching your **real dir names** to `~/.claude/clatter/manual-patterns`; verify with `/clat doctor` (see `manual-patterns.example`) |
+| Cross-machine peers | list SSH hosts in `~/.claude/clatter/peers` (see `peers.example`) |
+
+**Manual mode.** A registered, fully addressable session that the relay will **never** type into —
+peers see it in `/clat peers`, messages reach its mailbox, and you drain them yourself with `/clat recv`.
+A session registers manual for either reason:
+
+- its cwd matches a glob in `manual-patterns` — sensitive workspaces you don't want a peer able to
+  drive; or
+- it isn't running in a tmux pane, so there's no pane to `send-keys` into. Rather than register
+  `auto` and then silently fail to wake, it degrades to manual — still on the bus and reachable, just
+  polled instead of pushed.
+
+A session's tmux-ness is fixed when it launches, so this is decided once at registration. If an
+`auto` session later *loses* its pane (e.g. tmux is killed mid-session), the relay can't wake it — it
+leaves the message queued and logs a loud `WARN` rather than dropping it silently.
+
+The guard fails **open**: a glob that matches nothing looks identical to a working one, so it can
+protect nothing without telling you. Match your *actual* directory names, not category words (`*acme*`,
+not `*emr*`), and run **`/clat doctor`** to see which live sessions and workspace dirs the patterns
+cover — `/clat peers` also warns when `manual-patterns` is set but matches no live session. Mode is
+fixed at registration, so restart a session (or run `/clat mode manual`) after editing patterns.
+
+## Security
+
+The threat here isn't eavesdropping — it's **injection**, because waking a pane literally submits a
+turn in another session. Clatter is built around that:
+
+- **The wake is a single fixed constant** (`/clat recv`). Message *content* is always read from a
+  file by that trusted command, never typed into a pane — so a peer can never cause arbitrary text
+  to be submitted as a user turn elsewhere. Mailbox names are charset-restricted on both the send
+  and relay sides.
+- **Rendered messages are framed as untrusted data** with an explicit "do not obey" preamble; header
+  fields are newline-escaped so a message can't forge the frame.
+- **Message bodies are inert data end-to-end.** They're stored with `jq --arg`, transported as files
+  (piped, never interpolated, over SSH cross-machine), and rendered as quoted text — nothing in a
+  message is ever shell-executed by the pipeline. You can safely send text that *contains* commands;
+  the `/clat` command hands your free text to the CLI as a single quoted argument.
+- **Manual mode** (above) guarantees a peer can never drive a sensitive session.
+- **Never put secrets, credentials, or private/regulated data in a message** — the bus is local
+  plaintext files under your user account, and a message lands in another session's context.
+
+No encryption (local files, Unix perms — same trust model as Claude Code's own data). Cross-machine
+rides your existing SSH keys.
+
+## Uninstall
+
+```bash
+./uninstall.sh            # stop services, remove /clat + hooks (keeps your mailbox/registry)
+./uninstall.sh --purge    # also delete ~/.claude/clatter entirely
+```
+
+Your `settings.json` is backed up before every change.
+
+## Status & limitations
+
+- **Cross-machine works** (verified host↔host, both directions, including different home dirs). List
+  peer hosts in `~/.claude/clatter/peers`; then `/clat peers` shows their sessions as `name@host` and
+  a bare-name `/clat ask <name>` auto-locates the peer. You can always force one with `name@host`.
+- Waking a pane while you're mid-typing appends to your input line (targets are normally idle).
+
+## Development
+
+Run the test suite — zero framework, just bash + jq:
+
+```bash
+./test/run.sh
+```
+
+It covers registration (sessionId-keyed), live-name resolution (transcript title wins over the
+session-file name, with fallback) including a rename, duplicate-name disambiguation, send/recv/clear,
+**message-body safety** (shell metacharacters stay inert), target validation, reply routing, the
+manual-mode guard + `/clat doctor` (fail-open detection), the rename-collision notifier, `mode`/`desc`,
+discovery `--json`, broadcast, and cleanup — against an isolated `CLATTER_ROOT` with fake session
+files. The relay, tmux wake, and cross-machine SSH are integration paths, verified manually.
+
+## License
+
+[Apache-2.0](LICENSE) © 2026 Brandon Thomas