Purplemux

한국어 · English

Claude Code / Codex에서 로컬 purplemux(subicura의 tmux + LLM 워크스페이스 매니저)를 제어하는 MCP 서버다. 워크스페이스·탭·터미널·(Electron)브라우저·서브에이전트 오케스트레이션을 23개 툴로 다룬다.

purplemux CLI는 localhost HTTP API를 감싼 얇은 래퍼일 뿐이라, 이 서버는 그 API를 MCP 툴로 그대로 노출한다(CLI로 셸아웃하지 않고 HTTP를 직접 호출). 그래서 에이전트가 터미널을 오케스트레이션하고, 나아가 Claude·GPT 계열을 넘나드는 크로스 LLM 서브에이전트(다른 AI-CLI 세션)까지 직접 운전할 수 있다.

Node ≥ 20 + 같은 호스트에 purplemux 실행이 필요하다.

---

왜 만들었나 — 크로스 LLM · 구독형 CLI를 서브에이전트로

이 프로젝트의 진짜 목적은 tmux(purplemux) 위에서 돌아가는 구독형 CLI(claude-code, codex-cli)를, 서로 다른 LLM을 넘나드는(크로스 LLM) 서브에이전트로 부려먹는 것이다.

• 크로스 LLM 오케스트레이션. 하나의 오케스트레이터가 Claude 계열(claude-code)과 GPT 계열(codex-cli)을 동시에 서브에이전트로 띄워 쓸 수 있다. 같은 문제를 서로 다른 모델에 던져 **교차 검증·합의(consensus)**를 시키거나, 강점이 다른 모델에 작업을 라우팅하는 식으로 — 한 모델 계열에 갇히지 않는다.

• 구독 정액 활용. 서브에이전트를 API로 붙이면 토큰 종량 과금이 붙지만, Claude Code(Claude 구독)·Codex CLI(ChatGPT/Codex 구독)는 정액 구독으로 돌아가는 대화형 세션이다. 이 세션들을 워커로 재활용한다.

• 다리 역할. purplemux는 이 구독형 CLI들을 각각 tmux 페인(탭)으로 띄워 주고, 그걸 제어할 로컬 HTTP API를 갖고 있다. 이 MCP가 그 API를 열어주는 다리다. 오케스트레이터(예: 지금 이 Claude Code)가 →

  1. pmux_agent_start로 claude/codex CLI를 탭에 런치하고 (훅 주입 + 부트 검증까지 자동)
  2. pmux_agent_wait_ready로 부트스트랩 echo 완료 증거를 확인하고
  3. pmux_agent_turn으로 턴 단위 작업을 던져 응답을 무손실 회수하고
  4. pmux_close_tab으로 정리한다.

  pmux_create_tab(claude-code/codex-cli 타입) + pmux_send_input 조합은 서브에이전트 실행 경로가 아니다 — 그 panelType은 UI 패널이라 빈 셸일 수 있고, readiness·응답 회수를 아무도 관리하지 않는다. 저수준 툴은 일반 터미널 작업과 수동 폴백 전용.

즉 여러 LLM의 구독 CLI 세션을 "호출 가능한 워커 에이전트"로 바꿔 팬아웃(fan-out) 오케스트레이션을 하는 게 핵심 시나리오다. 여러 탭에 작업을 나눠 병렬로 돌리고, 상태를 폴링하고, 서로 다른 모델의 결과를 합치는 흐름 전체를 자연어 지시로 굴릴 수 있다.

참고: 이 저장소 자체도 그 정신으로 만들어졌다 — 추출→설계→작업→리뷰→테스트 5단계를 각각 크로스 LLM 3개 서브에이전트(Claude Sonnet / Claude Opus / Codex gpt-5.5-high)의 합의로 진행했다. 서로 다른 모델이 교차 검증한 덕에 실제로 한쪽만으론 놓쳤을 것들(예: send 자동 제출 동작, 포트 인젝션 토큰 유출)을 잡아냈다.

---

빠른 시작

# 1. purplemux 실행 중이어야 함 (서버가 ~/.purplemux/{port,cli-token}을 기록)
# 2. 빌드
npm install && npm run build            # -> dist/index.js

# 3. 등록 (절대경로)
claude mcp add purplemux -s user -- node "$PWD/dist/index.js"
codex  mcp add purplemux        -- node "$PWD/dist/index.js"

