Universal Remote Control

URC——通用遥控器

通过手机上的Claude应用程序控制Codex和Gemini。

URC Demo — orchestrating Codex and Gemini from the Claude App

你知道 /remote-control --Claude Code功能允许您从手机上的Claude应用程序控制会话。URC做到了 通用的一个命令，你的手机就能控制Codex。另一个命令，它控制着双子座。同样的应用程序，同样的对话，同样的界面。没有额外的API密钥。没有额外的应用程序。

/urc codex    # Your phone now controls Codex
/urc gemini   # Your phone now controls Gemini

在幕后，URC生成了一个轻量级的Haiku中继，它充当了一个纯粹的传递——你的消息原封不动地传递，输出逐字逐句地返回。继电器是自我管理的：它会自动清除，在目标死亡时自动重新连接，并在没有干预的情况下无限期运行。

特性

每个CLI的电话控制

• 只需一个命令，即可从手机桥接任何Codex或Gemini窗格
• 生成新窗格或桥接现有窗格(/urc 875)
• 也从对方开始搭建桥梁（Codex技能或双子座 /rc 命令）

自我管理继电器

• 在25次发送时自动清除——重新发送，恢复电话连接，重置计数器
• 目标死亡时自动重新连接——生成替换，重试您的消息（3次尝试）
• 类型 “状态” 检查容量、目标健康状况和重生计数
• 没有手动维护，没有 /clear，不重新启动

实时可见性

• 推送归因显示谁发送了每条消息以及询问了什么
• 当目标收到您的消息时，立即“收到消息”确认
• 完成后，响应会流式传输回您的手机

$0中继模式

• 类型 >codex: message 或 >gemini: message 用于基于钩子的穿透
• 零模型调用，零成本 UserPromptSubmit 吊钩手柄调度
• 设置： bash urc/core/relay-ctl.sh add codex %NNN && bash urc/core/relay-ctl.sh on

跨CLI协调

• 11工具MCP服务器，用于窗格级通信（调度、读取、注册、心跳、消息传递）
• Claude Code、Codex和Gemini的代理可以发送消息、共享工作和协调
• 5层收件箱通知堆栈确保没有遗漏任何消息

经过测试和验证

• 10个测试套件中的160个断言
• 23检查插件验证
• 输入后卡住输入检测，提高TUI可靠性

快速开始

先决条件

• 终端复用器: brew install tmux （macOS）或 sudo apt install tmux （Linux）
• Python 3.10+, jq
• Claude 代码命令行界面: curl -fsSL https://claude.ai/install.sh | bash
• 克劳德·马克斯计划 （有关电话控制，请参阅 claude.com/pricing)
• Codex 命令行界面 和 双子星命令行工具 （可选--安装您想桥接的任何一个）

- 食品法典： npm install -g @openai/codex - 双子座：看

安装

tmux new -s urc                # Start a tmux session (required)
git clone https://github.com/siddharthkandan/universal-remote-control
cd universal-remote-control
./setup.sh                     # Detects your CLIs, generates configs

或者安装为Claude Code插件：

/plugin marketplace add siddharthkandan/universal-remote-control
/plugin install urc

用它

来自克劳德代码（tmux内部）：

/urc codex                    # Spawn Codex pane + bridge it to your phone
/urc gemini                   # Spawn Gemini pane + bridge it to your phone
/urc 875                      # Bridge an existing pane by ID
/urc                          # List unbridged panes

打开 手机上的Claude应用程序 --继电器自动激活远程控制。键入一条消息，它会直接发送到Codex或Gemini。响应在完成时返回。

别名： /rc-bridge, /rc-any, /rc-relay 所有工作。

你也可以从另一边过桥：

• 来自Codex： 激活 rc-bridge 技能
• 双子座： 类型 /rc

您的Claude计划涵盖Haiku继电器-不需要单独的API密钥。

Gemini设置说明

Gemini CLI需要额外的配置 setup.sh 生成：

• setup.sh 自动创建项目配置和策略规则
• 如果 ~/.gemini/settings.json 有一个 tools.allowed 白名单，删除 "tools" 块
• 验证： gemini mcp list （会议外）或 /mcp list （会议中）
• 注：双子座 /tools 命令故意隐藏MCP工具——不要用它来检查

运作原理

Phone (Claude App)
    |  Remote Control
    v
Haiku Relay (rc-bridge agent)        ← self-managing, auto-clears at 25 sends
    |  send.sh              push files
    |  (dispatch) ←———————— (response)
    v                           |
Target pane (tmux)              |
    |  hook.sh fires ———————————┘    ← captures response, writes push file

中继是一种无状态的直通。 状态位于tmux窗格选项中(@bridge_target, @bridge_cli, @bridge_relays).调度和响应读取通过 UserPromptSubmit 钩子(bridge-push-hook.sh)--中继的电话信息触发钩子，钩子通过以下方式发送 send.sh 并读取任何待处理的推送文件，而无需消耗模型回合。当目标完成其转弯时， hook.sh 捕获响应并写入推送文件。中继器会在下次唤醒时接收到它，并将其显示在您的手机上。

