muxr 0.1.3 → 0.1.5

data/lib/muxr/key_parser.rb

@@ -0,0 +1,89 @@
+module Muxr
+  # Translates an array of "keys" entries (a mix of literal text and vim-style
+  # named keys like "<esc>") into a stream of byte segments tagged by kind.
+  #
+  # Each input element is either:
+  #
+  #   - Literal text (UTF-8) — emitted as [:literal, bytes].
+  #   - A named key wrapped in angle brackets like "<esc>", "<c-c>", "<up>" —
+  #     emitted as [:special, bytes] using the appropriate control sequence.
+  #
+  # The tagged form lets callers wrap *only* literal segments in
+  # bracketed-paste markers when desired. Concatenating the bytes of all
+  # segments gives the raw byte stream to write to the PTY.
+  module KeyParser
+    NAMED_KEY_RE = /\A<([^<>]+)>\z/.freeze
+
+    # CSI = ESC [ , SS3 = ESC O — both standard xterm key encodings.
+    CSI = "\e[".b.freeze
+    SS3 = "\eO".b.freeze
+
+    # Single canonical map. Keys are lowercased; aliases live alongside their
+    # canonical forms. Values are ASCII byte strings.
+    NAMED_KEYS = {
+      "esc"      => "\e".b,
+      "escape"   => "\e".b,
+      "enter"    => "\r".b,
+      "cr"       => "\r".b,
+      "return"   => "\r".b,
+      "tab"      => "\t".b,
+      "s-tab"    => "#{CSI}Z".b,
+      "bs"       => "\x7f".b, # what real backspace keys send through a PTY
+      "backspace"=> "\x7f".b,
+      "space"    => " ".b,
+      "up"       => "#{CSI}A".b,
+      "down"     => "#{CSI}B".b,
+      "right"    => "#{CSI}C".b,
+      "left"     => "#{CSI}D".b,
+      "home"     => "#{CSI}H".b,
+      "end"      => "#{CSI}F".b,
+      "pageup"   => "#{CSI}5~".b,
+      "pagedown" => "#{CSI}6~".b,
+      "f1"       => "#{SS3}P".b,
+      "f2"       => "#{SS3}Q".b,
+      "f3"       => "#{SS3}R".b,
+      "f4"       => "#{SS3}S".b,
+      "f5"       => "#{CSI}15~".b,
+      "f6"       => "#{CSI}17~".b,
+      "f7"       => "#{CSI}18~".b,
+      "f8"       => "#{CSI}19~".b,
+      "f9"       => "#{CSI}20~".b,
+      "f10"      => "#{CSI}21~".b,
+      "f11"      => "#{CSI}23~".b,
+      "f12"      => "#{CSI}24~".b
+    }.freeze
+
+    CTRL_RE = /\Ac-([a-z])\z/.freeze
+
+    module_function
+
+    # Returns an array of [kind, bytes] pairs. Raises Dispatcher::Error on a
+    # non-array input or an unrecognized `<name>`.
+    def translate(entries)
+      raise Dispatcher::Error.new("`keys` must be an array of strings") unless entries.is_a?(Array)
+
+      entries.map do |entry|
+        raise Dispatcher::Error.new("`keys` entries must be strings") unless entry.is_a?(String)
+        classify(entry)
+      end
+    end
+
+    def classify(entry)
+      m = NAMED_KEY_RE.match(entry)
+      return [:literal, entry.b] unless m
+
+      name = m[1].downcase
+      bytes = NAMED_KEYS[name] || ctrl_bytes(name)
+      raise Dispatcher::Error.new("unknown named key #{entry.inspect}") unless bytes
+
+      [:special, bytes]
+    end
+
+    def ctrl_bytes(name)
+      m = CTRL_RE.match(name)
+      return nil unless m
+      # <c-a>=0x01 .. <c-z>=0x1A
+      (m[1].ord - "a".ord + 1).chr.b
+    end
+  end
+end