Claude Code / Codex 세션을 재시작하면 pmux_* 툴이 뜬다. 포트·토큰은 호출마다 ~/.purplemux/에서 자동으로 읽으므로(캐시 없음), purplemux를 재시작하거나 포트가 바뀌어도 이 서버는 재시작할 필요가 없고 일반 환경에선 env 설정도 필요 없다.

---

툴 (23개)

에이전트 오케스트레이션 (v2 — 권장 진입점): pmux_agent_start · pmux_agent_wait_ready · pmux_agent_send · pmux_agent_capture · pmux_agent_status · pmux_agent_turn

claude/codex를 훅 주입으로 부팅해(purplemux 네이티브 cliState/command 상태 채널 활용) readiness·busy를 결정론적으로 판정하고, 부트 검증(SessionStart 부트 신호 + bootstrap echo)으로 "프로세스가 떴고 모델이 실제로 응답했다"는 증거를 확보한 뒤, 응답은 파일 프로토콜(req 신원 + EOF 커밋 이중 게이트)로 무손실 회수한다. pmux_agent_turn은 send→폴링→회수를 턴당 1콜로 묶은 복합 툴. 설계·근거: docs/worklog-20260707-workflow/design-v2.md, design-v22.md, worklog/plan-boot-signal-echo.md

터미널/탭 (headless에서도 동작): pmux_list_workspaces · pmux_list_tabs · pmux_create_tab · pmux_get_tab · pmux_send_input · pmux_tab_status · pmux_capture_pane · pmux_close_tab

브라우저 (Electron 필요): pmux_browser_url · pmux_browser_screenshot · pmux_browser_console · pmux_browser_network · pmux_browser_network_body · pmux_browser_eval

메타/유틸: pmux_guide(이 서버의 오케스트레이션 가이드 — LLM 셀프 문서) · pmux_api_guide(purplemux HTTP API 레퍼런스) · pmux_connection_info(토큰값은 절대 노출 안 함)

접속하는 LLM에는 MCP instructions로 툴 계층·골든 패스가 initialize 시점에 자동 전달되고, 상세 가이드(실패 모드·복구 패턴 포함)는 pmux_guide 한 번으로 회수할 수 있다.

pmux_send_input은 자동 제출된다(서버가 Enter를 침) — 개행을 붙이지 말 것. trailing \n 1개는 자동 제거된다. 브라우저 툴은 headless(비 Electron) purplemux에서 503을 반환하고, web-browser 탭 생성 직후엔 409 "not attached yet"(잠시 후 재시도)가 날 수 있다.

claude/codex CLI를 pmux_agent_*로 서브에이전트로 부리는 cookbook을 포함한 전체 기능·설치 옵션·사용 예시: docs/USAGE.md.

---

개발 / 테스트

npm run build && npm run typecheck
npm run smoke     # handshake + 23툴 + 라이브 list_workspaces
npm run unit      # 순수 함수 단위테스트 (fixture 기반)
npm run e2e       # 실행 중 purplemux 대상 라이브 라운드트립 12케이스

---

구조

src/            # config, http, errors, schemas, tools, agents, boot, guide, pane, paths, profiles, index
test/           # smoke + 라이브 e2e (Node, 프레임워크 없음)
docs/
  USAGE.md               # 기능 · 설치 · 사용법
  01-cli-features.md     # purplemux CLI 추출 정본
  02-mcp-design.md       # MCP 서버 설계 정본
  worklog/               # 단계별 작업기록 (추출→설계→작업→리뷰→테스트)
  panel/                 # 3에이전트(Sonnet/Opus/Codex) 단계별 초안
  reference/             # 추출에 사용한 고정 입력(api-guide 등)

---

어떻게 만들었나

추출 → 설계 → 작업 → 리뷰 → 테스트 5단계. 각 단계를 세 서브에이전트(Claude Sonnet, Claude Opus, Codex gpt-5.5-high)의 합의로 통과시키고, 이견은 오케스트레이터가 라이브 서버 실측으로 판정했다(예: send 자동 제출 동작 확정, 리뷰 단계에서 포트 인젝션에 의한 토큰 유출 취약점 발견·차단). 자세한 내용은 docs/worklog/.

---

라이선스

MIT (이 서버). purplemux는 subicura의 별도 프로젝트다.