cmuxLayer

Name: cmuxlayer
Author: EtanHey

AI 에이전트들은 서로의 터미널을 볼 수 없습니다. 하나는 탭 1에서, 다른 하나는 탭 2에서 실행되며, 당신이 그 사이에서 클립보드 역할을 해야 합니다. cmuxLayer가 이 문제를 해결합니다: AI 에이전트에게 터미널 워크스페이스에 대한 프로그래밍 방식의 제어 권한을 부여하는 22개의 MCP 도구를 제공합니다.

install License MCP Tools Tests

빠른 시작

npm install -g cmuxlayer

cmux가 실행 중이어야 합니다.

MCP 설정(Claude Code, Cursor, VS Code, Claude Desktop)에 추가하세요:

{
  "mcpServers": {
    "cmux": {
      "command": "cmuxlayer"
    }
  }
}

설정 위치: Claude Code .mcp.json 또는 claude mcp add cmuxlayer -s user -- cmuxlayer | Cursor .cursor/mcp.json | VS Code .vscode/mcp.json | Claude Desktop — 플랫폼별 경로는 MCP 문서를 참조하세요.

무엇을 할 수 있나요?

AI 에이전트에게 다음과 같이 지시할 수 있습니다:

"오른쪽으로 창을 분할하고 거기서 테스트 스위트를 실행해"
"새 창에서 Claude Code 에이전트를 생성하여 auth.ts를 리팩토링해"
"surface:2의 화면을 읽고 빌드가 통과했는지 알려줘"
"모든 에이전트가 완료될 때까지 기다렸다가 출력을 읽어"
"사이드바 상태를 설정하여 배포 진행 상황을 보여줘"

내부적으로 cmuxLayer는 터미널 제어, 화면 읽기 및 다중 에이전트 오케스트레이션을 위한 22개의 MCP 도구를 노출합니다. read_screen은 Claude Code, Codex, Gemini, Cursor 및 Kiro에 대한 에이전트 메타데이터(상태, 모델, 토큰, 컨텍스트 %)를 파싱합니다.

MCP 도구 (22개)

모든 도구는 자동 안전 정책 적용을 위한 ToolAnnotations와 함께 제공됩니다.

터미널 제어 — new_split send_input send_key read_screen rename_tab close_surface browser_surface

에이전트 수명 주기 — spawn_agent send_to_agent wait_for wait_for_all interact stop_agent kill

워크스페이스 — list_surfaces list_agents my_agents get_agent_state read_agent_output notify set_status set_progress

읽기 전용 (6개)

도구	기능
`list_surfaces`	모든 워크스페이스의 표면 목록 나열
`read_screen`	파싱된 에이전트 상태와 함께 터미널 출력 읽기
`get_agent_state`	추적 중인 에이전트의 전체 상태
`list_agents`	선택적 필터가 포함된 모든 에이전트
`my_agents`	실시간 화면 상태를 포함한 부모 에이전트의 자식들
`read_agent_output`	구분 기호 사이의 구조화된 출력

변경 가능 (13개)

도구	기능
`new_split`	터미널 또는 브라우저 분할 창 생성
`send_input`	표면에 텍스트 전송
`send_key`	키 입력 전송 (return, escape, ctrl-c 등)
`rename_tab`	표면 탭 이름 변경
`notify`	cmux 알림 배너 표시
`set_status`	사이드바 상태 키-값 쌍 설정
`set_progress`	진행률 표시기 설정 (0.0-1.0)
`browser_surface`	브라우저 표면과 상호 작용
`spawn_agent`	새 창에서 CLI 에이전트 생성
`send_to_agent`	실행 중인 에이전트에 프롬프트 전송
`wait_for`	에이전트가 대상 상태에 도달할 때까지 차단
`wait_for_all`	여러 에이전트가 완료될 때까지 차단
`interact`	대화형 입력 전송 (확인, 취소, 재개)

파괴적 (3개)

도구	기능
`close_surface`	터미널 또는 브라우저 창 닫기
`stop_agent`	에이전트를 정상적으로 중지
`kill`	에이전트 프로세스 강제 종료

지원되는 에이전트

CLI	명령어	자동 감지
Claude Code	`claude`	상태, 모델, 토큰, 컨텍스트 %
Codex	`codex`	상태, 모델
Gemini CLI	`gemini`	상태, 모델
Cursor	`cursor agent`	상태
Kiro	`kiro-cli`	상태

read_screen은 에이전트 유형을 자동 감지하고 터미널 출력에서 메타데이터를 파싱합니다.

아키텍처

AI Agent  ─── MCP ───>  cmuxLayer  ─── Unix socket ───>  cmux
                         ├── Agent engine (spawn → monitor → teardown)
                         ├── Screen parser (5 agent formats)
                         ├── Mode policy (autonomous vs manual)
                         └── State manager + event log

소켓 클라이언트는 Unix 소켓을 통해 cmux에 연결됩니다. 연결이 끊기면 자동으로 재연결되며, 소켓을 사용할 수 없는 경우 CLI 하위 프로세스로 대체됩니다.

연결	지연 시간	속도 향상
CLI 하위 프로세스	~142ms	기준
Unix 소켓	~0.1ms	1,423배

문제 해결

cmux가 실행 중이지 않음 cmuxLayer는 실행 중인 cmux 인스턴스가 필요합니다. 먼저 설치하고 cmuxLayer를 사용하기 전에 cmux 세션을 시작하세요.

Claude Code에 도구가 나타나지 않음 MCP 설정을 추가한 후 Claude Code를 다시 시작하세요. claude mcp list를 실행하여 cmuxlayer가 연결되었는지 확인하세요.

소켓 연결 실패 cmuxLayer는 cmux 소켓을 자동으로 검색합니다(macOS: ~/Library/Application Support/cmux/cmux.sock). 필요한 경우 CMUX_SOCKET_PATH로 재정의하세요.

테스트

npm test            # 335 tests via vitest
npm run typecheck   # Type checking

개발

npm install
npm run dev         # Run with tsx (hot reload)
npm run build       # Compile TypeScript
npm start           # Run compiled output

기여

개발 설정 및 PR 가이드라인은 CONTRIBUTING.md를 참조하세요.

라이선스

Apache 2.0 — LICENSE를 참조하세요.

Golems AI 에이전트 생태계의 일부입니다. cmuxlayer.etanheyman.com | @EtanHey 제작.

cmuxlayer