@danielishi/lmux 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Bratschke / SpockyMagicAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# lmux
+
+**lmux — Linux terminal multiplexer for Claude Code agent orchestration. The Linux peer of cmux (macOS) and wmux (Windows).**
+
+lmux is a thin CLI wrapper around `tmux` that exposes a stable, scriptable interface for orchestrating multiple Claude Code agents in panes, splits, and workspaces. It mirrors the cmux API one-to-one so the same orchestration code, skills, and agent definitions work unchanged across all three platforms.
+
+## Platform ecosystem
+
+| Platform | Tool | Backend | Install |
+|---|---|---|---|
+| Windows | [wmux](https://github.com/openwong2kim/wmux) | Electron + ConPTY | Installer |
+| macOS | [cmux](https://github.com/manaflow-ai/cmux) | Swift / AppKit | Homebrew |
+| **Linux** | **lmux** | **tmux wrapper** | **curl \| bash** |
+
+All three expose the same CLI surface (`<x>mux send`, `read-screen`, `new-split`, `tree`, `identify`, ...), so an agent skill written against one runs against all of them.
+
+## Requirements
+
+- Linux (any distribution with bash)
+- `tmux` >= 3.0
+- `bash` >= 4.0
+
+## Install
+
+Preferred (npm):
+
+```bash
+npm install -g lmux
+```
+
+Alternative (curl | bash):
+
+```bash
+curl -sL https://raw.githubusercontent.com/DanielIshi/lmux/master/install.sh | bash
+```
+
+The installer symlinks `lmux*` into `/usr/local/bin/` and verifies the install with `lmux identify`. The npm install registers the `lmux*` binaries on your `PATH` via npm's global bin directory.
+
+## Quick start
+
+```bash
+tmux new-session -d -s agents              # start a tmux session
+lmux new-split right                        # → surface:2
+lmux send --surface surface:1 "claude\n"   # launch claude in left pane
+lmux send --surface surface:2 "claude\n"   # launch claude in right pane
+lmux read-screen --surface surface:1        # read left pane output
+```
+
+## Command reference
+
+| Command | Flags | Description |
+|---|---|---|
+| `lmux send` | `--surface surface:N "text"` | Send text to pane (append `\n` for Enter) |
+| `lmux send-key` | `--surface surface:N <key>` | Send key: `return`, `ctrl+c`, `ctrl+d`, etc. |
+| `lmux read-screen` | `--surface surface:N [--scrollback] [--lines N]` | Read pane output |
+| `lmux new-split` | `right\|down` | Split pane, returns new `surface:N` |
+| `lmux close-surface` | `--surface surface:N` | Kill pane |
+| `lmux tree` | `--all --json` | JSON hierarchy of all panes |
+| `lmux identify` | — | Verify lmux (tmux) environment |
+| `lmux list-workspaces` | — | List workspaces (tmux windows) |
+| `lmux notify` | `--title T --body B` | Desktop notification |
+| `lmux-send` | `--surface surface:N "text"` | Wrapper: auto-resolves surface refs |
+| `lmux-read` | `--surface surface:N [--scrollback]` | Wrapper: auto-resolves surface refs |
+| `lmux-send-key` | `--surface surface:N <key>` | Wrapper: auto-resolves surface refs |
+| `lmux-grid` | `<rows> <cols>` | Build a rows×cols grid of panes; returns JSON array of new `surface:N` refs |
+
+See [commands/lmux.md](commands/lmux.md) for full per-command documentation and tmux equivalents.
+
+## Wrapper scripts
+
+`lmux-send`, `lmux-read`, `lmux-send-key`, and `lmux-grid` are thin convenience wrappers around the core commands. They:
+
+- Auto-resolve surface references against the active workspace (no need to spell out the full tmux target).
+- Apply newline normalization automatically.
+- Are the recommended entrypoints for agent skills and orchestration loops — the bare `lmux <verb>` form is the lower-level primitive.
+
+`lmux-grid <rows> <cols>` builds a rows×cols pane grid in the current workspace and prints a JSON array of the new `surface:N` references — convenient for spawning a swarm of agents in one call.
+
+## Newline rules (critical)
+
+Same semantics as cmux — get this wrong and your agent will type its prompt without ever pressing Enter:
+
+- **`lmux send "text"`** — sends literal text. **No Enter is pressed.**
+- **`lmux send "text\n"`** — sends text *and* Enter. Use this to submit a prompt.
+- **`lmux send-key return`** — presses Enter on its own (e.g. to dismiss a prompt).
+- Multi-line input: embed `\n` between lines; the final `\n` submits.
+- **Never** rely on a trailing space or shell behavior to submit — be explicit.
+
+## Claude Code integration
+
+lmux is designed to be driven by Claude Code agents. See the `using-lmux` skill at [`skills/using-lmux/SKILL.md`](skills/using-lmux/SKILL.md) for the canonical agent-side usage patterns, including the orchestration loop, polling cadence, and cleanup contract.
+
+For multi-agent setups (lead + worker panes, cross-server SSH panes), see [commands/lmux-team.md](commands/lmux-team.md).
+
+## Uninstall
+
+```bash
+npm rm -g lmux
+# or, if installed via curl|bash:
+sudo rm /usr/local/bin/lmux*
+```
+
+## Troubleshooting
+
+- **`lmux: command not found`** — the `lmux*` binaries are not on your `PATH`. For npm installs, check that npm's global bin directory (`npm config get prefix`/`bin`) is on `PATH`. For curl|bash installs, verify the symlinks landed in `/usr/local/bin/` and that this directory is on `PATH`.
+- **`lmux: not inside a tmux session (TMUX env var unset)`** — every lmux command (except `identify` reporting the error) must run inside a tmux session. Start one first: `tmux new -s agents`, then re-run your command from inside that session.
+- **`tmux >= 3.0 required`** — check your tmux version with `tmux -V`. Upgrade via your package manager (`apt install tmux`, `dnf install tmux`, `brew install tmux`). Distributions on older LTS lines (e.g. Ubuntu 18.04) ship 2.x and will not work — install from a backports repo or build from source.
+
+## License
+
+MIT

package/bin/lmux

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# lmux — Linux tmux wrapper with a CLI surface compatible with cmux/wmux.
+# Surface refs are formatted "surface:N" or "session:N" where N is a tmux
+# pane index. The wrapper extracts N and calls tmux with `-t N`.
+
+set -euo pipefail
+
+_die() { echo "lmux: $*" >&2; exit 2; }
+
+# Extract the trailing pane index from a surface ref like "surface:3" or "main:3".
+_surface_index() {
+  local ref="$1"
+  case "$ref" in
+    *:*) echo "${ref##*:}" ;;
+    *)   _die "invalid surface ref: $ref (expected surface:N)" ;;
+  esac
+}
+
+# Parse a flag pair "--name value" out of an arg list, echoing the value.
+# Usage: val=$(_get_flag --surface "$@")
+_get_flag() {
+  local name="$1"; shift
+  while [ $# -gt 0 ]; do
+    if [ "$1" = "$name" ]; then
+      echo "$2"
+      return 0
+    fi
+    shift
+  done
+  return 1
+}
+
+cmd_send() {
+  local surface text
+  surface=$(_get_flag --surface "$@") || _die "send: missing --surface"
+  # Last positional arg is the text payload.
+  text=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --surface) shift 2 ;;
+      *) text="$1"; shift ;;
+    esac
+  done
+  [ -z "$text" ] && _die "send: missing text"
+  local idx
+  idx=$(_surface_index "$surface")
+
+  if [[ "$text" == *'\n' ]]; then
+    local body="${text%\\n}"
+    tmux send-keys -t "$idx" "$body" Enter
+  else
+    tmux send-keys -t "$idx" "$text"
+  fi
+}
+
+cmd_send_key() {
+  local surface key
+  surface=$(_get_flag --surface "$@") || _die "send-key: missing --surface"
+  key=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --surface) shift 2 ;;
+      *) key="$1"; shift ;;
+    esac
+  done
+  [ -z "$key" ] && _die "send-key: missing key name"
+  local idx
+  idx=$(_surface_index "$surface")
+
+  local mapped
+  case "$key" in
+    return|enter)  mapped="Enter" ;;
+    escape|esc)    mapped="Escape" ;;
+    tab)           mapped="Tab" ;;
+    space)         mapped="Space" ;;
+    backspace|bs)  mapped="BSpace" ;;
+    up)            mapped="Up" ;;
+    down)          mapped="Down" ;;
+    left)          mapped="Left" ;;
+    right)         mapped="Right" ;;
+    ctrl+*)        mapped="C-${key#ctrl+}" ;;
+    alt+*)         mapped="M-${key#alt+}" ;;
+    *)             _die "send-key: unknown key '$key'" ;;
+  esac
+
+  tmux send-keys -t "$idx" "$mapped"
+}
+
+cmd_read_screen() {
+  local surface scrollback=0 lines=""
+  surface=$(_get_flag --surface "$@") || _die "read-screen: missing --surface"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --surface)     shift 2 ;;
+      --scrollback)  scrollback=1; shift ;;
+      --lines)       lines="$2"; shift 2 ;;
+      *)             shift ;;
+    esac
+  done
+  local idx
+  idx=$(_surface_index "$surface")
+
+  if [ -n "$lines" ]; then
+    tmux capture-pane -t "$idx" -p -S "-${lines}"
+  elif [ "$scrollback" = "1" ]; then
+    tmux capture-pane -t "$idx" -p -S -
+  else
+    tmux capture-pane -t "$idx" -p
+  fi
+}
+
+cmd_new_split() {
+  local dir="${1:-}"
+  local flag
+  case "$dir" in
+    right) flag="-h" ;;
+    down)  flag="-v" ;;
+    *)     _die "new-split: direction must be 'right' or 'down'" ;;
+  esac
+  tmux split-window "$flag" -P -F "surface:#{pane_index}"
+}
+
+cmd_close_surface() {
+  local surface
+  surface=$(_get_flag --surface "$@") || _die "close-surface: missing --surface"
+  local idx
+  idx=$(_surface_index "$surface")
+  tmux kill-pane -t "$idx"
+}
+
+cmd_tree() {
+  # Flags ignored beyond --all --json; the only supported mode.
+  local fmt="#{session_name}:#{window_index}:#{pane_index}:#{pane_title}"
+  if command -v jq >/dev/null 2>&1; then
+    tmux list-panes -a -F "$fmt" \
+      | jq -R 'select(length > 0) | split(":") | {session: .[0], window: (.[1]|tonumber), pane: (.[2]|tonumber), surface: ("surface:" + .[2]), title: (.[3] // "")}' \
+      | jq -s .
+  elif command -v python3 >/dev/null 2>&1; then
+    tmux list-panes -a -F "$fmt" \
+      | python3 -c "import sys,json; rows=[l.split(':',3) for l in sys.stdin.read().splitlines() if l]; print(json.dumps([{'session':r[0],'window':int(r[1]),'pane':int(r[2]),'surface':f'surface:{r[2]}','title':r[3] if len(r)>3 else ''} for r in rows]))"
+  else
+    echo "lmux tree: warning — neither jq nor python3 found, falling back to naive JSON escape (titles with special chars may break)" >&2
+    local raw
+    raw=$(tmux list-panes -a -F "$fmt")
+    printf '['
+    local first=1
+    while IFS= read -r line; do
+      [ -z "$line" ] && continue
+      IFS=':' read -r session window pane title <<<"$line"
+      [ "$first" = "1" ] || printf ','
+      first=0
+      local esc_title
+      esc_title=${title//\\/\\\\}
+      esc_title=${esc_title//\"/\\\"}
+      printf '{"session":"%s","window":%s,"pane":%s,"surface":"surface:%s","title":"%s"}' \
+        "$session" "$window" "$pane" "$pane" "$esc_title"
+    done <<<"$raw"
+    printf ']\n'
+  fi
+}
+
+cmd_identify() {
+  if [ -n "${TMUX:-}" ]; then
+    echo "tmux: ${TMUX}"
+    exit 0
+  else
+    echo "lmux: not inside a tmux session (TMUX env var unset)" >&2
+    exit 1
+  fi
+}
+
+cmd_list_workspaces() {
+  tmux list-windows -F "workspace:#{window_index} #{window_name}"
+}
+
+cmd_notify() {
+  local title="" body=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --title) title="$2"; shift 2 ;;
+      --body)  body="$2";  shift 2 ;;
+      *) shift ;;
+    esac
+  done
+  if command -v notify-send >/dev/null 2>&1; then
+    notify-send "$title" "$body"
+  else
+    echo "[lmux notify] $title: $body"
+  fi
+}
+
+main() {
+  local sub="${1:-}"
+  shift || true
+  case "$sub" in
+    send)            cmd_send "$@" ;;
+    send-key)        cmd_send_key "$@" ;;
+    read-screen)     cmd_read_screen "$@" ;;
+    new-split)       cmd_new_split "$@" ;;
+    close-surface)   cmd_close_surface "$@" ;;
+    tree)            cmd_tree "$@" ;;
+    identify)        cmd_identify "$@" ;;
+    list-workspaces) cmd_list_workspaces "$@" ;;
+    notify)          cmd_notify "$@" ;;
+    ""|-h|--help)
+      cat <<EOF
+lmux — Linux tmux wrapper (cmux/wmux-compatible CLI)
+
+Commands:
+  send --surface S:N "text\\n"
+  send-key --surface S:N <return|escape|tab|ctrl+c|...>
+  read-screen --surface S:N [--scrollback | --lines N]
+  new-split <right|down>
+  close-surface --surface S:N
+  tree --all --json
+  identify
+  list-workspaces
+  notify --title T --body B
+EOF
+      ;;
+    *) _die "unknown subcommand: $sub" ;;
+  esac
+}
+
+main "$@"

