muxy-cli
How to drive Muxy 2 from a shell with the `muxy` command — start terminals that keep running, type into them, read and wait on their output, and manage projects and Git worktrees. Use this when you are an agent running inside a Muxy terminal (or any script on the same computer) and want work to run in its own terminal instead of blocking yours, or to drive the desktop app's built-in browser.
How do I install this agent skill?
npx skills add https://github.com/muxy-app/muxy --skill muxy-cliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a command-line interface for managing background terminals, Git worktrees, and browser automation. While the tool is designed for developer productivity, it provides broad capabilities for arbitrary command execution and ingests untrusted data from terminals and web pages, which introduces a surface for indirect prompt injection and dynamic code execution.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Muxy CLI
Muxy keeps terminals in a background server. The muxy command talks to that
server directly; the desktop app doesn't need to be open. Terminals you start
keep running after your command returns, and the user can open them in the
desktop app or the terminal UI from Existing Terminals, or you can show
one to them with muxy session show.
Run muxy --help for command groups and muxy help session create (or
muxy session create --help) for one command. Add --json to management
commands for machine-readable output. Pipes keep their original text formats;
terminals get formatted tables. Project/session/worktree lists accept
--quiet (-q) for IDs only; do not combine it with --json.
Short aliases: ls = session list, new = session create, send =
session send, send-key = session send-keys, capture =
session read-screen, and wait = session wait.
When to use it
- Start a long-running process (a dev server, a test watcher, a log tail) in its own terminal, then check on it later.
- Wait until that process prints something, or exits, before going on.
- Create a Git worktree for a task, with the user's configured location.
Don't use it for work a plain command can do in your own terminal.
Inside a Muxy terminal
Muxy sets MUXY_SESSION_ID and MUXY_SERVER_ID in every terminal. Session
commands then default to your own terminal, and session create to your
project, so most commands need no IDs.
Start a terminal and capture its ID
session create prints the new session ID. Everything after -- is typed into
the new terminal, followed by Return. Capture the ID; never guess one.
WEB=$(muxy session create -- npm run dev)
TESTS=$(muxy session create MyProject --directory ./packages/api -- exec npm test)
Outside a Muxy terminal, name the project: an ID, a unique name, or its folder.
The words after -- are joined with spaces, so quote the whole command to keep
its own quotes, pipes, or ;:
muxy session create -- 'grep -rn "TODO list" src | wc -l'
Wait instead of polling
muxy session wait "$WEB" --text "ready" --timeout-ms 120000 # prints the matching line
muxy session wait "$TESTS" --exit # prints how it ended
wait fails with a nonzero exit if the timeout passes (default 30 s) or, for
--text, if the terminal ends without showing the text. It looks at the
visible screen, not scrollback. Don't wait on your own terminal: it is busy
running muxy.
--exit waits for the terminal's shell to end. Use exec for a one-shot command,
as in the test example, so the program replaces the shell and its exit ends the
session. Without exec, the shell stays open after the program finishes.
Read output
muxy session read-screen "$WEB" --lines 40 # last visible rows, not scrollback
muxy session search "$WEB" "error" --ignore-case
muxy session history "$WEB" --limit 200 # JSON, paged with --before
After a terminal ends, add --saved to read its last saved output.
Send input deliberately
send types text without pressing Return; send-keys presses one or more
keys in order (Enter, Tab, Escape, Backspace, Ctrl+C, Ctrl+D, Ctrl+Z).
send --stdin sends piped or redirected bytes verbatim, including newlines,
up to 1 MiB. Larger input sends nothing; no text argument is allowed with it.
muxy session send-keys "$WEB" Ctrl+C
muxy session read-screen "$WEB"
muxy session send "$WEB" "npm run dev"
muxy session send-keys "$WEB" Enter
You are typing into a live terminal. Read the screen first if you are unsure what is running.
Inspect and name terminals
muxy project inspect MyProject --json
muxy session inspect "$WEB" --json
muxy session rename "$WEB" dev-server
muxy session list --project MyProject --quiet
Inspection works for live and saved sessions. Renaming updates the shared name shown in every app; IDs stay unchanged and remain the targets for commands.
End terminals you started
muxy session list --project MyProject # id, project-id, status, attached, directory
muxy session end "$WEB" --yes
Only end terminals you created. A terminal the user is looking at closes in their app too.
Show a terminal to the user
muxy session show "$WEB"
This opens the terminal in a new tab of its project in the desktop app, or selects the tab that already shows it, without raising the app. Use it when the user should watch or take over a terminal, not for every terminal you start.
Projects and worktrees
muxy project list
muxy project add ~/code/app --reuse # prints the existing project if there is one
muxy worktree create MyProject login # branch "login" from HEAD, default location
muxy worktree create MyProject fix --branch fix/x --base main --hooks
muxy worktree list MyProject
muxy worktree remove login --yes
--hooks runs the setup or teardown commands from .muxy/worktree.json; ask
the user before using it. worktree remove refuses uncommitted changes unless
--force is given; never pass --force without the user's consent.
Browser
muxy browser drives tabs in the desktop app's built-in browser: open a page,
read it, click and type, take screenshots. It talks to the desktop app on this
Mac, so it needs the app (open starts it) and never takes --host.
TAB=$(muxy browser open http://localhost:3000) # prints the new tab's ID
muxy browser wait-for-navigation "$TAB"
muxy browser snapshot "$TAB" # interactive elements, each with a selector
muxy browser fill "$TAB" "#email" "me@example.com"
muxy browser click "$TAB" "button[type=submit]"
muxy browser wait "$TAB" --text "Welcome" --timeout-ms 10000
muxy browser read "$TAB" # title, URL and page text
- Capture the tab ID that
openprints, or find it withmuxy browser list; never guess one. - Wait after anything that loads a page (
open,navigate, a submittingclick,back):wait-for-navigation,wait-for <selector>, orwait. snapshotlists the interactive elements, each with aselectoryou can pass toclick,fill,type, and the other element commands. They printfalsewhen nothing matches.evalruns JavaScript in the page and prints the result as JSON.- Screenshots work on background tabs:
muxy browser screenshot "$TAB" | base64 -D > page.png. - Close only tabs you opened.
App settings
muxy config reads and changes the desktop app's settings on this computer and
has a running app apply them at once. Keys are dotted paths into
settings.toml, or into terminal.toml after terminal..
muxy config list # every setting with its value
muxy config get terminal.font_size
muxy config set terminal.font_size 14
muxy config unset terminal.font_size # back to the default
- Change settings only when the user asks, and say what changed.
- A rejected value leaves the files as they were; never edit them by hand.
- Server settings, such as the default shell, use
muxy settings.
Other computers
Put --host user@computer before a server-backed command, such as project,
session, or worktree, to use another computer's server over SSH. Directories
are then absolute paths on that computer.
Folder-opening commands, browser, config, session show, and install-skills do
not support --host.
install-skills --dir DIR always installs into a local directory.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/muxy-app/muxy/muxy-cli">View muxy-cli on skillZs</a>