LLM Wiki

muxy-app/muxy — SwiftUI·libghostty 기반 macOS 터미널과 에이전트 확장 플랫폼

Properties3
descriptionMuxy는 libghostty 터미널, Git worktree·세션, AI 에이전트 CLI·확장 API, 모바일 원격 제어를 한 macOS 앱에 묶은 오픈소스 프로젝트다.
tagsdev-tools, ai-agents, macos, open-source, cli
aliasesMuxy, muxy

14 min read

개요

Muxy는 SwiftUI로 만든 macOS용 터미널 애플리케이션이다. 터미널 렌더링은 libghostty와 Metal 레이어에 의존하고, 그 위에 프로젝트·Git worktree·탭·분할 pane·브라우저·확장·AI 에이전트 상태·모바일 원격 제어를 하나의 작업공간으로 결합한다. 저장소 README는 “가볍고 메모리 효율적인 터미널”이라고 소개하지만, 이 문서에서는 그 마케팅 표현을 독립 벤치마크로 검증하지 않았다.

현재 스냅샷

항목확인값
저장소muxy-app/muxy
최신 확인 커밋a3be0ce — Resolve agent tab provider icons from hook state
언어 / 라이선스Swift / MIT
요구사항macOS 14+, Swift 6.0+
GitHub Stars / Forks2,141 / 180
Open issues50
저장소 크기(API)12,613 KB
GitHub API 갱신 / push2026-08-04 22:59:51Z / 2026-08-04 23:16:41Z
캡처 시각2026-08-05 08:25~08:27 KST

공식 확인 — 제품 표면

README가 열거하는 기능은 프로젝트 그룹, 세로 탭, split pane, Git worktree, 빠른 열기·command palette, 구문 강조 텍스트 편집기, Mermaid를 포함한 Markdown/HTML 미리보기, 이미지 뷰어, 확장, iOS·Android companion 앱, 이미지 첨부가 가능한 rich input, 음성 입력, 알림, 490개 이상의 테마, 50개 이상의 단축키, workspace·session persistence, 그리고 단축키로 띄우는 Quick Terminal이다. 기능 목록은 README의 제품 주장으로 보존했으며, 각 기능을 이 환경에서 실행해 검증한 것은 아니다.

구현 구조

Swift Package 구성

Package.swift 기준 macOS 14용 Swift 6 패키지이며, 주요 타깃은 다음과 같다.

계층역할
MuxySwiftUI 앱 본체; GhosttyKit, MuxyShared, MuxyServer, MuxySessionProtocol 및 Sparkle/Yams/Sentry 사용
GhosttyKitGhosttyKit C 브리지와 libghostty 내부 정적 라이브러리 연결
MuxyShared앱·서버·확장 호스트가 공유하는 타입
MuxyServer모바일/원격 서버 계층
MuxySession / MuxySessionProtocol백그라운드 터미널 세션 daemon과 프로토콜
MuxyExtensionHost확장 background JavaScript 실행 호스트; Foundation·JavaScriptCore 링크
MuxyHookKit / MuxyHookBridgeAI provider hook 브리지
MuxyTests앱·공유·서버·세션·확장 호스트·hook kit 테스트 타깃

외부 의존성은 Sparkle 2.9.1, Yams 5.1+, Sentry Cocoa 8.40+이며, 앱·테스트 타깃은 AppKit, Metal, MetalKit, Speech, UserNotifications, sqlite3 등 macOS 프레임워크와 GhosttyKit.xcframework/.../ghostty-internal.a를 직접 링크한다. 이 구조는 네이티브 macOS 통합과 기능 폭을 얻는 대신, GhosttyKit 배포 산출물과 macOS 빌드 환경에 강하게 결합된다.

작업공간 상태 모델

MuxyApp는 AppState, ProjectStore, WorktreeStore, ProjectGroupStore, RemoteDeviceStore, 브라우저 profile/history store를 초기화하고 SwiftUI environment로 주입한다. 시작 시 저장된 선택 상태와 workspace를 복원하고, deferred service 단계에서 업데이트, offline terminal service, AI provider hook 설치, notification socket, extension lifecycle을 연결한다.