data/lib/muxr/pane.rb

@@ -1,19 +1,56 @@
+require "securerandom"
+
 module Muxr
   # A Pane bundles a Terminal emulator buffer with the PTYProcess running the
   # shell that feeds it. The Window keeps a list of panes; the Renderer asks
   # each pane for its current grid contents and cursor position.
+  #
+  # Each pane has a stable 6-hex id generated at creation. The id survives
+  # promote_to_master and other array reshuffles (since it lives on the Pane,
+  # not on the index) and is persisted in the session JSON so it also survives
+  # a full cold restart. The drawer pane uses the symbol `:drawer` as its id;
+  # the MCP control surface treats it specially and never lists it under
+  # `panes.list`.
   class Pane
     attr_reader :id, :terminal, :process
     attr_accessor :rect
 
-    def initialize(id:, rows: 24, cols: 80, cwd: nil, command: nil, process: nil)
-      @id = id
+    def initialize(id: nil, rows: 24, cols: 80, cwd: nil, command: nil, env_overrides: nil, process: nil)
+      @id = id || SecureRandom.hex(3)
       @rows = rows
       @cols = cols
       @terminal = Terminal.new(rows: rows, cols: cols)
-      @process = process || PTYProcess.new(rows: rows, cols: cols, cwd: cwd, command: command)
+      @process = process || PTYProcess.new(
+        rows: rows,
+        cols: cols,
+        cwd: cwd,
+        command: command,
+        env_overrides: env_overrides || {}
+      )
       @rect = nil
       @initial_cwd = cwd || @process.cwd
+      @private_flag = false
+    end
+
+    # Private panes are invisible to the MCP control surface — their cwd is
+    # stripped from panes.list and pane.read/send_input/run/subscribe/kill
+    # all refuse. Toggled by the human via Ctrl-a P or `:private`. Never
+    # settable from the control surface itself (so a misbehaving MCP client
+    # can't unmark a pane it shouldn't see).
+    def private?
+      @private_flag
+    end
+
+    def mark_private!
+      @private_flag = true
+    end
+
+    def mark_public!
+      @private_flag = false
+    end
+
+    def toggle_private!
+      @private_flag = !@private_flag
     end
 
     def io
@@ -36,11 +73,32 @@ module Muxr
       @process.write(data)
     end
 
+    # Drain everything currently in the PTY's kernel read buffer, feeding
+    # each chunk to the Terminal. Coalescing reads here means we render once
+    # per fully-formed output burst (fzf re-render, vim cursor+status redraw,
+    # etc.) instead of once per ~8 KiB chunk — the latter shows intermediate
+    # frames and is the main source of in-pane flicker. Bounded by a byte cap
+    # so a runaway producer can't starve other panes on a single tick.
+    READ_BUDGET = 1 << 20 # 1 MiB
     def read_from_pty
-      data = @process.read_nonblock
-      return nil unless data
-      @terminal.feed(data)
-      data
+      total = 0
+      while total < READ_BUDGET
+        chunk = @process.read_nonblock
+        break unless chunk
+        @terminal.feed(chunk)
+        total += chunk.bytesize
+      end
+      # The emulator may owe the inner program a reply (DSR / CPR — see
+      # Terminal#take_pending_replies!). Ship it back through the PTY's
+      # input side as if it had been typed. Failure here is non-fatal: the
+      # process can have exited between read and write.
+      if (reply = @terminal.take_pending_replies!)
+        begin
+          @process.write(reply)
+        rescue Errno::EIO, Errno::EPIPE
+        end
+      end
+      total.positive? ? total : nil
     end
 
     def resize(rows, cols)

data/lib/muxr/renderer.rb

@@ -93,6 +93,11 @@ module Muxr
         focused = (i == win.focused_index) && !(session.focus_drawer && session.drawer&.visible?)
         title = "##{i + 1}"
         title += "/#{win.panes.length}" if monocle
