Clarify tmux-bridge socket selection and outside-tmux usage#7
Conversation
The bridge already supports socket overrides and auto-framed messages, but the docs left out two practical constraints: non-default tmux servers require TMUX_BRIDGE_SOCKET, and message requires the sender to be inside tmux. This updates the skill, bridge reference, and README so users can route to alternate sockets and fall back to type+Enter when running outside tmux. Constraint: Keep the change docs-only and aligned with current tmux-bridge behavior Rejected: Change tmux-bridge behavior in this PR | broader scope than the requested docs fix Confidence: high Scope-risk: narrow Reversibility: clean Directive: If tmux-bridge behavior changes later, update the skill and reference docs in the same PR to keep examples consistent Tested: git diff --check Not-tested: Runtime execution of tmux-bridge examples inside the repo clone
There was a problem hiding this comment.
Pull request overview
This docs-only PR clarifies how tmux-bridge selects a tmux server socket (including non-default tmux -L <name> servers) and documents when/why tmux-bridge message requires the sender to be inside tmux.
Changes:
- Added guidance on selecting non-default tmux servers via
TMUX_BRIDGE_SOCKET. - Documented that
tmux-bridge namelabels are pane metadata (not tmux pane titles). - Documented
messagebehavior (auto-header) and the outside-tmux fallback workflow (type+Enter).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
skills/smux/SKILL.md |
Adds socket-selection guidance and outside-tmux message fallback instructions for the smux skill. |
skills/smux/references/tmux-bridge.md |
Expands the tmux-bridge reference with socket selection and updated message-based messaging conventions. |
README.md |
Updates the top-level command list and adds a brief note on TMUX_BRIDGE_SOCKET for non-default sockets. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| The `message` command auto-prepends sender info and location: | ||
|
|
||
| ``` | ||
| [tmux-bridge from:claude] Please review src/auth.ts | ||
| [tmux-bridge from:claude pane:%4 at:3:0.0] Please review src/auth.ts | ||
| ``` |
There was a problem hiding this comment.
The message header example does not match the actual header emitted by tmux-bridge message. The implementation includes an extra suffix inside the brackets ("— load the smux skill to reply"), so readers copying this example will be looking for the wrong prefix. Update the example header (and any related wording below) to reflect the real format from scripts/tmux-bridge.
|
|
||
| The receiver gets: who sent it (`from`), the exact pane to reply to (`pane`), and the session/window location (`at`). When you see this header, reply using tmux-bridge to the pane ID from the header. | ||
|
|
||
| `tmux-bridge message` requires the sender to be inside tmux so it can include `TMUX_PANE` in the reply header. If you are running outside tmux, `message` will fail with `not running inside a tmux pane`. |
There was a problem hiding this comment.
The error string shown here is shortened. tmux-bridge message actually errors with not running inside a tmux pane ($TMUX_PANE is unset) when run outside tmux (see scripts/tmux-bridge). Consider updating the quoted message to match the real output so users can recognize it exactly.
| `tmux-bridge message` requires the sender to be inside tmux so it can include `TMUX_PANE` in the reply header. If you are running outside tmux, `message` will fail with `not running inside a tmux pane`. | |
| `tmux-bridge message` requires the sender to be inside tmux so it can include `TMUX_PANE` in the reply header. If you are running outside tmux, `message` will fail with `not running inside a tmux pane ($TMUX_PANE is unset)`. |
| # STOP. Do NOT read codex for a reply. The agent replies into YOUR pane. | ||
| ``` | ||
|
|
||
| `tmux-bridge message` requires the sender to be inside tmux so it can include `TMUX_PANE` in the reply header. If you are running outside tmux, `message` will fail with `not running inside a tmux pane`. |
There was a problem hiding this comment.
The error string shown here is shortened. tmux-bridge message actually errors with not running inside a tmux pane ($TMUX_PANE is unset) when run outside tmux (see scripts/tmux-bridge). Consider updating the quoted message to match the real output so users can recognize it exactly.
| `tmux-bridge message` requires the sender to be inside tmux so it can include `TMUX_PANE` in the reply header. If you are running outside tmux, `message` will fail with `not running inside a tmux pane`. | |
| `tmux-bridge message` requires the sender to be inside tmux so it can include `TMUX_PANE` in the reply header. If you are running outside tmux, `message` will fail with `not running inside a tmux pane ($TMUX_PANE is unset)`. |
| ### Receiving messages — IMPORTANT | ||
|
|
||
| **When you see a message prefixed with `[tmux-bridge from:<sender>]`, you MUST reply using tmux-bridge:** | ||
| **When you see a message prefixed with `[tmux-bridge from:<sender> pane:%N at:...]`, you MUST reply using tmux-bridge to the pane ID in the header:** |
There was a problem hiding this comment.
This section describes the prefix as [tmux-bridge from:<sender> pane:%N at:...], but the current tmux-bridge message header includes an additional in-bracket suffix ("— load the smux skill to reply"). Update the described prefix to match the actual header so the guidance is consistent with what users will see in-pane.
| **When you see a message prefixed with `[tmux-bridge from:<sender> pane:%N at:...]`, you MUST reply using tmux-bridge to the pane ID in the header:** | |
| **When you see a message prefixed with `[tmux-bridge from:<sender> pane:%N at:... — load the smux skill to reply]`, you MUST reply using tmux-bridge to the pane ID in the header:** |
Summary
TMUX_BRIDGE_SOCKETfor panes running on non-default tmux socketstmux-bridgelabels are different from tmux pane titlestmux-bridge messagerequires the sender to be inside tmux, withtype+Enteras the fallbackskills/smux/SKILL.md, andskills/smux/references/tmux-bridge.mdVerification
git diff --checkContext
This PR is docs-only and reflects current
tmux-bridgebehavior that was validated while routing messages to a Claude pane running on a separatetmux -L guisocket.