WorkspaceReducer는 프로젝트·worktree 선택/삭제, 탭 생성·선택·닫기, command/extension/browser/session 탭, pane split·이동·focus, top-level tab 이동, layout 적용을 하나의 action reducer와 side-effect 구조로 관리한다. 따라서 Muxy의 핵심은 “터미널 여러 개를 띄우는 앱”보다 프로젝트/worktree를 기준으로 터미널·브라우저·확장 surface를 조합하는 작업공간 런타임에 가깝다.

터미널과 세션

공식 terminal 문서는 Muxy의 터미널이 libghostty를 Metal 레이어에서 실행한다고 설명한다. 백그라운드 세션을 켜면 muxy-session daemon이 실제 PTY를 소유하고, 앱 표면은 Unix socket으로 attach client를 통해 바이트·창 크기·종료 상태를 중계한다. 세션 ID는 workspace snapshot에 저장되고, 재실행 시 pane별 세션을 재연결하며 최근 최대 256KB 출력을 replay한다. 이 환경에서는 실제 daemon 재연결이나 앱 복구 동작을 실행하지 않았다.

Quick Terminal은 Double Shift 또는 Carbon global hotkey backend를 선택할 수 있고, Double Shift의 system-wide 감지는 Input Monitoring 권한을 요구한다. 홈 디렉터리에서 시작해 숨겨져도 같은 shell·cwd·history를 유지하며, README가 설명하는 notch/dynamic-island 형태는 macOS 화면 조건에 의존한다.

Git worktree 서비스는 git worktree list --porcelain, add, remove, prune, rev-parse를 actor 안에서 실행하고, branch 이름을 허용 문자 집합으로 검증한다. 로컬 repository probe에는 동시성 제한과 10초 timeout이 있다.

AI 에이전트와 확장 표면

AI provider 통합

코드의 AIProviderRegistry에는 Claude Code, OpenCode, Codex, Cursor, Copilot, Droid, Pi, Grok provider 구현이 기본 등록되어 있다. provider마다 실행 파일 탐색, hook script, 설정 경로, 설치/제거/검증을 추상화하며, hook resource를 stage한 뒤 provider별 reconcile·config watcher·실행 파일 discovery를 수행한다. 터미널 process detection과 Agents Focused layout은 실행 중인 에이전트를 worktree/pane 단위로 표시하는 기반이다.

이것은 “지원 목록과 통합 경로가 코드에 존재한다”는 확인이지, 각 provider의 실제 설치·로그인·hook 동작이 이 캡처 환경에서 성공했다는 뜻은 아니다. 또한 README의 npx skills add 예시는 Muxy workspace를 shell에서 운전하는 muxy-cli skill과 확장을 만드는 muxy-extension skill을 제공한다는 제품 표면을 보여준다.

muxy CLI

공식 문서에 따르면 CLI는 실행 중인 Muxy 앱과 local Unix socket으로 통신한다. 프로젝트·workspace·worktree를 열고 전환하거나 만들 수 있고, pane split·pane 목록·탭 탐색·브라우저 자동화·pane 입력 전송·화면 출력 읽기·pane 닫기/이름 변경·백업 import/export를 shell/자동화 스크립트에서 수행한다. MUXY_PANE_ID를 사용하면 Muxy pane 안에서 실행한 split 명령이 현재 pane을 자동으로 기준으로 삼는다.

CLI는 Muxy 앱이 열려 있어야 하는 명령이 있고, extension API와 달리 문서상 “unidentified client”로 처리되어 extension manifest permission gate 대상이 아니다. 따라서 CLI 사용자는 로컬 사용자 자신이 실행하는 자동화 경계로 보고, extension 권한 모델과 동일하다고 가정하면 안 된다.

확장 시스템

확장은 npm + Vite 프로젝트이고 npm run build가 만든 dist/만 배포·설치된다. package.json의 top-level name/version과 muxy manifest를 읽으며, manifest에는 background script, events, permissions, tab types, file openers, panels, popovers, sidebar, topbar/status-bar items, settings, remote methods, marketplace 정보가 들어갈 수 있다.

  • main process의 ExtensionStore가 ~/.config/muxy/extensions/<name>/package.json을 스캔한다.
  • 선언된 UI는 WKWebView와 주입된 window.muxy bridge를 사용한다.
  • 선택적인 background.js는 MuxyExtensionHost 별도 프로세스에서 실행된다.
  • muxy.exec, panes.send, panes.sendKeys, panes.readScreen, Git/file write, http.fetch, remote method는 manifest permission 외에 runtime consent를 요구한다.
  • 사용자가 허용/거부를 기억하는 grant와 audit log를 남기고, consent prompt가 60초 동안 응답되지 않으면 자동 거부한다.
  • extension process crash는 Settings에 표시되고 앱 본체와 분리된다.