+        # Stable id sits after the slot number so monocle reads "#1/3 a3f9b2".
+        # respond_to? guard keeps renderer tests (which use simple struct fakes)
+        # from blowing up when a pane stand-in doesn't implement #id.
+        title += " #{pane.id}" if pane.respond_to?(:id) && pane.id.is_a?(String)
+        title += " [P]" if pane.respond_to?(:private?) && pane.private?
         title += " ★" if i == win.master_index
         title += " (" + win.layout.to_s + ")" if i == win.focused_index
         if pane.terminal.scrolled_back?
@@ -113,7 +118,11 @@ module Muxr
 
       w = session.width
       h = session.height
-      dh = (h * 0.35).round.clamp(5, h - 2)
+      # Drawer height is the larger of "16 rows" or 35% of the screen — the
+      # 35% rule is fine on tall terminals but uselessly small on short ones,
+      # so we floor it at 16 to keep the drawer practical. Final clamp keeps
+      # room for panes + status bar on very small terminals.
+      dh = [16, (h * 0.35).round].max.clamp(5, h - 2)
       dy = h - 1 - dh
       rect = LayoutManager::Rect.new(0, dy, w, dh)
       drawer.pane.rect = rect
@@ -263,7 +272,9 @@ module Muxr
       "  C-a k       close focused pane",
       "  C-a Tab     cycle layout (tall → grid → monocle)",
       "  C-a Enter   promote focused pane to master",
-      "  C-a ~       toggle drawer",
+      "  C-a ~       toggle drawer (shell)",
+      "  C-a C       toggle Claude Code drawer (MCP-aware)",
+      "  C-a P       toggle private flag on focused pane (hides from MCP)",
       "  C-a [       enter scrollback (j/k d/u f g/G C-b/C-f; v→cursor, q quits)",
       "              cursor: v select, C-v block, y yank, q cancel",
       "              motions: h/j/k/l 0/^/$ w/e/b W/E/B H/M/L g/G",
@@ -274,7 +285,7 @@ module Muxr
       "  C-a ?       toggle this help",
       "  C-a C-a     send literal C-a",
       "",
-      "Commands: layout {tall|grid|monocle}, drawer {toggle|show|hide|reset},",
+      "Commands: layout {tall|grid|monocle}, drawer {toggle|show|hide|reset}, claude,",
       "          save, restore, sessions, quit, new, close, next, prev",
       "",
       "press any key to dismiss"
@@ -371,7 +382,13 @@ module Muxr
     end
 
     def emit_frame(frame, session, input_state:, command_buffer:)
-      out = String.new("\e[0m")
+      # \e[?2026h enters synchronized-output mode so terminals that support it
+      # (Ghostty, kitty, iTerm2 ≥3.5, WezTerm, Alacritty ≥0.13, foot) present
+      # the whole frame atomically instead of repainting incrementally as bytes
+      # arrive. \e[?25l hides the cursor for the duration of the diff so it
+      # doesn't smear across every \e[y;xH position; cursor_position turns it
+      # back on at the final spot.
+      out = String.new("\e[?2026h\e[?25l\e[0m")
       same_size = @prev && @prev_w == frame[0].length && @prev_h == frame.length
       cur_fg = :unset
       cur_bg = :unset
@@ -400,6 +417,7 @@ module Muxr
       end
       out << "\e[0m"
       out << cursor_position(session, input_state: input_state, command_buffer: command_buffer)
+      out << "\e[?2026l"
       @out.write(out)
       @out.flush
       @prev = frame.map { |row| row.map(&:dup) }

data/lib/muxr/session.rb

@@ -45,7 +45,7 @@ module Muxr
         "focused_index"  => @window.focused_index,
         "master_index"   => @window.master_index,
         "focus_drawer"   => @focus_drawer,
