Feature request: ship an official Claude Code skill at .claude/skills/rmux/SKILL.md

[yjloong]

Request

Ship an official Claude Code skill bundled with the repo so that Claude Code automatically knows how to use rmux when a user asks about it. The skill file just needs to live at .claude/skills/rmux/SKILL.md in the repository.

Why

rmux already has:

• rmux claude — a native Claude Code launcher with Agent Teams support (v0.7.0)
• send-keys --wait* — CLI automation primitives for agents (v0.7.0, from send-keys has no completion notification — agents can't know when a command finishes #57)
• Rust SDK, Python SDK (librmux), TypeScript SDK (@rmux/sdk)
• Docs sidebar icons specifically for Claude agent workflows

The missing piece is a skill file that teaches Claude Code how to use rmux's CLI and SDK surfaces. Without it, Claude Code users have to manually explain rmux commands to the model every session. With it, the model loads the skill on-demand (~200 tokens, zero overhead when not used) and can issue correct rmux commands immediately.

What the skill should cover

A reference implementation exists (see comment below). It covers:

Section	Content
Claude Code integration	rmux claude launcher, Agent Teams, swarm sessions, tmux shim
Daemon survival	setsid workaround for Claude Code shell recycling (claude-code#40207)
CLI reference	Sessions, windows, panes, send-keys --wait* (v0.7.0), wait-pane, stream-pane, collect-pane-output, capture-pane, format strings, Web Share with all tunnel providers, config/debugging
SDK reference	Rust SDK: connection, sessions, pane operations (split/send_text/snapshot/wait/PaneSet/Locator/event streams/Web Share)
Agent automation patterns	Chained commands with --wait quiet, cross-session coordination with wait-for, capturing command output
Gotchas	SplitDirection naming, send_text vs send_key, PaneCapture structure, --wait-text shell echo caveat, -- delimiter requirement

All content was tested against rmux v0.6.1 and v0.7.0 with real CLI and SDK programs.

The skill would go at ./claude/skills/rmux/SKILL.md (Claude Code searches .claude/skills/ in the project root). Users who clone or work inside the rmux repo would get it automatically; others can copy it to ~/.claude/skills/rmux-help/.

Related

• send-keys has no completion notification — agents can't know when a command finishes #57 — send-keys --wait* (implemented in v0.7.0)
• [Bug]: In windows11 terminal, Ctrl-C or Ctrl-D don't work #56 — Windows Ctrl-C/D fix
• The Claude Code Skills documentation

[yjloong]

Reference skill implementation

Here is a complete, tested skill file that can be placed at .claude/skills/rmux/SKILL.md. All CLI and SDK patterns were verified against rmux v0.6.1 and v0.7.0.

---
name: rmux-help
description: Guide for using rmux — the Rust terminal multiplexer with 90+ tmux-compatible commands, typed SDK, browser-shared sessions, and native Claude Code launcher. Use when the user asks about rmux CLI commands, rmux-sdk APIs, terminal sharing, agent automation, or Claude Code integration.
disable-model-invocation: true
---

rmux is a modern terminal multiplexer written in Rust that supports Linux, macOS, and Windows (no WSL). It exposes four surfaces: CLI (tmux-compatible), Rust SDK (`rmux-sdk`), browser-based Web Share, and the `rmux claude` launcher for Claude Code Agent Teams.

Check availability first: `which rmux && rmux -V`. Current stable: `0.7.0`. If not installed, recommend `cargo install rmux --locked`.

## Claude Code integration (`rmux claude`)

```sh
# Launch Claude Code inside a dedicated rmux session with Agent Teams support
rmux claude [args...]

What it does:

• Creates a dedicated rmux-claude session for the main Claude process
• Creates a claude-swarm session for multi-agent orchestration
• Passes --teammate-mode tmux to Claude automatically
• Provides a private tmux shim so Claude can drive rmux panes through tmux-compatible commands
• Works on Linux, macOS, and Windows (Windows uses Git Bash-backed teammate panes)
• Set RMUX_DISABLE_TMUX_SHIM=1 to disable the shim

Daemon survival inside Claude Code sessions

Problem: When running rmux inside Claude Code's shell session, the rmux daemon can disappear unexpectedly. Claude Code's shell lifecycle management sends SIGTERM to child processes during session compaction or shell recycling (documented in anthropics/claude-code#40207). Since rmux-daemon is a child of Claude Code's bash process, it gets killed along with the shell.

Symptoms: rmux has-session -t mysession returns "no server running" after working fine moments earlier.

Fix: Start rmux with setsid to detach the daemon from Claude Code's process tree:

# Start a daemon that survives Claude Code shell recycling
setsid rmux new-session -d -s mywork

# All subsequent commands connect to the existing daemon via socket — safe
rmux send-keys -t mywork 'echo hello' Enter --wait quiet
rmux attach-session -t mywork

# When done, remember to clean up
rmux kill-server

setsid gives rmux-daemon PPID=1 (init), so Claude Code can recycle its own shell without touching the daemon. The daemon communicates through the Unix socket at /tmp/rmux-{uid}/default, not through the shell process tree.

Caveat: The daemon will not auto-exit when the Claude Code session ends. Use rmux kill-server to clean up, or let the cc-reaper community tool handle orphaned processes.

CLI reference

All commands mirror tmux syntax. Commonly used ones:

Sessions

rmux new-session -d -s NAME          # create detached session
rmux new-session -d -s NAME -x 120 -y 32  # with size
rmux attach-session -t NAME          # attach
rmux detach-client -s NAME           # detach
rmux list-sessions                   # list all sessions
rmux has-session -t NAME             # check existence
rmux kill-session -t NAME            # destroy session
rmux kill-server                     # stop daemon and all sessions
rmux rename-session -t OLD NEW       # rename

Windows and panes

rmux split-window -h -t SESSION      # split horizontally (side-by-side)
rmux split-window -v -t SESSION      # split vertically (stacked)
rmux split-window -h -b -t SESSION   # new pane left (before target)
rmux kill-pane -t TARGET             # destroy pane
rmux kill-window -t TARGET           # destroy window
rmux list-windows -t SESSION         # list windows
rmux list-panes -t SESSION           # list panes with details
rmux last-pane -t WINDOW             # switch to last active pane
rmux resize-pane -t TARGET -L 10     # resize by 10 columns left

send-keys (v0.7.0: synchronous wait support)

# Basic (async, fire-and-forget — original behavior)
rmux send-keys -t TARGET 'text' Enter
rmux send-keys -t TARGET C-c            # send Ctrl-c

# Synchronous wait modes (v0.7.0 NEW)
rmux send-keys -t TARGET --wait quiet --stable-for 500ms --timeout 30s -- 'cmd' Enter
rmux send-keys -t TARGET --wait-text "DONE" --timeout 10s -- 'cmd' Enter
rmux send-keys -t TARGET --wait-next-text "DONE" --timeout 10s -- 'cmd' Enter
rmux send-keys -t TARGET --wait-visible-text "DONE" --timeout 10s -- 'cmd' Enter
rmux send-keys -t TARGET --wait-pane-exit --timeout 10s -- 'cmd' Enter

# Explicit async (default, for script readability)
rmux send-keys -t TARGET -- 'cmd' Enter

Flag	Behavior	Best for
--wait quiet	Waits for pane output to stop for --stable-for duration	Default choice. "Just tell me when it's done." Works for builds, tests, any long command.
--wait-text "X"	Waits for X to appear in pane output stream	Waiting for specific output like PASS/FAIL
--wait-next-text "X"	Waits for X in NEW output only (after keys sent)	Same as above but ignores existing scrollback
--wait-visible-text "X"	Waits for X in rendered visible snapshot	Checking what the user would see
--wait-pane-exit	Waits for the pane's child process to exit	One-shot commands where you exit after
--timeout <DUR>	Max wait time (e.g. 30s, 5m). Exit code 1 on timeout	Safety belt — always attach
--stable-for <DUR>	How long output must be silent for --wait quiet (default: 500ms)	Tune for chatty programs

Important: -- is required before payload keys when using --wait* flags.

Shell echo caveat: --wait-text and --wait-next-text monitor the raw PTY output stream which includes shell echo of the command itself. If the marker text appears in the command string (e.g., echo DONE), the match will be instant. Disable shell echo first (stty -echo) or use --wait quiet instead.

New v0.7.0 CLI commands

rmux wait-pane -t TARGET              # wait for pane to become ready
rmux stream-pane -t TARGET            # stream pane output to stdout
rmux collect-pane-output -t TARGET    # collect and print pane output

Capturing output

rmux capture-pane -t TARGET -p          # capture pane to stdout
rmux capture-pane -t TARGET -S 0 -E 10  # capture line range
rmux capture-pane -t TARGET -e          # include ANSI escape sequences

Format strings

rmux list-sessions -F "#{session_name}: #{session_width}x#{session_height}"
rmux list-panes -F "pane #{pane_index}: #{pane_width}x#{pane_height} pid=#{pane_pid}"
rmux display-message -p '#{version}'

Web Share

rmux web-share                       # share current session over loopback
rmux web-share -t SESSION            # share a named session
rmux web-share --tunnel-provider localhost-run  # expose via internet
rmux web-share --operator-only       # restrict to operator role
rmux web-share --spectator-only      # restrict to spectator role
rmux web-share --no-pin              # disable pairing PIN requirement
rmux web-share --theme dark          # set frontend theme (user|light|dark)
rmux web-share --ttl 3600            # auto-expire after 1 hour
rmux web-share --disconnect SHARE_ID # revoke an active share

Available tunnel providers: localhost-run, sandhole, serveo, srv-us, tailscale-funnel, tailscale-serve.

Config and debugging

rmux diagnose --human                # full platform/build/runtime report
rmux diagnose --json                 # machine-readable diagnostic
rmux list-commands                   # all 90+ supported commands
rmux list-keys                       # list key bindings
rmux show-options -g                 # global options
rmux set-option -g allow-passthrough on  # enable Kitty graphics/SIXEL

Config file locations

• Linux/macOS: /etc/rmux.conf → ~/.rmux.conf → $XDG_CONFIG_HOME/rmux/rmux.conf
• Windows: %XDG_CONFIG_HOME%\rmux\rmux.conf → %USERPROFILE%\.rmux.conf
• tmux.conf fallback: if no rmux config found, tmux configs are loaded best-effort
• Disable tmux fallback: RMUX_DISABLE_TMUX_FALLBACK=1

SDK reference

SDKs available: Rust (rmux-sdk), Python (librmux), TypeScript (@rmux/sdk).

Connection

use rmux_sdk::{Rmux, RmuxBuilder};
let rmux = Rmux::builder()
    .default_timeout(Duration::from_secs(5))
    .connect_or_start()
    .await?;

Session management

use rmux_sdk::{EnsureSession, EnsureSessionPolicy, SessionName, TerminalSizeSpec};

let session = rmux.ensure_session(
    EnsureSession::named(SessionName::new("work")?)
        .policy(EnsureSessionPolicy::CreateOrReuse)
        .detached(true)
        .size(TerminalSizeSpec::new(120, 32)),
).await?;

Pane operations (core interaction surface)

let pane = session.pane(0, 0);

// Split: SplitDirection::Right | Left | Up | Down
let new_pane = pane.split_with(SplitDirection::Right).shell("bash").await?;

// Send text (trailing \n acts as Enter)
pane.send_text("echo hello\n").await?;
pane.send_key("Enter").await?;

// Wait for output (polling snapshot every 25ms by default)
pane.expect_visible_text().to_contain("ready").timeout(Duration::from_secs(5)).await?;
pane.wait_for_text("ready").await?;

// Daemon-side wait (more efficient, no polling)
pane.wait_for_text_next("ready").await?;

// Snapshot: captures all cells, cursor, colors, revision
let snap = pane.snapshot().await?;
println!("{}x{} rev={}", snap.cols, snap.rows, snap.revision);
let text = snap.visible_text();

// Capture pane stdout (tmux capture-pane equivalent)
let captured = pane.capture_pane().await?;   // fields: stdout, buffer_name

// Collect all output until process exits
let output = pane.collect_output_until_exit_starting_at(PaneOutputStart::Oldest, 64*1024).await?;

// Process lifecycle
pane.wait_for_load_state(TerminalLoadState::Quiet).await?;
pane.wait_for_exit().await?;
pane.resize(TerminalSizeSpec::new(80, 24)).await?;
pane.respawn(PaneRespawnOptions { kill: true, ..Default::default() }).await?;
pane.close().await?;  // returns PaneCloseOutcome

// Info snapshot (sessions, windows, panes metadata)
let info = pane.info().await?;
// info.panes: Vec<PaneInfo>, info.sessions: Vec<SessionInfo>, info.windows: Vec<WindowInfo>

Multi-pane (PaneSet)

use rmux_sdk::PaneSet;
let panes = PaneSet::new(vec![pane1, pane2, pane3]);

// Broadcast same input to all panes
panes.broadcast(Input::text("echo sync\n")).await?;

// Assert ALL panes contain text
panes.expect_all().visible_text_contains("OK").timeout(Duration::from_secs(5)).await;

// Assert ANY pane contains text
panes.expect_any().visible_text_contains("OK").await;

// Bulk snapshot / close
let snapshots = panes.snapshot_all().await;
panes.close_all().await;

Locator (text finder in pane snapshots)

let loc = pane.get_by_text("ERROR").first();
loc.wait_for().timeout(Duration::from_secs(5)).await?;
// loc.nth(2), loc.all() for multiple matches

Event streams

use rmux_sdk::events::{PaneOutputStream, PaneLineStream, PaneRenderStream, PaneOutputStart};
let stream = pane.output_stream().await?;           // raw byte chunks
let line_stream = pane.line_stream().await?;        // line-by-line
let render_stream = pane.render_stream().await?;    // render updates
// Start from a specific point:
let stream = pane.output_stream_starting_at(PaneOutputStart::AfterSequence(42)).await?;

Web Share (SDK)

use rmux_sdk::web_share::WebShareBuilder;
let share = rmux.web_share()
    .tunnel_provider("localhost-run")
    .ttl_seconds(3600)
    .start()
    .await?;
println!("operator URL: {}", share.operator_url());
println!("spectator URL: {}", share.spectator_url());

Agent automation patterns

CLI: chained commands with --wait quiet

# Safely chain operations without blind sleeps
rmux send-keys -t build 'git pull' Enter --wait quiet
rmux send-keys -t build 'cargo build --release' Enter --wait quiet --timeout 5m
rmux send-keys -t build 'cargo test' Enter --wait quiet

# With explicit timeout and error handling
if ! rmux send-keys -t build 'make deploy' Enter --wait quiet --timeout 2m; then
    echo "deploy timed out or failed"
fi

CLI: cross-session coordination (wait-for remains the best tool)

# Producer
rmux send-keys -t s:1 'make build && rmux wait-for -S build_done' Enter

# Consumer (blocks until build finishes)
rmux wait-for -L build_done
rmux send-keys -t s:2 'make deploy' Enter --wait quiet

CLI: capture command output after waiting

rmux send-keys -t ci './run_tests.sh' Enter --wait quiet --timeout 5m
output=$(rmux capture-pane -t ci.0 -p)
echo "$output" | grep -q "PASS" && echo "Tests passed"

Key API gotchas (from real-world testing, v0.6.1 and v0.7.0)

• SplitDirection uses spatial names (Right/Left/Up/Down), not Vertical/Horizontal
• send_text needs trailing \n to execute the command (acts as Enter)
• send_key sends a single key event ("Enter", "C-c"), not text strings
• capture_pane() returns PaneCapture { stdout: Vec<u8>, buffer_name: Option<String> } — use String::from_utf8_lossy(&c.stdout) for text
• collect_output_until_exit needs the process to still be alive when called; use _starting_at(PaneOutputStart::Oldest, ...) to catch output from already-exited processes
• pane.info() returns InfoSnapshot with public fields panes, sessions, windows — each is a Vec
• Killing the last session may shut down the daemon; subsequent transport calls will get UnexpectedEof
• CLI send-keys --wait-text "X": shell echo of the command itself contains X, so match is instant. Use stty -echo first, or prefer --wait quiet for most cases
• CLI send-keys with --wait* flags requires -- before the payload keys
• --wait quiet --stable-for 500ms is the recommended default for "command finished" detection