muxr 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a22c29848cc6a0454f9be515cbc0f654537e37f9fbde37902f55dd34c103ce21
-  data.tar.gz: b96e180cc3750f1f0d3f72fc822669acaf68cc33c65b312029664b36981794cb
+  metadata.gz: 0f553caf555f455f8c89689ed8ef73de3158467171551f177a27009363055091
+  data.tar.gz: b26779047961944af58a74593773b876af42c4e512ed956e0c7cb7a9becead99
 SHA512:
-  metadata.gz: 9139072cdc6e55e0ab94c7144d492858cdb3fa75bf59f5009b925d7f4e6659d8228f64987aba7c08fdff119dbcbb480511969cc64c0904e96a3ae95cb8456ddc
-  data.tar.gz: 77028f21adf1d5a7710f952af3dfc0621223b4aa0cbb70ff15436c54e797d8d3809885b50d31a71c5f417afaae2bb153bbf149379110813beeb23ba716cefe25
+  metadata.gz: 4ab01bd3c63531f1e9b64aecb2532e79eecc4e3736d7970cb1040ee5e9db0fd9f316b06358f1bd758bc93d413ed5e70d17d884ce85ebb4f593cc4d556b180ee3
+  data.tar.gz: '09abcbbdec950405196dc6015dc00c201c7200c890db0de49ba0c3b703923b78125c0cce458b950c1921970e569e9eb209b1ffd1930ee9cda83ebeb8f88d8afa'

data/CHANGELOG.md

@@ -6,6 +6,69 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-05-13
+
+### Added
+- MCP (Model Context Protocol) integration so Claude Code can drive a
+  muxr session as a tool. A second listener at
+  `~/.muxr/sockets/<name>.ctrl.sock` accepts multiple concurrent NDJSON
+  clients and exposes read-only and mutating methods over a small
+  JSON-RPC surface (`session.get`, `panes.list`, `pane.read`,
+  `pane.send_input`, `pane.run`, `pane.subscribe`, `layout.set`,
+  `drawer.*`, etc.). The control socket does not interfere with TTY
+  attach — programmatic clients never count as "attached", so a Claude
+  session and a human can use the multiplexer concurrently.
+- `pane.run` waits for the PTY to go idle before responding. Sends the
+  input, polls for output, and returns once no bytes have arrived for
+  `idle_ms` (default 500). Server-side idle detection avoids the
+  send-then-poll race that plagues naive client-side automation.
+- Stable per-pane ids: every pane carries a 6-hex `SecureRandom` id that
+  survives splits, kills, promote_to_master, detach/reattach, and
+  cold-restart from the session JSON. The status bar now reads
+  `#1 a3f9b2` so users see both the slot (positional, what `Ctrl-a 1`
+  targets) and the id (stable, what the MCP client should reference).
+- `bin/muxr-mcp` — standalone MCP-over-stdio bridge that translates
+  Claude Code tool calls into NDJSON requests on the control socket.
+  Auto-detects the target session from `MUXR_CONTROL_SOCKET` or
+  `MUXR_SESSION` env vars.
+- `Ctrl-a C` (also `:claude`) opens a drawer whose shell is `claude`,
+  with `MUXR_SESSION`, `MUXR_CONTROL_SOCKET`, `MUXR_FOCUSED_PANE`, and
+  `MUXR_DRAWER_SELF=1` injected into its environment. The bridge picks
+  those up automatically; the human gets a Quake-style Claude Code
+  overlay that already knows what session it's in. The
+  `MUXR_DRAWER_SELF` guard makes the bridge refuse `drawer.*` methods
+  so a claude drawer can't recurse into its own PTY.
+- Private panes (`Ctrl-a P` / `:private`) hide a pane from programmatic
+  callers: `panes.list` strips cwd/rows/cols, and `pane.read`,
+  `pane.send_input`, `pane.run`, `pane.subscribe`, and `pane.kill`
+  refuse with an error message pointing the human at `Ctrl-a P` to
+  expose it. The flag is persisted in session JSON, shown as `[P]` in
+  the status bar, and intentionally one-way — there is no control
+  method to flip it.
+- Named keys on `pane.send_input`, `pane.run`, and `drawer.send_input`.
+  A `keys` array accepts vim-style `<name>` tokens (`<esc>`, `<c-c>`,
+  `<cr>`, arrows, etc.) interleaved with literal text, so MCP callers
+  no longer have to remember that Escape is `"\e"` and Ctrl-C is
+  `"\x03"`. Bracketed-paste wrapping still applies to literal segments
+  only.
+- Skill bundle at `skills/muxr-control/SKILL.md` teaching Claude how to
+  drive muxr via the MCP. Installable via `muxr --install-skill`, which
+  copies the skill into `~/.claude/skills/muxr-control` (survives
+  `gem update`) and prints the `claude mcp add` registration line.
+
+### Fixed
+- Honor DSR cursor-position queries (`\e[5n`, `\e[6n`). The Terminal
+  emulator now buffers a `\e[0n` OK reply or a `\e[<row>;<col>R` CPR
+  reply into a pending-replies queue; the Pane drains it back through
+  the PTY input side after each feed. AWS CLI and other programs that
+  probe geometry this way no longer log "your terminal doesn't support
+  cursor position requests (CPR)" and fall back to a degraded mode.
+- Drawer height now has a floor of 16 rows. The old 35%-of-screen rule
+  degraded badly on short terminals — a 24-row terminal gave only ~8
+  rows of drawer, barely enough for one prompt and a few lines of
+  output. The 35% growth still applies above the floor, so tall
+  terminals are unaffected.
+
 ## [0.1.4] - 2026-05-13
 
 ### Fixed
