Skip to main content
Glama

cmuxLayer

你的 AI 代理无法看到彼此的终端。 一个在标签页 1 运行,另一个在标签页 2 运行——而你就是它们之间的剪贴板。cmuxLayer 解决了这个问题:它提供了 26 个 MCP 工具,让 AI 代理能够以编程方式控制终端工作区。

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

发送按键(回车、转义、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 中 将 cmuxlayer 添加到 ~/.codex/config.toml 后重启客户端。如果你使用自定义的 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

贡献

请参阅 CONTRIBUTING.md 获取开发设置和 PR 指南。

许可证

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

    ActivityActive
    ResponsivenessMostly unanswered

    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