/muxy-cli

name: muxy-cli
description: How to drive the Muxy macOS terminal multiplexer from a shell with the `muxy` command — open projects, switch projects/worktrees/tabs, build split layouts, send input to panes, and read visible terminal output. Use this when you are an agent running inside a Muxy pane (or any script on the same machine) and want to control the workspace instead of asking the user to click. Mechanics and the security model live in the linked docs.

Muxy CLI Guide

The `muxy` command lets an agent or script control a running Muxy workspace: open projects, switch projects/worktrees/tabs, create split panes, send keystrokes to a pane, and read back what a pane is showing. You drive the same workspace the user sees — treat it as a shared surface, not a private scratchpad.

**This skill is the usage layer — when to reach for the CLI and how to use it safely.** For the full command reference, output formats, and security model, read the docs page (append `/plain` for raw Markdown):

> **<https://muxy.app/docs/features/muxy-cli/plain>**

The LLM-friendly index lists every Muxy docs page: **<https://muxy.app/llms.txt>**.

When to use it

• **You are running inside a Muxy pane** and want to spawn a sibling pane (a dev server, a test watcher, a logs tail) instead of blocking your own terminal. `muxy split-right`/`split-down` start from *your* pane automatically — Muxy exports `MUXY_PANE_ID` into every pane and the CLI reads it.
• **You need to orchestrate work across panes** — start a process in one pane, then later send it input or read its output by pane ID.
• **You are scripting project setup** — open a folder, switch to the right worktree, lay out a known split arrangement.

Don't use it to do work a plain shell command can do in your own pane. Splitting, sending keys, and reading screens are for when the work genuinely belongs in *another* pane the user is watching.

First, confirm Muxy is reachable

Every command talks to the running app over a local Unix socket — except opening a path, which falls back to launching Muxy if it is closed. So the socket commands fail with `Error: Muxy is not running` when Muxy is not open, while `muxy <path>` still works. Check once before a sequence of socket commands:

muxy list-panes >/dev/null 2>&1 || { echo "Muxy not running"; exit 1; }

If `muxy` itself is not found, it has not been installed — the user installs it from **Muxy → Install CLI** (it lands in `/usr/local/bin`, or `~/bin` / `~/.local/bin` as a fallback). You cannot install it for them.

`muxy --help` lists every command; `muxy <command> --help` (or `-h`) prints that command's options.

Capture IDs, never guess them

Pane, tab, project, and worktree commands key off IDs. The split commands **print the new pane ID on stdout** — capture it; do not invent or hardcode IDs.

WEB=$(muxy split-right npm run dev)
TESTS=$(muxy split-down --from "$WEB" npm test)

muxy rename-pane --pane "$WEB" "Web"
muxy rename-pane --pane "$TESTS" "Tests"

For the other surfaces, list and parse the **tab-separated** output (the first column is always the ID/index) rather than matching on a title that may not be unique:

| Command | Columns (tab-separated) | | --- | --- | | `muxy list-panes` | `<pane-id> <title> <cwd> <focused>` | | `muxy list-projects` | `<project-id> <name> <path> <active>` | | `muxy list-worktrees [project]` | `<worktree-id> <name> <path> <branch> <active>` | | `muxy list-workspaces` | `<workspace-id> <name> <project-count> <active>` | | `muxy list-tabs` | `<index> <tab-id> <kind> <title> <active>` | | `muxy list-sessions` | `<session-id> <shell-pid> <cwd> <attached> <title> <project-id> <worktree-id> <tab-id>` |

PANE=$(muxy list-panes | awk -F'\t' '$2=="Tests"{print $1; exit}')

Switch commands resolve a name, ID, path, or branch, so a human-readable argument is fine for `switch-project` / `switch-worktree` / `switch-tab`; capture the ID only when you will address the same pane repeatedly.

Send input deliberately

`muxy send` types text into a pane **without** pressing Return; `muxy send-keys` presses one supported key. Send the text, then the key — this lets you stage a command and run it in two steps, or send a control key on its own:

muxy send --pane "$TESTS" "npm test -- --watch"
muxy send-keys --pane "$TESTS" Enter

Supported keys: `Escape`/`Esc`, `Enter`/`Return`, `Tab`, `Ctrl+C`/`Ctrl-C`, `Ctrl+D`/`Ctrl-D`, `Ctrl+Z`/`Ctrl-Z`, `Backspace`.

You are typing into a live shell another process owns. Read the screen first if you are unsure what is running, and prefer `Ctrl+C` over assuming a prompt is idle.

Read the screen, don't scrape scrollback

`muxy read-screen --pane <id> [--lines N]` returns the **last N visible lines** (default 50) of rendered terminal cells — not the full scrollback. Use it to check on a process you started in another pane:

muxy read-screen --pane "$WEB" --lines 20

If you need more history than is on screen, that is a sign the work should write to a file you can read directly, not be scraped from a terminal.

Background sessions

If the user has **Settings → Terminal → Background sessions** on, terminals keep running after Muxy quits. `muxy list-sessions` shows them, along with the tab, project, and worktree each one belongs to, and `muxy kill-session --session <id>` stops one plus everything running inside it:

muxy kill-session --session "$SESSION"

Take the ID from the first column: it matches the pane ID only until a tab adopts another session. Closing a session's tab already ends it, so reach for `kill-session` only for a session that outlived its tab. Never kill a session you did not create — it is someone's running work, and it is gone for good.

Worktrees and projects

muxy switch-project "My App"
muxy switch-worktree feature/login --project "My App"
muxy create-worktree login --branch feature/login --base main
muxy r