@@ -108,7 +171,8 @@ Initial release.
   boundaries.
 - Renderer that composes one frame and diff-emits ANSI to STDOUT.
 
-[Unreleased]: https://github.com/roelbondoc/muxr/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/roelbondoc/muxr/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/roelbondoc/muxr/releases/tag/v0.1.5
 [0.1.4]: https://github.com/roelbondoc/muxr/releases/tag/v0.1.4
 [0.1.3]: https://github.com/roelbondoc/muxr/releases/tag/v0.1.3
 [0.1.2]: https://github.com/roelbondoc/muxr/releases/tag/v0.1.2

data/bin/muxr

@@ -18,6 +18,65 @@ if ARGV.include?("-l") || ARGV.include?("--list")
   exit 0
 end
 
+if ARGV.include?("--install-skill")
+  # Copies skills/muxr-control into ~/.claude/skills/muxr-control so the
+  # claude CLI loads it from anywhere. We *copy* rather than symlink so the
+  # install survives a RubyGems upgrade (which deletes the old versioned
+  # gem path that a symlink would have pointed at). Idempotent: re-running
+  # this after a `gem update muxr` is the supported way to refresh the
+  # skill content.
+  src = File.expand_path("../skills/muxr-control", __dir__)
+  unless File.directory?(src)
+    $stderr.puts "muxr: skill source not found at #{src} (was the gem packaged without skills/?)"
+    exit 1
+  end
+  claude_skills = File.expand_path("~/.claude/skills")
+  dst = File.join(claude_skills, "muxr-control")
+  FileUtils.mkdir_p(claude_skills)
+  # Wipe any prior install — symlink (from older dev installs) or directory.
+  if File.symlink?(dst) || File.exist?(dst)
+    FileUtils.rm_rf(dst)
+  end
+  FileUtils.mkdir_p(dst)
+  FileUtils.cp_r(File.join(src, "."), dst)
+
+  # Pick the most stable absolute path we can point claude's mcp config at:
+  #
+  #  - Installed gem: $GEM_HOME/bin/muxr-mcp is a wrapper bin stub that
+  #    survives version upgrades (RubyGems repoints it on `gem update`).
+  #    Always prefer it when present.
+  #  - Source checkout: no bin stub exists; fall back to the script that
+  #    sits next to the running `muxr` binary.
+  bin_stub = File.join(Gem.bindir, "muxr-mcp") rescue nil
+  bridge = (bin_stub && File.exist?(bin_stub)) ? bin_stub : File.expand_path("muxr-mcp", __dir__)
+  puts <<~MSG
+    ✓ Copied skill to: #{dst}
+      (source: #{src})
+
+    Re-run `muxr --install-skill` after `gem update muxr` to refresh the
+    skill contents.
+
+    Next, register the muxr MCP bridge with Claude Code at USER scope
+    (so every claude session sees it, not just ones started from your
+    home directory):
+
+        claude mcp add muxr #{bridge} --scope user
+
+    If you omit `--scope user`, `claude mcp add` defaults to local scope
+    and the MCP is only loaded when claude starts from your current cwd —
+    a common first-run gotcha.
+
+    If your gem bin directory is on $PATH, `muxr-mcp` works as a bare name too:
+
+        claude mcp add muxr muxr-mcp --scope user
+
+    Then restart any running Claude Code sessions so they pick up the new
+    config, and launch claude from inside a muxr drawer (Ctrl-a C) — the
+    bridge auto-detects the session via MUXR_SESSION / MUXR_CONTROL_SOCKET.
+  MSG
+  exit 0
+end
+
 if ARGV.include?("-h") || ARGV.include?("--help")
   puts <<~USAGE
     muxr #{Muxr::VERSION} — a tiling terminal multiplexer
@@ -27,6 +86,7 @@ if ARGV.include?("-h") || ARGV.include?("--help")
       muxr <name>          attach (or start) the named session
       muxr -s <name>       same as above
       muxr --list          list running sessions and exit
+      muxr --install-skill symlink the MCP skill into ~/.claude/skills and exit
       muxr --version       print version and exit
       muxr --help          this help
 
@@ -35,6 +95,7 @@ if ARGV.include?("-h") || ARGV.include?("--help")
       C-a a   toggle last pane    C-a 1..9    jump to pane by number
       C-a k   close pane          C-a Tab     cycle layout
       C-a ~   toggle drawer       C-a Enter   promote to master
+      C-a C   Claude drawer       (MCP-aware; needs `muxr --install-skill` + bridge configured)
       C-a :   command prompt      C-a ?       toggle help
       C-a d   detach (server stays running)
       C-a q   kill session (with y/n confirmation)

data/bin/muxr-mcp

@@ -0,0 +1,412 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# muxr-mcp — Model Context Protocol bridge for muxr.
+#
+# Speaks MCP JSON-RPC over stdio (one JSON object per line) and translates
+# tool calls into NDJSON requests on the muxr control socket at
+# ~/.muxr/sockets/<name>.ctrl.sock. Connection target is determined by:
+#
+#   1. $MUXR_CONTROL_SOCKET (absolute path) — exact override
+#   2. $MUXR_SESSION (session name)         — resolved to standard path
+#   3. otherwise: error
+#
+# Both env vars are injected automatically when claude is launched from the
+# muxr Claude-drawer (Ctrl-a C), so end users almost never set them by hand.
+#
+# Typical claude-code mcp config:
+#
+#   {
+#     "mcpServers": {
+#       "muxr": { "command": "/abs/path/to/bin/muxr-mcp" }
+#     }
+#   }
+
+require "json"
+require "socket"
+
+class MuxrMcpBridge
+  PROTOCOL_VERSION = "2024-11-05"  # MCP protocol revision the bridge speaks.
+  SERVER_NAME      = "muxr-mcp"
+  SERVER_VERSION   = "0.1.0"
+
+  # Map each exposed MCP tool name to the underlying muxr control method.
+  # The tool surface is intentionally a flat one-to-one — every method shipped
+  # by the control server gets a tool. Names are snake_case and prefixed with
+  # `muxr_` so they sit cleanly in Claude's tool list alongside other servers.
+  TOOL_TO_MUXR_METHOD = {
+    "muxr_ping"             => "ping",
+    "muxr_session_get"      => "session.get",
+    "muxr_session_save"     => "session.save",
+    "muxr_panes_list"       => "panes.list",
+    "muxr_pane_read"        => "pane.read",
+    "muxr_pane_send_input"  => "pane.send_input",
+    "muxr_pane_focus"       => "pane.focus",
+    "muxr_pane_new"         => "pane.new",
+    "muxr_pane_kill"        => "pane.kill",
+    "muxr_pane_promote"     => "pane.promote",
+    "muxr_pane_run"         => "pane.run",
+    "muxr_layout_set"       => "layout.set",
+    "muxr_layout_cycle"     => "layout.cycle",
+    "muxr_drawer_toggle"    => "drawer.toggle",
+    "muxr_drawer_show"      => "drawer.show",
+    "muxr_drawer_hide"      => "drawer.hide",
+    "muxr_drawer_reset"     => "drawer.reset",
+    "muxr_drawer_send_input"=> "drawer.send_input",
+    "muxr_drawer_read"      => "drawer.read"
+  }.freeze
+
+  # Reusable JSON schema fragment: pane identifier. We expose only the
+  # string-id form via MCP (slot-as-integer would have required `oneOf`,
+  # which the Anthropic tool-use API doesn't accept). The id-only contract
+  # matches the skill's "always use ids" guidance anyway. Callers get the
+  # ids from muxr_panes_list.
+  PANE_REF = {
+    "type" => "string",
+    "description" => "Stable 6-hex pane id from muxr_panes_list (e.g. \"a3f9b2\"). Ids survive splits, kills, and promote_to_master — always prefer them over the positional slot numbers shown in the status bar."
+  }.freeze
+
+  TOOL_SCHEMAS = [
+    {
+      "name" => "muxr_session_get",
+      "description" => "Get a summary of the muxr session: name, layout, focused pane, drawer visibility, dimensions, pane count. Call this first to ground yourself in the current state.",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_panes_list",
+      "description" => "List every pane with its stable id, 1-based slot number, focused/master flags, cwd, and grid dimensions. Always reference panes by id in subsequent calls (slots shift on split/kill).",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_pane_read",
+      "description" => "Read the currently-visible terminal contents of a pane as plain text (one row per line, trailing whitespace trimmed). Cheap and idempotent.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => { "pane" => PANE_REF },
+        "required" => ["pane"],
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_pane_send_input",
+      "description" => "Send raw bytes to a pane's PTY without waiting. For full commands prefer muxr_pane_run, which sends + waits for output to settle. Set bracketed=true when sending multi-line text into an editor or REPL. When the sequence needs any special key (Escape, Enter-as-terminator, arrows, Ctrl-*), use `keys` instead of `data` — sending \"\\n\" or \"\\e\" through `data` is a footgun that easily leaves vim in insert mode.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "pane" => PANE_REF,
+          "data" => { "type" => "string", "description" => "Literal bytes to send, sent exactly as-is (no \\r appended). Lower-level than `keys` — use `keys` whenever any named special key is involved. Mutually exclusive with `keys`." },
+          "keys" => {
+            "type" => "array",
+            "items" => { "type" => "string" },
+            "description" => "Mixed array of literal text and vim-style named keys. Each element is either literal text or a single `<name>`. Supported names (case-insensitive): <esc>, <enter>/<cr>, <tab>, <s-tab>, <bs>, <space>, <up>/<down>/<left>/<right>, <home>, <end>, <pageup>, <pagedown>, <c-a>..<c-z>, <f1>..<f12>. Mutually exclusive with `data`. Example for vim open-paste-save: [\"G\", \"o\", \"hello world\", \"<esc>\", \":w\", \"<enter>\"]."
+          },
+          "bracketed" => { "type" => "boolean", "description" => "Wrap literal text in bracketed-paste markers (\\e[200~ … \\e[201~). Named keys in `keys` are never bracketed." }
+        },
+        "required" => ["pane"],
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_pane_run",
+      "description" => "Send input to a pane and wait for the PTY to go idle before returning. The killer tool for driving shells: returns the pane's full visible text after the command settles, plus a timed_out flag. By default appends \\r and waits 500ms of idle. Bump idle_ms to ~800 for bursty commands (test runners) or timeout_ms for long builds. When the sequence needs any special key (Escape, arrows, Ctrl-*), use `keys` instead of `input`.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "pane"        => PANE_REF,
+          "input"       => { "type" => "string", "description" => "Command text. Omit/empty to just wait. Use `keys` instead when any named special key is needed. Mutually exclusive with `keys`." },
+          "keys"        => {
+            "type" => "array",
+            "items" => { "type" => "string" },
+            "description" => "Mixed array of literal text and vim-style named keys (see muxr_pane_send_input for the full list). Preferred over `input` whenever Escape/arrows/Ctrl-* are involved. Mutually exclusive with `input`."
+          },
+          "append_enter"=> { "type" => "boolean", "description" => "Append \\r after input/keys (default true)." },
+          "bracketed"   => { "type" => "boolean", "description" => "Wrap literal text in bracketed-paste markers (default false). Named keys in `keys` are never bracketed." },
+          "idle_ms"     => { "type" => "integer", "minimum" => 50, "maximum" => 60000, "description" => "Idle window before considering the command settled. Default 500." },
+          "timeout_ms"  => { "type" => "integer", "minimum" => 100, "maximum" => 300000, "description" => "Absolute timeout for the wait. Default 30000." }
+        },
+        "required" => ["pane"],
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_pane_focus",
+      "description" => "Focus a pane (moves the human's cursor to it). Mostly used to set up state before the human takes over.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => { "pane" => PANE_REF },
+        "required" => ["pane"],
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_pane_new",
+      "description" => "Create a new pane, optionally in a specific cwd. Returns the new pane's id and slot. Use sparingly — the human usually controls layout.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "cwd" => { "type" => "string", "description" => "Working directory for the new shell. Defaults to the focused pane's cwd." }
+        },
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_pane_kill",
+      "description" => "Close a pane. Destructive — only call when the user has named the specific pane to kill.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => { "pane" => PANE_REF },
+        "required" => ["pane"],
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_pane_promote",
+      "description" => "Promote a pane to the master slot (position 0). Useful for setting up a tall-layout focal pane.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => { "pane" => PANE_REF },
+        "required" => ["pane"],
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_layout_set",
+      "description" => "Switch to a specific layout: tall, grid, or monocle.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => { "layout" => { "type" => "string", "enum" => ["tall", "grid", "monocle"] } },
+        "required" => ["layout"],
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_layout_cycle",
+      "description" => "Cycle to the next layout (tall → grid → monocle → tall).",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_drawer_toggle",
+      "description" => "Toggle the persistent Quake-style drawer overlay.",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_drawer_show",
+      "description" => "Show the drawer if it's hidden.",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_drawer_hide",
+      "description" => "Hide the drawer (its shell keeps running).",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_drawer_reset",
+      "description" => "Tear down the drawer's shell process. Next show recreates it fresh.",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_drawer_read",
+      "description" => "Read the drawer pane's current text (works even when hidden — the PTY survives).",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_drawer_send_input",
+      "description" => "Send bytes to the drawer pane. When the sequence needs any special key (Escape, Enter-as-terminator, arrows, Ctrl-*), use `keys` instead of `data`.",
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "data" => { "type" => "string", "description" => "Literal bytes. Mutually exclusive with `keys`." },
+          "keys" => {
+            "type" => "array",
+            "items" => { "type" => "string" },
+            "description" => "Mixed literal text and vim-style named keys (see muxr_pane_send_input for the full list). Mutually exclusive with `data`."
+          },
+          "bracketed" => { "type" => "boolean", "description" => "Wrap literal text in bracketed-paste markers. Named keys in `keys` are never bracketed." }
+        },
+        "additionalProperties" => false
+      }
+    },
+    {
+      "name" => "muxr_session_save",
+      "description" => "Persist the structural session (layout, indices, cwds, drawer state) to ~/.muxr/sessions/<name>.json. Shell history is not saved.",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    },
+    {
+      "name" => "muxr_ping",
+      "description" => "Health check — returns {pong: true} if the muxr server is responsive.",
+      "inputSchema" => { "type" => "object", "properties" => {}, "additionalProperties" => false }
+    }
+  ].freeze
+
+  def initialize
+    @socket = nil
+    @next_request_id = 0
+    @read_buffer = +""
+    @in_drawer = ENV["MUXR_DRAWER_SELF"] == "1"
+  end
+
+  def run
+    connect_to_muxr
+    loop do
+      line = $stdin.gets
+      break if line.nil?
+      handle_message(line.chomp)
+    end
+  rescue Interrupt
+    # graceful exit
+  ensure
+    @socket&.close
+  end
+
+  private
+
+  def handle_message(line)
+    return if line.empty?
+    msg = JSON.parse(line)
+  rescue JSON::ParserError
+    return  # silently drop unparsable input — stdio is best-effort
+  else
+    id = msg["id"]
+    method = msg["method"]
+    params = msg["params"] || {}
+
+    case method
+    when "initialize"
+      respond(id, {
+        "protocolVersion" => PROTOCOL_VERSION,
+        "capabilities"    => { "tools" => {} },
+        "serverInfo"      => { "name" => SERVER_NAME, "version" => SERVER_VERSION }
+      })
+    when "initialized", "notifications/initialized"
+      # notification, no reply
+    when "tools/list"
+      respond(id, { "tools" => TOOL_SCHEMAS })
+    when "tools/call"
+      handle_tool_call(id, params)
+    when "ping"
+      respond(id, {})
+    when nil
+      # bare notification or invalid — ignore
+    else
+      respond_error(id, -32601, "Method not found: #{method}") if id
+    end
+  end
+
+  def handle_tool_call(id, params)
+    tool_name = params["name"].to_s
+    args = params["arguments"] || {}
+
+    muxr_method = TOOL_TO_MUXR_METHOD[tool_name]
+    if muxr_method.nil?
+      respond_tool_error(id, "Unknown tool: #{tool_name}")
+      return
+    end
+
+    # When the bridge is running inside the muxr drawer itself, calling any
+    # drawer.* method would either recurse into our own pty or yank the
+    # drawer out from under us. Refuse those instead.
+    if @in_drawer && muxr_method.start_with?("drawer.")
+      respond_tool_error(id, "drawer.* methods are unavailable from inside the drawer (MUXR_DRAWER_SELF=1).")
+      return
+    end
+
+    response = send_muxr_request(muxr_method, args)
+    if response.nil?
+      respond_tool_error(id, "muxr server closed the connection")
+    elsif response["error"]
+      err = response["error"]
+      respond_tool_error(id, "muxr error #{err["code"]}: #{err["message"]}")
+    else
+      result = response["result"]
+      respond(id, {
+        "content" => [{ "type" => "text", "text" => JSON.pretty_generate(result) }]
+      })
+    end
+  rescue StandardError => e
+    respond_tool_error(id, "#{e.class}: #{e.message}")
+  end
+
+  # Send one NDJSON request to the muxr control socket and block until the
+  # response with the matching id arrives. Server-pushed events (no id, or
+  # id mismatch) are silently dropped — the v1 bridge doesn't forward them.
+  def send_muxr_request(method, params)
+    @next_request_id += 1
+    rid = @next_request_id
+    payload = JSON.generate({ "id" => rid, "method" => method, "params" => params }) + "\n"
+    @socket.write(payload)
+
+    loop do
+      line = read_muxr_line
+      return nil unless line  # EOF
+      msg = JSON.parse(line)
+      next unless msg["id"] == rid
+      return msg
+    end
+  end
+
+  # Line-oriented read on the muxr socket. Reads in chunks and emits one
+  # JSON line at a time as they accumulate in @read_buffer.
+  def read_muxr_line
+    loop do
+      nl = @read_buffer.index("\n")
+      if nl
+        line = @read_buffer.slice!(0..nl)
+        return line.chomp
+      end
+      chunk = @socket.readpartial(64 * 1024)
+      @read_buffer << chunk
+    end
+  rescue EOFError, IOError
+    nil
+  end
+
+  def connect_to_muxr
+    path = ENV["MUXR_CONTROL_SOCKET"] || derive_socket_from_session
+    if path.nil? || path.empty?
+      die("set MUXR_CONTROL_SOCKET to the path of the muxr control socket, " \
+          "or MUXR_SESSION to the session name (the drawer-launched claude sets these for you).")
+    end
+    unless File.exist?(path)
+      die("muxr control socket not found at #{path} — is the server running? " \
+          "Start it with `muxr <session>`.")
+    end
+    @socket = UNIXSocket.new(path)
+  end
+
+  def derive_socket_from_session
+    name = ENV["MUXR_SESSION"]
+    return nil unless name && !name.empty?
+    File.join(Dir.home, ".muxr", "sockets", "#{name}.ctrl.sock")
+  end
+
+  # ---- JSON-RPC plumbing ----
+
+  def respond(id, result)
+    return if id.nil?
+    write_message({ "jsonrpc" => "2.0", "id" => id, "result" => result })
+  end
+
+  def respond_error(id, code, message)
+    return if id.nil?
+    write_message({ "jsonrpc" => "2.0", "id" => id, "error" => { "code" => code, "message" => message } })
+  end
+
+  def respond_tool_error(id, text)
+    respond(id, {
+      "content" => [{ "type" => "text", "text" => text }],
+      "isError" => true
+    })
+  end
+
+  def write_message(obj)
+    $stdout.write(JSON.generate(obj) + "\n")
+    $stdout.flush
+  end
+
+  def die(msg)
+    $stderr.puts "muxr-mcp: #{msg}"
+    exit 1
+  end
+end
+
+MuxrMcpBridge.new.run if $PROGRAM_NAME == __FILE__