-        "panes"          => @window.panes.map { |p| { "cwd" => safe_cwd(p) } },
+        "panes"          => @window.panes.map { |p| { "id" => safe_id(p), "cwd" => safe_cwd(p), "private" => safe_private(p) } },
         "drawer"         => serialize_drawer
       }
     end
@@ -76,11 +76,22 @@ module Muxr
       pane.respond_to?(:cwd) ? pane.cwd : nil
     end
 
+    def safe_id(pane)
+      return nil unless pane.respond_to?(:id)
+      id = pane.id
+      id.is_a?(String) ? id : nil
+    end
+
+    def safe_private(pane)
+      pane.respond_to?(:private?) && pane.private?
+    end
+
     def serialize_drawer
       return nil unless @drawer
       {
         "visible" => @drawer.visible?,
-        "cwd"     => @drawer.cwd
+        "cwd"     => @drawer.cwd,
+        "command" => @drawer.respond_to?(:command) ? @drawer.command : nil
       }
     end
   end

data/lib/muxr/terminal.rb

@@ -12,6 +12,14 @@ module Muxr
 
     SCROLLBACK_MAX = 5000
 
+    # Inner programs (fzf ≥ 0.41, neovim, helix, …) bracket coherent screen
+    # updates with `\e[?2026h … \e[?2026l` (DECSET 2026 — "Synchronized
+    # Output"). When we see the open, we know more bytes are coming that
+    # belong to the same logical frame; rendering before the close shows a
+    # half-painted state. SYNC_TIMEOUT is the safety cap so a crashed inner
+    # program (which left ?2026h open) cannot wedge the pane indefinitely.
+    SYNC_TIMEOUT = 0.2
+
     Cell = Struct.new(:char, :fg, :bg, :attrs) do
       def reset!
         self.char = " "
@@ -52,6 +60,40 @@ module Muxr
       @selection_anchor = nil
       @selection_cursor = nil
       @selection_mode = :linear
+      @sync_pending = false
+      @sync_started_at = nil
+      @pending_replies = +"".b
+    end
+
+    # Bytes the emulator owes back to the inner program in response to a
+    # query (currently DSR / Device Status Report — `\e[5n` and `\e[6n`).
+    # The Pane drains this after each feed and writes it to the PTY's input
+    # side. Without it, programs like the AWS CLI fall back with a warning
+    # ("your terminal doesn't support cursor position requests (CPR)").
+    def take_pending_replies!
+      return nil if @pending_replies.empty?
+      data = @pending_replies
+      @pending_replies = +"".b
+      data
+    end
+
+    # True iff the inner program has opened a synchronized-output block
+    # (\e[?2026h) and not yet closed it, and the safety timeout has not
+    # elapsed. The Application uses this to defer rendering so the diff lands
+    # on a fully-formed frame instead of a half-painted one.
+    def sync_pending?
+      return false unless @sync_pending
+      if @sync_started_at && (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @sync_started_at) > SYNC_TIMEOUT
+        @sync_pending = false
+        @sync_started_at = nil
+        return false
+      end
+      true
+    end
+
+    def sync_deadline
+      return nil unless @sync_pending && @sync_started_at
+      @sync_started_at + SYNC_TIMEOUT
     end
 
     attr_reader :selection_mode
@@ -60,6 +102,20 @@ module Muxr
       @buffer[r][c]
     end
 
+    # Return the currently-visible grid as a text string (rows joined by "\n",
+    # trailing whitespace stripped on each row). Used by the control surface
+    # to expose pane contents to programmatic clients (the MCP bridge in
+    # particular). This walks visible_cell so callers see whatever the user
+    # is currently looking at, including scrollback.
+    def dump_text
+      lines = Array.new(@rows) do |r|
+        row = String.new(capacity: @cols)
+        @cols.times { |c| row << visible_cell(r, c).char }
+        row.rstrip
+      end
+      lines.join("\n")
+    end
+
     # Returns the Cell that should be visible at (r, c) given the current
     # scrollback view_offset. When view_offset == 0 this is the live grid.
     # When view_offset > 0, rows in the top of the visible area are sourced
