Muxy: a lightweight macOS terminal built on libghostty, with an extension API

The problem Muxy targets: terminal sessions that outlive a single window

A terminal emulator is usually a window with tabs. That model breaks down once one machine holds several repositories, each needing a shell in the repo root, a second pane running a dev server, a third tailing logs, and a fourth attached to an agent or a REPL. Muxy's answer is to make the project the top-level unit and the terminal session a child of it. The README lists project groups, vertical tabs, split panes, git worktrees, workspace and session persistence, and a quick open and command palette. Those features only make sense together: groups hold projects, worktrees let one repository appear several times at different branches, and persistence means the arrangement survives a restart. The intended user is a developer on macOS who keeps multiple checkouts open at once and is willing to trade a mature, widely deployed emulator for one whose organising model matches that habit. The repository topics name amp, claude, codex, gemini and opencode, which suggests the author expects agent sessions to be one of the things living in those panes.

How Muxy is put together: SwiftUI shell, libghostty core, separate extension host

The README describes Muxy as built with SwiftUI and libghostty, and the repository layout backs that up. The top level contains GhosttyKit/, which is where the ghostty terminal core is vendored, alongside Muxy/ for the app itself and a set of separate Swift modules: MuxyExtensionHost, MuxyHookBridge, MuxyHookKit, MuxyServer, MuxySession, MuxySessionProtocol and MuxyShared. That split is the interesting architectural decision. The extension host is its own module rather than code running inside the app target, and the session and session-protocol modules are separated from the UI, which implies sessions are modelled as their own objects with a defined protocol rather than as views. MuxyServer suggests something is exposed over a local interface. The README does not document the wire format or the server's surface, so treat that as an unknown until you read MuxyServer/ directly. The practical consequence for an adopter is that the terminal emulation itself is ghostty's, not Muxy's, so rendering and escape-sequence behaviour should track the upstream project; Muxy's own surface area is the workspace model, the extension API and the mobile companions.

Installing Muxy on macOS and opening the first project group

The README gives two install paths: a Homebrew cask from the project's own tap, and a manual download from the releases page. The cask is the shorter route. Run the tap and install commands, then launch Muxy from Applications.

brew tap muxy-app/tap
brew install --cask muxy

If you would rather build from source, the README documents a setup script that fetches the ghostty framework, then a debug build and run. The requirements section lists macOS 14+ and Swift 6.0+.

scripts/setup.sh          # downloads GhosttyKit.xcframework
swift build               # debug build
swift run Muxy             # run

There is also a checks script that the README says runs format, lint, build and test in isolated app storage, which is the command to use before sending a patch. For local debug runs, the repository ships .env.example. Copy it to .env and set SENTRY_DSN if you want error reporting; the file states the values are read by the app in DEBUG builds only and that an empty DSN disables Sentry locally.

cp .env.example .env

Once the app is running, the workflow the README implies is: create a project group, add your repository, then split panes inside it. The command palette is the documented way to reach these actions without the menu bar, and the README lists 50+ customizable shortcuts if you would rather bind them. The optional quick terminal is described as expanding from the screen cutout with a persistent home-directory shell, so it is a separate surface from your project panes and not a replacement for them.

The extension and skills story is the part to scrutinise

Muxy's stated vision is a lightweight terminal with a rich API for extensions, and the repository carries the machinery for it: an extension host module, a skills directory under Muxy/Resources/skills, and a skills-lock.json at the top level. The README shows three install commands for agent skills, one for driving the workspace from a shell (open projects, splits, send keys, read panes), one for authoring extensions against a manifest and a window.muxy API, and a third that installs both into every detected AI harness and requires the Muxy CLI.

npx skills add github.com/muxy-app/muxy/tree/main/Muxy/Resources/skills/muxy-cli
npx skills add github.com/muxy-app/muxy/tree/main/Muxy/Resources/skills/muxy-extension
muxy install-skills

The third command is the one that tells you something about the project's assumptions: it presumes a Muxy CLI exists on your PATH, and the README does not say how that binary is installed or whether the Homebrew cask provides it. That is a real gap. The skills themselves are the most concrete extension surface documented here, and they are worth reading before you invest in writing an extension, because they describe the API from the caller's side.

Where Muxy is the wrong tool, and what it is not competing with

The clearest limitation is release maturity. The most recent releases listed are v2.0.0-beta-1012, v2.0.0-beta-1011 and v2.0.0-beta-1010, all dated 2026-09-14, and the build number suggests a rapid beta cadence rather than a settled release. If your terminal is where you keep long-running sessions you cannot afford to lose, a beta line is a real risk, and the README does not document a rollback path or a downgrade procedure. Platform is the second boundary: the README lists macOS 14+ for the desktop build, and the iOS and Android entries point to a separate mobile repository, so Muxy is not a Linux or Windows terminal. If you work across platforms and want one configuration everywhere, this is not it. The third case is narrower: if you want a terminal whose behaviour you can predict purely from ghostty's own documentation and release notes, a wrapper adds a layer between you and that, and the README does not describe how closely Muxy tracks upstream. For a comparison, ghostty itself is the obvious alternative, and the difference is one of scope rather than quality. Ghostty is the terminal core. Muxy takes that core and adds a workspace model on top: project groups, worktrees, an extension host, a server module and mobile companions. Choosing between them is choosing whether you want the emulator alone or the emulator plus an opinionated project layer. The README does not claim Muxy's terminal rendering differs from ghostty's, and there is no reason to assume it does.

Licence, maintenance and what an upgrade actually costs

Muxy is MIT licensed, which is permissive and places few obligations on you beyond retaining the copyright and licence text if you redistribute. Note that the licence covers Muxy's own code; GhosttyKit/ vendors the ghostty terminal core, which carries its own licence terms, and the repository does not restate them in the README. If you plan to ship a build, read the licence files in both locations rather than assuming MIT covers the whole tree. On maintenance: the repository is not archived, and the last push was on 2026-09-14, which is current. That is the only maintenance signal available here, and it says nothing about the project's direction. The upgrade cost is dominated by the beta cadence. Three beta releases on a single day, with build numbers in the thousands, means the version you install today may be superseded within hours, and the README offers no changelog guidance or compatibility statement for the extension API between betas. If you write an extension against the window.muxy API, budget for it breaking. The workspace and session persistence feature also cuts both ways on upgrades: persisted sessions that fail to restore after a version change are a failure mode the README does not address.

Editorial conclusion

Adopt Muxy if you work on a Mac and want terminal sessions organised by project rather than by window, and you accept that the current release line is 2.0.0-beta-1012. Do not adopt it if you need a stable tagged release, if your work happens on Windows or Linux (the README only lists macOS 14+ and Swift 6.0+ for the desktop build), or if you depend on a terminal that follows the ghostty upstream release cadence rather than a wrapper's. Before installing, verify two things: that the Homebrew cask resolves from the muxy-app/tap, and that the skills you intend to use exist under Muxy/Resources/skills in the repository. The extension API is the part that decides long-term value, and it is the part the README describes least.

Frequently asked questions

Official sources

1. License: MIT
2. muxy-app/muxy on GitHub
3. Project website
4. README
5. Releases