Skip to main content
Glama

cmuxLayer

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

install License MCP Tools Tests

빠른 시작

npm install -g cmuxlayer

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

MCP 설정에 추가하세요:

Codex CLI / T3 Code

T3 Code는 ~/.codex/config.toml (또는 $CODEX_HOME/config.toml)에 있는 Codex CLI 설정 파일로부터 MCP 서버를 상속받습니다.

[mcp_servers.cmux]
command = "cmuxlayer"

Claude Code, Cursor, VS Code, Claude Desktop

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

설정 위치: Codex CLI / T3 Code ~/.codex/config.toml (또는 $CODEX_HOME/config.toml) | Claude Code .mcp.json 또는 claude mcp add cmuxlayer -s user -- cmuxlayer | Cursor .cursor/mcp.json | VS Code .vscode/mcp.json | Claude Desktop — 플랫폼별 경로는 MCP 문서를 참조하세요.

Related MCP server: hyperpanes-mcp

무엇을 할 수 있나요?

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

  • "창을 오른쪽으로 분할하고 거기서 테스트 스위트를 실행해"

  • "새 창에서 Claude Code 에이전트를 생성하여 auth.ts를 리팩토링해"

  • "surface:2의 화면을 읽고 빌드가 통과했는지 알려줘"

  • "모든 에이전트가 완료될 때까지 기다린 다음 출력을 읽어줘"

  • "사이드바 상태를 설정하여 배포 진행 상황을 보여줘"

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

MCP 도구 (26개)

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

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

에이전트 수명 주기 — spawn_agent send_to 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

구분 기호 사이의 구조화된 출력

변경 가능 (17개)

도구

기능

new_split

터미널 또는 브라우저 분할 창 생성

new_surface

기존 창에 탭 생성

move_surface

표면을 다른 창이나 위치로 이동

reorder_surface

창 내 탭 순서 변경

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

표면을 알지 못해도 추적 중인 에이전트에 텍스트 전송

send_to_agent

실행 중인 에이전트에 프롬프트 전송

wait_for

에이전트가 대상 상태(기본값 done)에 도달할 때까지 차단

wait_for_all

여러 에이전트가 완료될 때까지 차단

interact

대화형 입력 전송 (확인, 취소, 재개)

파괴적 (3개)

도구

기능

close_surface

터미널 또는 브라우저 창 닫기

stop_agent

에이전트를 정상적으로 중지

kill

에이전트 프로세스 강제 종료

지원되는 에이전트

CLI

명령어

자동 감지

Claude Code

claude

상태, 모델, 토큰, 컨텍스트 %

Codex

codex

상태, 모델, 컨텍스트 %

Gemini CLI

gemini

상태, 모델, 토큰, 컨텍스트 %

Cursor

cursor agent

상태, 모델, 토큰, 컨텍스트 %

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 세션을 시작하세요.

Codex CLI 또는 T3 Code에 도구가 나타나지 않음 ~/.codex/config.toml에 cmuxlayer를 추가한 후 클라이언트를 다시 시작하세요. 사용자 지정 Codex 홈을 사용하는 경우 $CODEX_HOME/config.toml에 동일한 mcp_servers.cmux 항목이 포함되어 있는지 확인하세요.

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

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

테스트

bun run test        # 406 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 제작.

Available Tools

10 tools
close_surfaceA
Destructive

Close one surface, managed agent, or workspace with live-agent guards. scope="agent" stops the agent AND closes its pane, and reports the two halves separately (agent_stopped, surface_closed) so a pane that survives is never reported as closed. The pane close obeys the same live-agent guard as scope="surface": without force:true a still-live agent keeps its pane, and the receipt says so.

Inputs: force, scope, surface, agent_id, +1 more. Returns: ok, pane, force, scope, +12 more

control_healthA
Read-onlyIdempotent

Report terse control-path health by default; pass detail=full for diagnostics.

Inputs: detail. Returns: ok, health, retry_count

list_agentsA

List live-derived agents, including registry-persisted prompt blockage and pause state; filter to blocked agents or children with mine/parent_agent_id. Default summary returns flat addressable scalars and hides close tombstones and failed spawns whose surfaces are absent; request a terminal state or detail=full to include them. Full detail also includes provenance, health diagnostics, the registry record, and up to 20 unresolved or attention delivery receipts.

Inputs: mine, repo, model, state, +5 more. Returns: ok, count, agents, derived_at, +1 more

list_surfacesA
Read-onlyIdempotent

List workspace, pane, and surface topology. Condensed by default; verbose=true adds raw cmux fields.

Inputs: verbose, workspace, preview_lines, include_screen_preview. Returns: ok, surfaces, workspaces, retry_count, +1 more

read_screenA
Read-onlyIdempotent

Read a terminal screen and parsed harness status. Use raw=true for full text or parsed_only=true for monitoring.

Inputs: raw, lines, surface, workspace, +3 more. Returns: ok, parsed, surface, retry_count

report_to_parentA