package/bin/lmux-grid

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Wrapper: lmux-grid <rows> <cols>
+# Creates an N-row x M-col grid of panes via repeated splits and emits a JSON
+# array of the resulting surface refs (the new panes only, current pane first).
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+  echo "usage: lmux-grid <rows> <cols>" >&2
+  exit 2
+fi
+
+rows="$1"; cols="$2"
+total=$((rows * cols))
+if [ "$total" -lt 1 ]; then
+  echo "[]"
+  exit 0
+fi
+
+surfaces=()
+# We need total-1 new splits to reach total panes from the current one.
+# Strategy: alternate vertical (down) and horizontal (right) splits.
+n=$((total - 1))
+i=0
+while [ "$i" -lt "$n" ]; do
+  if [ $((i % 2)) -eq 0 ]; then
+    s=$(lmux new-split right)
+  else
+    s=$(lmux new-split down)
+  fi
+  surfaces+=("$s")
+  i=$((i + 1))
+done
+
+# Apply tiled layout for evenness (best-effort; mock tmux ignores).
+tmux select-layout tiled >/dev/null 2>&1 || true
+
+# Emit JSON.
+printf '['
+first=1
+for s in "${surfaces[@]}"; do
+  [ "$first" = "1" ] || printf ','
+  first=0
+  printf '"%s"' "$s"
+done
+printf ']\n'