@@ -527,8 +583,20 @@ module Muxr
       when ">", "<", "=", "!"
         return
       when "?"
-        # DEC private modes — we treat `h`/`l` as no-ops anyway, so dropping
-        # everything is safe and avoids `\e[?Nr` colliding with DECSTBM.
+        # DEC private modes — most we treat as no-ops, but mode 2026
+        # (Synchronized Output) is a render-timing hint we honor so the
+        # outer paint lands on fully-formed frames from fzf/nvim/helix.
+        if final == "h" || final == "l"
+          if csi_params.include?(2026)
+            if final == "h"
+              @sync_pending = true
+              @sync_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            else
+              @sync_pending = false
+              @sync_started_at = nil
+            end
+          end
+        end
         return
       end
 
@@ -604,6 +672,16 @@ module Muxr
         @saved_cursor = [@cursor_row, @cursor_col]
       when "u"
         @cursor_row, @cursor_col = @saved_cursor
+      when "n"
+        # DSR — Device Status Report. `\e[5n` asks if the terminal is OK,
+        # `\e[6n` (CPR) asks for the cursor position. The reply rides back
+        # through the PTY's input side; see take_pending_replies!.
+        case pms[0] || 0
+        when 5
+          @pending_replies << "\e[0n".b
+        when 6
+          @pending_replies << "\e[#{@cursor_row + 1};#{@cursor_col + 1}R".b
+        end
       when "h", "l"
         # Non-private mode set/reset — nothing we need to honor. (DEC private
         # `?`-prefixed mode sequences are short-circuited above.)

data/lib/muxr/version.rb

@@ -1,3 +1,3 @@
 module Muxr
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/lib/muxr.rb

@@ -10,6 +10,7 @@ require_relative "muxr/renderer"
 require_relative "muxr/input_handler"
 require_relative "muxr/command_dispatcher"
 require_relative "muxr/protocol"
+require_relative "muxr/control_server"
 require_relative "muxr/application"
 require_relative "muxr/client"
 

data/muxr.gemspec

@@ -26,10 +26,12 @@ Gem::Specification.new do |spec|
   }
 
   spec.bindir        = "bin"