Raise a short blocker to this managed agent's registry parent. cmuxlayer chooses the parent; callers cannot address arbitrary agents. The blocker is durably appended to the parent's inbox and its pointer is actively delivered. If that wake fails, cmuxlayer alerts the nearest reachable ancestor and returns fallback provenance. A root agent has no parent and receives an error. Workers with collab_path must append there to reach their own parent lead; this tool refuses that upward route.

Inputs: blocker (required). Returns: ok, route, durable, delivery, +6 more

send_toA

Send text or a key through the shared delivery engine. send_to submits new messages. Key-Return supports pickers, menus, permission prompts, and recovery of this caller's exact typed draft on the same agent/session once the displayed unambiguous reset time passes or new harness output confirms recovery; the old refusal may stay visible. Exact /usage, /usage-credits or /rate-limit-options navigation is also guarded. Read the pane and receipt first; never retype or repeat accepted input. Every receipt includes caller_agent_id (null when unknown). Workers with collab_path cannot address their own parent or ancestor leads in any mode; append to that collab file instead. Unknown callers remain allowed. Lead-originated and engine-internal pushes remain allowed. Targets may be one agent, structured agent targeting, or a raw surface in surface/command/key mode; for shell commands use mode:command. Text success requires a verified submit or new matching queue proof. Otherwise ok=false with submit_unverified retains pending verification and ownership for retries without retyping. Verified text success returns only ok, target identity, delivery_id, delivery_state, submitted, caller_agent_id, and queued_behind_turn when applicable. Key success returns its key verification fields. Pass verbose=true for full diagnostics; failures always retain them.

Inputs: mode, text, target, surface, +13 more. Returns: ok, key, model, title, +37 more

spawn_agentA

Spawn a managed agent or terminal, or resume a captured agent on a fresh surface preserving its ID. Resume: {resume_agent_id:"..."}. Omit new-spawn fields: repo, cli, model, effort, cwd, prompt, boot_prompt_path, worktree, mcp_profile, role, placement, authority, collab_path, parent_agent_id, max_cost_per_agent; these cause INVALID_RESUME_SPEC. Optional resume controls such as force, workspace, focus, report_path and verbose remain supported. Resume restores session context; it does not resend a task. For a new task, check current readiness, then use send_to separately. ok:true/state:started means lifecycle started, not ready or task delivered. At a chooser or permission prompt, inspect the current frame with read_screen before acting; never blindly send Return or assume success. pending_verify leaves delivery unverified; follow wait_for guidance in warning when present; do not resend blindly. Placement is deterministic; boot_prompt_timeout_ms also bounds pane placement. Default successes have at most six fields: ok, agent_id, surface_id, state (spawn outcome), delivered (boot prompt), and optional warning. Use verbose:true for contract_path, report_path, done_marker, transport, worktree, and diagnostics; report_path and done_marker are also in the issued contract file. Failures always keep full detail.

Inputs: cli, cwd, repo, role, +25 more. Returns: ok, cwd, role, type, +26 more

update_surfaceB

Move or rename a surface, or adopt_session to rebind an existing managed Claude or Codex identity after a restart using pinned historical evidence and fresh process/topology proof. Adoption changes no pane or input; layout reconciliation follows separately.

Inputs: action (required), surface (required), cwd, pane, +20 more. Returns: ok, pane, title, action, +3 more

wait_forB

Block until one agent_id or every agent in ids reaches a target registry state and return health. Defaults to waiting for completion (done).

Inputs: ids, mine, watch, agent_id, +6 more. Returns: ok, typed, watch, results, +16 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool has a reasonably distinct purpose: spawn, send, list, close, read, wait, health, report. There is mild overlap between list_agents and list_surfaces (agents live on surfaces) and among the surface-touching tools (spawn_agent, update_surface, close_surface), but descriptions clarify the boundaries.

    Naming Consistency4/5

    Nearly all names are snake_case with a verb_noun or verb_prep pattern (control_health, spawn_agent, list_agents, update_surface, close_surface, list_surfaces, read_screen). Minor deviations are the prepositional forms send_to, wait_for, and report_to_parent, which are still readable and consistent in style.

    Tool Count5/5

    Ten tools is well within the ideal range and each covers a distinct facet of agent/surface orchestration. No redundant or filler tools appear; the set feels tightly scoped to the domain.

    Completeness4/5

    The surface covers the full lifecycle: spawn/resume, list, send, read, wait, update/adopt, close, report, and health. Coverage is strong, with only minor gaps such as no dedicated agent-state update beyond update_surface's adoption path.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Terminal MCP server for AI coding agents with persistent PTY sessions, ring-buffer incremental reads, headless xterm screen capture, multi-agent orchestration, and a real-time web dashboard.
      33 npm
      28
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for hyperpanes terminal workspace app, enabling AI agents to compose and launch workspace layouts, inspect and drive terminal panes, stream output, and orchestrate agent hierarchies.
      50
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server to control Onda terminal from AI agents, providing tools for splitting panes, running commands, managing tabs and workspaces, and orchestrating multi-agent workflows across multiple windows.
      39
      5 npm
      MIT