package/bin/lmux-read

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Wrapper: lmux-read <surface:N> [--scrollback | --lines N]
+set -euo pipefail
+if [ $# -lt 1 ]; then
+  echo "usage: lmux-read <surface:N> [--scrollback | --lines N]" >&2
+  exit 2
+fi
+surface="$1"; shift
+exec lmux read-screen --surface "$surface" "$@"

package/bin/lmux-send

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Wrapper: lmux-send <surface:N> <text>
+# Mirrors cmux-send. Just forwards to `lmux send --surface S T`.
+set -euo pipefail
+if [ $# -lt 2 ]; then
+  echo "usage: lmux-send <surface:N> <text>" >&2
+  exit 2
+fi
+surface="$1"; shift
+exec lmux send --surface "$surface" "$*"

package/bin/lmux-send-key

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Wrapper: lmux-send-key <surface:N> <key>
+set -euo pipefail
+if [ $# -lt 2 ]; then
+  echo "usage: lmux-send-key <surface:N> <key>" >&2
+  exit 2
+fi
+surface="$1"; key="$2"
+exec lmux send-key --surface "$surface" "$key"

package/commands/lmux-team.md

@@ -0,0 +1,123 @@
+# `lmux-team` — Multi-agent orchestration with lmux
+
+This guide shows how to drive multiple Claude Code agents from a single lead process using lmux. It assumes you've read [`lmux.md`](lmux.md) and understand surfaces, newline rules, and the wrapper scripts.
+
+## Creating a 2-agent session
+
+The canonical "lead + worker" layout: a left pane running the orchestrator, a right pane running a worker agent.
+
+```bash
+# 1. Start a dedicated tmux session (detached, so we can drive it from outside)
+tmux new-session -d -s agents -x 200 -y 50
+
+# 2. Confirm the root pane
+lmux identify
+# → session=agents, window=0, surface=surface:1
+
+# 3. Split right to create the worker pane
+WORKER=$(lmux new-split right)
+# → surface:2
+
+# 4. Launch claude in each pane
+lmux send --surface surface:1 "claude\n"
+lmux send --surface "$WORKER"  "claude\n"
+
+# 5. Wait for both to settle, then dispatch
+sleep 3
+lmux send --surface "$WORKER" "Read README.md and summarize it in 3 bullets.\n"
+```
+
+The lead pane is now free to receive its own prompts, monitor the worker, or spawn more splits.
+
+## The orchestration loop
+
+This is the pattern you'll use 90% of the time: dispatch a task, poll for completion, collect the result, clean up.
+
+```bash
+dispatch() {
+    local surface="$1" prompt="$2"
+    lmux send --surface "$surface" "$prompt\n"
+}
+
+wait_for_idle() {
+    # Poll until the pane stops changing for `stable_for` seconds,
+    # or until `timeout` seconds elapse.
+    local surface="$1" timeout="${2:-300}" stable_for="${3:-5}"
+    local last="" now="" stable_since=$SECONDS deadline=$((SECONDS + timeout))
+
+    while [ $SECONDS -lt $deadline ]; do
+        now=$(lmux read-screen --surface "$surface" --lines 40)
+        if [ "$now" = "$last" ]; then
+            if [ $((SECONDS - stable_since)) -ge "$stable_for" ]; then
+                return 0
+            fi
+        else
+            last="$now"
+            stable_since=$SECONDS
+        fi
+        sleep 1
+    done
+    return 1   # timed out
+}
+
+collect() {
+    local surface="$1"
+    lmux read-screen --surface "$surface" --scrollback
+}
+
+cleanup() {
+    local surface="$1"
+    lmux send-key --surface "$surface" ctrl+c   # interrupt
+    sleep 1
+    lmux send --surface "$surface" "/exit\n"    # graceful claude exit
+    sleep 1
+    lmux close-surface --surface "$surface"
+}
+
+# Usage
+WORKER=$(lmux new-split right)
+lmux send --surface "$WORKER" "claude\n"
+sleep 3
+dispatch       "$WORKER" "Summarize README.md in 3 bullets."
+wait_for_idle  "$WORKER" 180 5 || echo "Worker timed out"
+RESULT=$(collect "$WORKER")
+cleanup        "$WORKER"
+echo "$RESULT"
+```
+
+### Tuning the loop
+
+- **`stable_for`** — raise it for agents that pause mid-thought (3–10 s typical).
+- **`timeout`** — set generously; a Claude task that exceeds it is almost always stuck, not slow.
+- **Polling cadence** — 1 s is the sweet spot. Faster wastes CPU on `capture-pane`; slower delays the next dispatch.
+- **Idempotency** — always design tasks so re-dispatching is safe; transient network blips happen.
+
+## Cross-server pattern (SSH pane + lmux)
+
+To drive an agent on another machine, dedicate a pane to an SSH session and treat it like any other surface.
+
+```bash
+REMOTE=$(lmux new-split down)
+lmux send --surface "$REMOTE" "ssh user@host\n"
+sleep 2                                              # wait for login
+lmux send --surface "$REMOTE" "cd /srv/app && claude\n"
+sleep 3
+lmux send --surface "$REMOTE" "Show me the last 20 log lines.\n"
+```
+
+Caveats:
+
+- **Authentication** — use key-based SSH; don't expect the orchestrator to type passwords.
+- **Liveness** — keepalives (`ServerAliveInterval 30` in `~/.ssh/config`) prevent silent disconnects from breaking the polling loop.
+- **Detection** — `lmux read-screen` shows whatever the remote terminal renders. If the remote shell prompt looks identical to the local one, distinguish them with a unique `PS1` over SSH.
+- **Cleanup** — exit the remote shell *before* closing the surface to avoid orphaned remote processes.
+
+## Integration with the agent-mux skill
+
+The `agent-mux` skill (shared across wmux/cmux/lmux) wraps this entire pattern in a stable, declarative interface:
+
+- It picks the right backend (`wmux` / `cmux` / `lmux`) based on the host OS — your skill code doesn't change.
+- It provides ready-made helpers for dispatch / wait / collect / cleanup with sane defaults.
+- It coordinates multiple worker surfaces (fan-out / fan-in) and aggregates results.
+
+See the `using-lmux` skill (`skills/using-lmux/SKILL.md`) for the Linux-specific notes, and the `agent-mux` skill for the cross-platform orchestration API. When writing a new orchestration skill, prefer `agent-mux` over driving `lmux` directly — it's what guarantees your skill works unchanged on macOS and Windows too.

package/commands/lmux.md

@@ -0,0 +1,183 @@
+# `lmux` command reference
+
+`lmux` is a tmux-backed CLI for orchestrating Claude Code agents on Linux. It is API-compatible with `cmux` (macOS) and `wmux` (Windows) — the same flags, the same surface model, the same newline rules.
+
+## Concepts
+
+### Surface references
+
+Every pane is addressed as `surface:N`, where `N` is a stable integer assigned by lmux when the pane is created. Surfaces are scoped to the active tmux session and survive splits, layout changes, and zoom toggles.
+
+- The first/root pane of a session is `surface:1`.
+- `lmux new-split` returns the new surface ID on stdout.
+- `lmux tree --json` lists all surfaces with their parents, sizes, and TTY paths.
+
+### Control key sequences
+
+`lmux send-key` accepts symbolic names. The most common:
+
+| Name | Effect |
+|---|---|
+| `return` / `enter` | Press Enter |
+| `tab` | Press Tab |
+| `escape` / `esc` | Press Escape |
+| `space` | Press Space |
+| `backspace` | Press Backspace |
+| `up` / `down` / `left` / `right` | Arrow keys |
+| `ctrl+c` | Interrupt (SIGINT) |
+| `ctrl+d` | EOF / exit |
+| `ctrl+l` | Clear screen |
+| `ctrl+z` | Suspend |
+| `pageup` / `pagedown` | Page navigation |
+
+Compound modifiers use `+`: `ctrl+a`, `alt+f`, `shift+tab`.
+
+### Newline handling
+
+This is the single most common source of "agent hung" bugs. Internalize it.
+
+- `lmux send "hello"` — types `hello`. **No Enter.**
+- `lmux send "hello\n"` — types `hello` *and* presses Enter.
+- `lmux send-key return` — presses Enter without typing anything.
+- `lmux send "line1\nline2\n"` — types two lines and submits.
+
+The wrappers (`lmux-send`, `lmux-read`, `lmux-send-key`) follow the same rules.
+
+---
+
+## Commands
+
+### `lmux send`
+
+Send literal text to a pane.
+
+```
+lmux send --surface surface:N "text"
+```
+
+- **Flags:**
+  - `--surface surface:N` (required) — target pane
+  - `"text"` (positional) — payload; `\n` is interpreted as Enter
+- **Example:**
+  ```
+  lmux send --surface surface:2 "echo hello\n"
+  ```
+- **tmux equivalent:** `tmux send-keys -t <target> "echo hello" Enter`
+
+### `lmux send-key`
+
+Press a named key or key combo.
+
+```
+lmux send-key --surface surface:N <key>
+```
+
+- **Flags:**
+  - `--surface surface:N` (required)
+  - `<key>` (positional) — see Control key sequences above
+- **Example:**
+  ```
+  lmux send-key --surface surface:1 ctrl+c
+  ```
+- **tmux equivalent:** `tmux send-keys -t <target> C-c`
+
+### `lmux read-screen`
+
+Read the current visible pane buffer.
+
+```
+lmux read-screen --surface surface:N [--scrollback] [--lines N]
+```
+
+- **Flags:**
+  - `--surface surface:N` (required)
+  - `--scrollback` — include history above the visible region
+  - `--lines N` — limit output to the last N lines
+- **Example:**
+  ```
+  lmux read-screen --surface surface:2 --lines 50
+  ```
+- **tmux equivalent:** `tmux capture-pane -p -t <target> [-S -]`
+
+### `lmux new-split`
+
+Split the current (or specified) pane and return the new surface ID.
+
+```
+lmux new-split right|down [--surface surface:N]
+```
+
+- **Args:**
+  - `right` — vertical split (new pane on the right)
+  - `down` — horizontal split (new pane below)
+- **Output:** the new `surface:N` on stdout
+- **Example:**
+  ```
+  NEW=$(lmux new-split right)
+  lmux send --surface "$NEW" "claude\n"
+  ```
+- **tmux equivalent:** `tmux split-window -h` / `-v`
+
+### `lmux close-surface`
+
+Kill a pane.
+
+```
+lmux close-surface --surface surface:N
+```
+
+- **tmux equivalent:** `tmux kill-pane -t <target>`
+
+### `lmux tree`
+
+Dump the pane hierarchy.
+
+```
+lmux tree [--all] [--json]
+```
+
+- **Flags:**
+  - `--all` — include every workspace (tmux window), not just the active one
+  - `--json` — emit machine-readable JSON
+- **Example:**
+  ```
+  lmux tree --all --json | jq '.workspaces[].surfaces[].id'
+  ```
+
+### `lmux identify`
+
+Verify lmux is functional in the current environment. Prints the lmux version, tmux version, active session/window/pane, and exits non-zero if anything is off.
+
+```
+lmux identify
+```
+
+### `lmux list-workspaces`
+
+List workspaces (tmux windows) in the active session.
+
+```
+lmux list-workspaces
+```
+
+- **tmux equivalent:** `tmux list-windows`
+
+### `lmux notify`
+
+Fire a desktop notification (best-effort; uses `notify-send` if available).
+
+```
+lmux notify --title "Build done" --body "All tests passed"
+```
+
+---
+
+## Wrapper scripts
+
+`lmux-send`, `lmux-read`, `lmux-send-key` are the recommended entrypoints for agents. They mirror the bare verbs but:
+
+- Auto-resolve `surface:N` against the active workspace (no need to pass session/window).
+- Normalize newlines.
+- Emit the same exit codes as the underlying commands.
+
+Use the wrappers in skills and orchestration loops; use the bare verbs only when you need precise control over a non-active workspace.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@danielishi/lmux",
+  "version": "0.1.1",
+  "description": "Linux terminal multiplexer companion for Claude Code agents — drop-in API equivalent of cmux (macOS) and wmux (Windows)",
+  "bin": {
+    "lmux": "./bin/lmux",
+    "lmux-send": "./bin/lmux-send",
+    "lmux-read": "./bin/lmux-read",
+    "lmux-send-key": "./bin/lmux-send-key",
+    "lmux-grid": "./bin/lmux-grid"
+  },
+  "scripts": {
+    "postinstall": "node -e \"const { execSync } = require('child_process'); try { execSync('tmux -V', { stdio: 'ignore' }); } catch { console.warn('[lmux] WARNING: tmux not found on PATH. Install it (apt/dnf/brew install tmux) for lmux to work.'); }\"",
+    "test": "echo 'Tests use bats — run: bats tests/'"
+  },
+  "files": ["bin/", "README.md", "LICENSE", "commands/", "skills/"],
+  "os": ["linux", "darwin"],
+  "engines": { "node": ">=14" },
+  "keywords": ["claude-code", "tmux", "ai-agents", "terminal-multiplexer", "cmux", "wmux", "agent-orchestration"],
+  "author": "Daniel Bratschke",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DanielIshi/lmux.git"
+  },
+  "homepage": "https://github.com/DanielIshi/lmux#readme",
+  "bugs": { "url": "https://github.com/DanielIshi/lmux/issues" }
+}

package/skills/using-lmux/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: using-lmux
+description: >
+  Use lmux to orchestrate Claude Code agents in tmux panes on Linux.
+  Trigger on: lmux operations, coordinating agents in tmux, Linux multi-agent
+  sessions, lmux send/read/split commands.
+allowed-tools:
+  - Bash
+---
+
+# Using lmux
+
+`lmux` is a thin tmux wrapper that mirrors the `cmux` CLI so Claude Code can drive panes on
+Linux servers exactly the same way it drives them on macOS. Use this skill whenever you need
+to spin up, talk to, or read from agents running in tmux.
+
+## Prerequisites
+
+- `tmux >= 3.2` installed on the host.
+- `lmux` on `$PATH` (the `lmux`, `lmux-send`, `lmux-read`, `lmux-send-key` wrappers).
+- Running inside a tmux session (`$TMUX` set) for surface refs to resolve.
+
+If `$TMUX` is unset, start one first:
+```bash
+lmux new-session -s agents
+```
+
+## Surface References
+
+A "surface" is a tmux pane addressed as `session:window.pane` or shorthand `session:N` (pane
+index inside the active window). Discover them with:
+
+```bash
+lmux tree --all --json
+```
+
+Returns a JSON tree of sessions → windows → panes with their surface refs and current
+command. Use this to pick a target before sending input.
+
+## Core Commands
+
+### List
+
+```bash
+lmux list-workspaces            # all tmux sessions
+lmux tree --all --json          # full hierarchy as JSON
+```
+
+### Split / new pane
+
+```bash
+lmux new-split right            # split current pane to the right
+lmux new-split down             # split downwards
+lmux new-session -s mywork      # brand-new session
+```
+
+### Send a command
+
+`lmux-send` writes literal text to a pane. **You must include the trailing `\n`** — without
+it the shell will not execute the line.
+
+```bash
+lmux-send --surface agents:1 "ls -la\n"
+lmux-send --surface agents:2 "claude --print 'summarize ./README.md'\n"
+```
+
+### Read pane output
+
+```bash
+lmux-read --surface agents:1            # current visible buffer
+lmux-read --surface agents:1 --lines 200  # last 200 lines of scrollback
+```
+
+### Send a key
+
+For control keys and special keys, use `lmux-send-key` (not `lmux-send`):
+
+```bash
+lmux-send-key --surface agents:1 return
+lmux-send-key --surface agents:1 c-c       # Ctrl-C
+lmux-send-key --surface agents:1 c-d       # Ctrl-D (EOF / exit)
+```
+
+## Orchestration Pattern
+
+A typical multi-agent run looks like this:
+
+1. **Bootstrap panes.** One `lmux new-split` per agent; label by setting the pane title:
+   ```bash
+   lmux-send --surface agents:2 $'printf "\\033]2;researcher\\007"\n'
+   ```
+2. **Dispatch.** Send each agent a one-shot Claude invocation wrapped in markers so output
+   capture is deterministic:
+   ```bash
+   lmux-send --surface agents:2 \
+     "echo '=== START r1 ===' && claude --print 'task A' && echo '=== END r1 ==='\n"
+   ```
+3. **Poll.** Loop on `lmux-read` every ~2 seconds; stop when `=== END r1 ===` appears or you
+   hit a timeout.
+4. **Collect.** Slice the buffer between the START/END markers, strip ANSI, hand the result
+   back to the orchestrator.
+5. **Aggregate.** Merge per-pane results into a single summary for the user.
+
+## Newline & Quoting Rules
+
+- `lmux-send` does **not** add a newline. Always end commands with `\n`.
+- Use double quotes around the payload so `\n` is interpreted by the shell.
+- For payloads that contain literal `$` or backticks, prefer single quotes and embed `\n` via
+  `$'...\n'` (Bash ANSI-C quoting):
+  ```bash
+  lmux-send --surface agents:1 $'echo "$HOME"\n'
+  ```
+- `lmux-send-key` takes a key name (e.g. `return`, `c-c`, `tab`, `up`), not raw text.
+
+## Examples
+
+### Two parallel researchers
+
+```bash
+lmux new-split right
+lmux new-split down
+# pane indices are now agents:1 (orchestrator), agents:2, agents:3
+
+lmux-send --surface agents:2 \
+  "echo '=== START a ===' && claude --print 'summarize repo X' && echo '=== END a ==='\n"
+lmux-send --surface agents:3 \
+  "echo '=== START b ===' && claude --print 'summarize repo Y' && echo '=== END b ==='\n"
+
+# Poll
+for pane in agents:2 agents:3; do
+  until lmux-read --surface "$pane" | grep -q "=== END "; do sleep 2; done
+done
+
+# Collect
+lmux-read --surface agents:2 --lines 500 \
+  | sed -n '/=== START a ===/,/=== END a ===/p'
+```
+
+### Cancel a runaway agent
+
+```bash
+lmux-send-key --surface agents:2 c-c
+```
+
+### Tear down a session
+
+```bash
+lmux-send-key --surface agents:1 c-d   # exit shell in pane 1
+# or, kill the whole session:
+tmux kill-session -t agents
+```
+
+## Tips
+
+- Keep one orchestrator pane that runs `claude` interactively and lets it drive the rest via
+  these commands. It scales much better than juggling sessions by hand.
+- Always wrap fan-out work in START/END markers. Scrollback-based completion detection
+  without markers is fragile.
+- `lmux tree --all --json` is cheap — re-run it whenever pane indices might have shifted
+  (e.g. after a `kill-pane`).
+- For cross-server work, run lmux inside a tmux session on the remote host and drive it over
+  SSH; the surface refs are local to that host's tmux server.