1 files changed, 108 insertions, 0 deletions
diff --git a/tmuxrdr/README.md b/tmuxrdr/README.md
new file mode 100644
index 00000000..b152b39e
--- /dev/null
+++ b/tmuxrdr/README.md
@@ -0,0 +1,108 @@
+# tmuxrdr
+
+herdr without the disrespect for tmux users.
+
+[herdr](https://herdr.dev) is a terminal workspace manager for AI coding
+agents: tmux's model -- a server owning panes, clients attaching -- plus an
+agent-aware sidebar. Its keys are its own. tmuxrdr is herdr with tmux's keys
+and tmux's behaviour wherever herdr can be made to have them: tmux 3.7c's
+default prefix table, with this machine's `dot/config/tmux.conf` and
+`~/.tmux.conf.local` on top.
+
+Everything tmuxrdr adds is in this directory. The rest of the checkout is
+herdr, untouched, on a herdr release tag.
+
+| Path | What |
+|---|---|
+| `config/config.toml` | herdr config: tmux's bindings on herdr's actions, each commented with the tmux line it mirrors |
+| `plugin/` | the tmux-mode herdr plugin: the bindings herdr has no action for -- break-pane, swap/rotate by pane order, marks, last session, select/move-window, paste-buffer, display-message, select-layout -E, kill with y/n, the `:` prompt, clock, messages, automatic-rename |
+| `scripts/install` | puts this machine on the config and plugin |
+| `scripts/test-e2e` | presses every binding in a real herdr client and checks the result |
+| `scripts/sync-upstream` | rebases tmuxrdr onto a newer herdr release |
+| `ROADMAP.md` | what only a patch to herdr's code can do, with the patch for each |
+
+## Status
+
+- Based on herdr **v0.9.3**, the release Homebrew ships.
+- Of tmux's 88 default prefix bindings, **67 work** (some approximately --
+  ROADMAP.md, "Coverage"), **5 are moot** in herdr, **16 need code**.
+  `scripts/test-e2e`: 66 checks, all passing on v0.9.3.
+- **No herdr code is patched yet.** The config and plugin run on stock herdr;
+  the first code patches are in ROADMAP.md, smallest first.
+
+## Install
+
+```sh
+tmuxrdr/scripts/install        # dry run: what it would do
+tmuxrdr/scripts/install yes
+```
+
+It links `~/.config/herdr/config.toml` to `config/config.toml`, keeping a real
+file already there as `config.toml.pre-tmuxrdr`, and
+`~/.local/share/tmuxrdr/plugin` to `plugin/`, which it registers with
+`herdr plugin link`. herdr saves its settings in place, so changes made from
+its settings screen land in `config/config.toml` too -- `git diff` shows them.
+Then, in a running herdr: `prefix+r`.
+
+Needs `jq`. Run it again after moving the checkout.
+
+To leave: `herdr plugin unlink tmuxrdr.tmux-mode`, remove the two links, and
+move `config.toml.pre-tmuxrdr` back if you want herdr's old config.
+
+## Test
+
+```sh
+tmuxrdr/scripts/test-e2e
+```
+
+About a minute. It runs a herdr client inside a throwaway tmux server (its own
+socket, its prefix off), on a throwaway herdr session and a copy of the
+config, presses each binding, checks the effect through the herdr CLI, and
+removes everything after. Your sessions and config are not touched. `HERDR=`
+tests another binary -- a tmuxrdr build, once there is one.
+
+## Maintaining
+
+The fork is meant to follow herdr release by release with as little work as
+possible. What keeps it that way:
+
+- **One branch, `tmuxrdr`:** a herdr release tag with tmuxrdr's commits on
+  top. Remote `upstream` is herdr, fetch-only -- its push URL is disabled.
+- **Fork content stays in `tmuxrdr/`.** Upstream never touches this
+  directory, so these commits never conflict. Do not edit upstream files for
+  anything that can live here -- not even the top-level README.
+- **Code patches are one commit each, and small.** Put the logic in new
+  files; keep the lines changed in upstream's files to the hooks that call
+  it. ROADMAP.md says where each patch touches.
+- **rerere is on** in this checkout (`git config rerere.enabled true`), so a
+  conflict resolved once is resolved by itself next time.
+
+To move to a new herdr release:
+
+```sh
+tmuxrdr/scripts/sync-upstream          # or: sync-upstream v0.9.4
+tmuxrdr/scripts/test-e2e
+```
+
+`sync-upstream` keeps the branch as it was under `tmuxrdr-on-<old tag>`; if
+something is wrong, `git switch -C tmuxrdr tmuxrdr-on-<old tag>` puts it back.
+Test against the new release: upgrade the herdr on PATH (`brew upgrade
+herdr`) while there are no code patches, or build this checkout once there
+are.
+
+## Building
+
+Not needed until the first code patch: until then, tmuxrdr runs on stock
+herdr. When it is:
+
+- herdr pins Rust 1.96.1 in `rust-toolchain.toml`. Install rustup with
+  `--no-modify-path` -- dot's shell profiles are links into a repo -- and put
+  `. "$HOME/.cargo/env"` in `~/.localenv`.
+- Fetch crates through Socket Firewall: `sfw cargo build --release`.
+- Client and server are one binary and check each other's protocol version.
+  Stop the server (`herdr server stop`) before switching, then install the
+  build as `~/.local/bin/herdr`, which comes before Homebrew's on PATH here.
+  Keep it named `herdr`: agent integrations call that name.
+- Never `herdr update` a tmuxrdr build -- it installs stock herdr over it.
+
+License: Apache-2.0, like herdr (`LICENSE` at the top of the checkout).