MCP服务器 (urc-coordination，11个工具）提供跨窗格基础设施：通过SQLite发送消息、读取窗格输出、注册代理、跟踪心跳以及发送/接收异步消息。任何CLI中的任何代理都可以使用这些工具与其他代理进行协调。

第二台MCP服务器(urc-teams，17个工具）提供结构化的团队创建、键入消息和任务依赖关系。当前处于休眠状态——协调服务器处理所有活动消息。

项目结构

根目录包含特定于CLI的文件(CLAUDE.md, AGENTS.md, GEMINI.md，符号链接），因为每个AI CLI都有自己的发现指令的约定。所有实际代码都存在于 urc/.

核心(urc/)

urc/
├── core/
│   ├── server.py                 Coordination MCP server (11 tools)
│   ├── db.py                     SQLite foundation
│   ├── teams_protocol.py         Teams data layer (dormant)
│   ├── teams_server.py           Teams MCP server (dormant)
│   ├── send.sh                   Pane dispatch (bracketed paste + post-Enter verify)
│   ├── hook.sh                   Turn completion + push attribution + respawn
│   ├── wait.sh                   Blocking wait with self-wake
│   ├── dispatch-and-wait.sh      Atomic dispatch + wait + read
│   ├── cli-adapter.sh            CLI detection + paste behavior
│   ├── urc-spawn.sh              Fire-and-forget relay+target spawner
│   ├── urc-dispatch.sh           ! mode CLI dispatcher
│   ├── urc-status.sh             Fleet status display
│   ├── inbox-watcher.sh          Background inbox notification
│   ├── circuit.sh                Circuit breaker for dispatch failures
│   ├── relay-ctl.sh              $0 relay configuration
│   └── test-*.sh                 8 test suites (94 assertions)
├── lib/
│   └── state-write.sh            Atomic JSON write helper
└── schemas/
    └── response.md               Response file schema

CLI集成

插件系统

.claude-plugin/plugin.json           Plugin manifest
hooks/hooks.json                     Plugin hooks (Stop + SessionStart)
hooks/scripts/bridge-push-hook.sh    Hook-based dispatch + push reading (UserPromptSubmit)
hooks/scripts/plugin-setup.sh        Auto-setup on first session

文档

• 入门指南 --安装第一个网桥，tmux基础
• 架构概述 --系统设计和消息流
• 转弯完成系统 --吊钩信号排序和响应捕获
• 设计决策 --为什么东西是这样建造的
• 团队协议 --结构化跨CLI消息传递（休眠）

词汇表

故障排除

MCP工具未在Gemini中显示？ 跑 gemini mcp list。如果为空，请验证 ~/.gemini/policies/urc-mcp.toml 存在（由创建 setup.sh).删除任何 tools.allowed 白名单来自 ~/.gemini/settings.json.

中继显示“窗格不存在”？ 目标死了。键入“status”进行确认，然后使用新的窗格ID“重新连接%NNN”，或让自动重新连接处理它。

文本卡在窗格的输入字段中？ TUI时间边缘案例。 send.sh 在大多数情况下会自动重试。如果仍然卡住，请手动按Enter键。

setup.sh venv创建失败？ 需要Python 3.10+。在某些系统上： sudo apt install python3.12-venv.

插件验证失败？ 跑 bash scripts/validate-plugin.sh 用于诊断。最常见的修复：重新运行 setup.sh.

已知问题

RC会话空闲超时（约20分钟）-- #32982

即使本地CLI进程处于活动状态，在大约20分钟的空闲时间后，远程控制会话也会在服务器端注销。这会影响所有人 /remote-control 会话（不仅仅是URC中继），是由Claude Code中的keepalive错误引起的：

1. CLAUDE_CODE_REMOTE （为所有RC会话内部设置）禁用5分钟WebSocket保活
2. CLAUDE_CODE_REMOTE_SEND_KEEPALIVES （替换）是重计数门控的——仅在活动模型处理期间发送保活消息，而在空闲期间不发送
3. 结果：空闲的RC会话没有保活机制，服务器会注销它们

对URC的影响： 中继会话在大约20分钟的不活动后会失去电话连接。中继进程保持活动状态，但手机显示“已断开连接”/“未知网络错误”

状态： 提交了带有完整源代码分析的Bug报告。在实施变通方案之前等待Anthropic的回应。看门狗（重置服务器端定时器的周期性活动）是已知的解决方法，但在上游明确之前被推迟。

已知限制

• 双子座自动重连赛： send.sh 报告 delivered 一块垂死的玻璃。下一条消息会触发重新连接。
• 快速注射表面： 中继通过bash变量传递电话消息 send.sh。风险低（手机用户是机器所有者），但内容没有经过消毒。
• 基于提示的功能没有自动测试： 推送归因、自动重新连接和健康仪表板是代理提示中的行为指令，而不是可执行代码。

许可证

麻省理工学院