-  spec.executables   = ["muxr"]
+  spec.executables   = ["muxr", "muxr-mcp"]
   spec.files         = Dir[
     "lib/**/*.rb",
     "bin/muxr",
+    "bin/muxr-mcp",
+    "skills/**/*",
     "README.md",
     "CHANGELOG.md",
     "LICENSE.txt",

data/skills/muxr-control/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: muxr-control
+description: |
+  Use when driving a muxr terminal session — running commands across panes,
+  watching long-running processes, capturing terminal output, setting up
+  layouts, or working with the muxr drawer. Triggers when MUXR_SESSION is
+  set in the environment, or when the user asks to "run X in pane Y",
+  "what does pane N show", "switch the muxr layout", etc.
+---
+
+# muxr-control
+
+You're driving a [muxr](https://github.com/roelbondoc/muxr) terminal
+multiplexer session through its MCP bridge. muxr is a tiling terminal
+multiplexer (think tmux + xmonad). Each pane is a real shell PTY; you can
+read its current screen contents, send keystrokes, and wait for output to
+settle — without taking control of the user's keyboard.
+
+## First thing: ground yourself
+
+Before doing anything else, call **`muxr_session_get`** and
+**`muxr_panes_list`**. These are cheap, idempotent reads. They tell you:
+
+- The session name, layout (tall / grid / monocle), and current dimensions.
+- Each pane's stable id (6 hex chars, e.g. `a3f9b2`), its 1-based slot
+  number as shown on screen (`#1`, `#2`, …), its cwd, and whether it's the
+  focused or master pane.
+- The `focused_pane` field in `session.get` tells you which pane the user
+  was last looking at — if the user just said "run X" without naming a
+  pane, that's the natural target.
+
+## Pane identity: **always use the id, never the slot**
+
+The status bar shows panes as `#1 a3f9b2`, `#2 c2e810`, etc. The number is
+a *slot* — purely positional and tied to where the pane sits in the array.
+The hex string is the *id* — generated once at pane creation and stable
+forever.
+
+Slots shift when panes are created, killed, or promoted to master. The id
+never moves. **Every tool call that names a pane should pass the id.** If
+the user says "the second pane", look it up in `muxr_panes_list` and pass
+the id you find at slot 2 — don't pass `2` directly even though it works,
+because by the time the call lands the slots may have changed.
+
+## Recipes
+
+### Run a command and get its output
+
+```
+muxr_pane_run({ "pane": "a3f9b2", "input": "ls -la" })
+```
+
+This sends `ls -la\r` to pane `a3f9b2`, waits for the PTY to go idle (no
+output for 500ms by default), and returns the pane's full visible text
+plus a `timed_out` flag.
+
+**Always prefer `muxr_pane_run` over `muxr_pane_send_input` + a separate
+`muxr_pane_read`.** The split version races — the read can fire before
+the shell has redrawn the prompt, and you'll miss the output entirely.
+
+### Tune `idle_ms` for the kind of command
+
+- **Fast, simple commands** (`pwd`, `git status`): default 500ms is fine.
+- **Bursty output** (test runners, builds): bump to `idle_ms: 800` or
+  `1000`. Test runners often pause briefly between phases; a too-short
+  idle window cuts off mid-run.
+- **Interactive REPLs** that you want to type into without waiting for
+  completion: use `muxr_pane_send_input` directly with `append_enter:
+  false` — don't try to detect idleness on a REPL.
+- **Long builds** (npm install, cargo build): bump `timeout_ms` to
+  `120000` or higher. Default is 30s.
+
+### Wait without sending anything
+
+```
+muxr_pane_run({ "pane": "a3f9b2", "input": "", "append_enter": false,
+                "idle_ms": 1000, "timeout_ms": 30000 })
+```
+
+Useful when the user has already typed a command and you want to capture
+its output once it finishes.
+
+### Send multi-line input (paste mode)
+
+```
+muxr_pane_send_input({
+  "pane": "a3f9b2",
+  "data": "def hello\n  puts :world\nend\n",
+  "bracketed": true
+})
+```
+
+`bracketed: true` wraps the data in `\e[200~` / `\e[201~` so editors and
+REPLs treat it as a single paste rather than N separate keystrokes (which
+fires their auto-indent / autocomplete on every line).
+
+### Look at the drawer without opening it
+
+```
+muxr_drawer_read({})
+```
+
+The drawer's shell process keeps running while hidden — its scrollback
+survives. You can read it any time without disturbing the user's view.
+
+### Set up a layout for a task
+
+```
+muxr_layout_set({ "layout": "tall" })
+muxr_pane_new({})                              // create a second pane
+muxr_pane_send_input({ "pane": "<new id>", "data": "npm run dev\n" })
+```
+
+Avoid doing this unsolicited — the human owns the layout. Only restructure
+when the user explicitly asks ("set up a dev environment", "split this
+into 3 panes").
+
+## Gotchas
+
+### Reading is cheap. Writing is destructive.
+
+`muxr_pane_read`, `muxr_panes_list`, `muxr_drawer_read`, and
+`muxr_session_get` have zero side effects — call them whenever you need
+to ground yourself. **Mutating tools** (`muxr_pane_send_input`,
+`muxr_pane_run`, `muxr_pane_kill`, `muxr_layout_set`, …) affect the
+user's live session. Before calling any of them:
+
+- Confirm the user named the specific pane you're about to act on (or
+  agreed implicitly by saying "run X here").
+- Double-check the id by reading `muxr_panes_list` if you haven't done so
+  recently.
+- **Never `muxr_pane_kill`** without the user explicitly saying "close
+  pane X" — a pane often holds in-progress work that's not in any file.
+
+### `pane.read` returns *visible* text only
+
+The result is the pane's current 80×24-or-whatever grid, with trailing
+whitespace trimmed per row. Lines that have scrolled into scrollback are
+not in the response. If you need older output, ask the user to scroll
+the pane up first (they have `Ctrl-a [` for scrollback mode), or watch
+the pane via `muxr_pane_run` while the command is running.
+
+### Private panes
+
+The user can mark any pane *private* with `Ctrl-a P` (status bar shows
+`[P]` after the pane id). Private panes appear in `muxr_panes_list` with
+`"private": true` and *no* `cwd`/`rows`/`cols` — `muxr_pane_read`,
+`muxr_pane_send_input`, `muxr_pane_run`, `muxr_pane_subscribe`, and
+`muxr_pane_kill` all refuse with an error message that tells you the
+human-side gesture to undo it.
+
+When this happens: **do not retry**. Surface it to the user verbatim
+("pane #2 a3f9b2 is private; press Ctrl-a P on it to expose it to me").
+The privacy flag is intentionally one-way from MCP's perspective: there
+is no `muxr_pane_unmark_private` tool.
+
+`muxr_pane_focus` and `muxr_pane_promote` still work on private panes
+(they're layout ops, not content ops) — useful if the user asks to
+"bring my private pane to the front" without exposing it.
+
+### The drawer might be Claude itself
+
+If the bridge sees the env var `MUXR_DRAWER_SELF=1` it refuses
+`muxr_drawer_*` methods — that means the bridge is running *inside* the
+muxr drawer and the call would recurse into your own pty. If you get
+that error, that's why: you can still drive the surrounding tiled panes
+normally, you just can't toggle/read the drawer that's hosting you.
+
+### Don't toggle the drawer just to peek
+
+`muxr_drawer_read` works without showing the drawer. Toggling it to
+look, then toggling back, is visible to the user as a flash of overlay
+and is almost never what they wanted.
+
+### Tool errors
+
+If a tool call returns `isError: true`, the text usually starts with
+`muxr error <code>: <message>`. Common ones:
+
+- `muxr error -32602: pane: no pane with id "…"` — the pane has been
+  killed, or you passed a stale id from before a kill/promote. Refetch
+  `muxr_panes_list`.
+- `muxr error -32602: layout: unknown layout` — valid layouts are
+  `tall`, `grid`, `monocle`.
+
+## Naming muxr in conversation
+
+When responding to the user, call panes by **slot first, id second**:
+"pane #2 (a3f9b2) is showing the test failures." That matches what's on
+their status bar and makes the id available for follow-up references.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: muxr
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Roel Bondoc
@@ -46,6 +46,7 @@ email:
 - rsbondoc@gmail.com
 executables:
 - muxr
+- muxr-mcp
 extensions: []
 extra_rdoc_files: []
 files:
@@ -53,12 +54,15 @@ files:
 - LICENSE.txt
 - README.md
 - bin/muxr
+- bin/muxr-mcp
 - lib/muxr.rb
 - lib/muxr/application.rb
 - lib/muxr/client.rb
 - lib/muxr/command_dispatcher.rb
+- lib/muxr/control_server.rb
 - lib/muxr/drawer.rb
 - lib/muxr/input_handler.rb
+- lib/muxr/key_parser.rb
 - lib/muxr/layout_manager.rb
 - lib/muxr/pane.rb
 - lib/muxr/protocol.rb
@@ -69,6 +73,7 @@ files:
 - lib/muxr/version.rb
 - lib/muxr/window.rb
 - muxr.gemspec
+- skills/muxr-control/SKILL.md
 homepage: https://github.com/roelbondoc/muxr
 licenses:
 - MIT