이 설계는 “웹 확장 API가 곧 로컬 shell 권한”이 되지 않도록 선언 권한·실행 시 동의·감사 로그를 겹친다. 반면 permission group은 아직 coarse-grained이며, extension이 가진 기능 범위가 넓어질수록 manifest와 runtime prompt를 함께 검토해야 한다.

모바일·원격 제어

Muxy는 local network에서 mobile companion, dashboard, custom integration이 접속할 수 있는 WebSocket 서버를 내장한다. 공식 문서 기준 기본 포트는 4865(development build 4866), Bonjour 서비스명은 _muxy._tcp, JSON/UTF-8 프로토콜을 사용한다. 서버는 기본적으로 꺼져 있고, 설정에서 활성화한 뒤 모든 client가 인증·pairing을 거쳐야 RPC를 사용할 수 있다. 구현상 포트가 사용 중이면 기존 listener를 정리하고, 실패 원인을 사용자용 메시지로 표시한다.

원격 표면은 프로젝트·worktree·workspace·notification·terminal cell·파일·logo와 pane take-over 흐름을 노출한다. 네트워크 서버를 켜는 순간의 노출 범위와 승인된 device 상태는 별도 운영 책임이며, 이 캡처에서는 모바일 클라이언트 연결을 실제로 시험하지 않았다.

설치·빌드 경로

README가 제시하는 공식 경로는 다음과 같다.

brew tap muxy-app/tap
brew install --cask muxy
 
scripts/setup.sh          # GhosttyKit.xcframework 다운로드
swift build               # debug build
swift run Muxy             # 실행
scripts/checks.sh         # format, lint, build, test

swift build와 scripts/checks.sh는 이 조사에서 실행하지 않았다. 따라서 문서에 적힌 요구사항과 저장소 구성은 확인했지만, 현재 macOS 호스트에서 실제 빌드·테스트·앱 실행이 통과한다고 보고하지 않는다.

판단과 한계

매력적인 지점

  1. Ghostty의 네이티브 터미널 렌더링과 SwiftUI workspace UI를 한 앱 안에 묶는다.
  2. Git worktree·project group·workspace·session persistence가 AI 코딩 작업의 병렬 작업 표면과 직접 연결된다.
  3. CLI, extension bridge, provider hook, remote server가 동일한 workspace state를 서로 다른 자동화 진입점으로 노출한다.
  4. extension에는 permission + runtime consent + audit log + process isolation이 있어 단순한 무제한 plugin 모델보다 통제면이 분명하다.
  5. Muxy CLI와 muxy-cli skill은 터미널을 UI가 아닌 에이전트가 호출할 수 있는 실행 표면으로 만든다.

확인해야 할 리스크

  • macOS 14+와 Swift 6, AppKit/Metal/Speech/SQLite, GhosttyKit binary에 묶여 있어 크로스플랫폼 도구가 아니다.
  • GhosttyKit.xcframework를 내려받는 setup 단계와 내부 정적 라이브러리 링크가 재현 가능한 빌드의 핵심 전제다.
  • README의 “lightweight/memory efficient”, “490+ themes”, “50+ shortcuts” 및 provider 지원은 캡처 시점의 프로젝트 주장/코드 범위이며, 성능·완성도·호환성을 독립적으로 벤치마크하지 않았다.
  • 원격 서버, extension shell/file/Git/browser 호출, terminal read/send는 유용한 만큼 승인·감사·네트워크 노출을 운영자가 직접 관리해야 한다.
  • 2026-08-04에 push된 빠르게 변하는 저장소이므로 기능과 수치는 이후 커밋에서 달라질 수 있다.

관련 노트

출처 및 검증 자료

조사 범위: GitHub API metadata, pinned README, 저장소 tree(1,740 entries / 927 Swift files), Package.swift, 앱·workspace·AI provider·extension·Git worktree·Quick Terminal·mobile server 구현 파일, 공식 docs 일부. 실제 앱 빌드·테스트·provider 로그인·모바일 연결은 실행하지 않음.

백링크