URC——通用遥控器
通过手机上的Claude应用程序控制Codex和Gemini。
你知道 /remote-control --Claude Code功能允许您从手机上的Claude应用程序控制会话。URC做到了 通用的一个命令，你的手机就能控制Codex。另一个命令，它控制着双子座。同样的应用程序，同样的对话，同样的界面。没有额外的API密钥。没有额外的应用程序。```bash
/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`
- 双子座：看 github.com/google-gemini/gemini-cli
### 安装```bash
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内部）：```bash
/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.md |
克劳德代码 | 代理说明 |
AGENTS.md |
食品法典 | 代理说明 |
GEMINI.md |
Gemini | 代理说明 |
.claude/agents/ |
Claude Code | RC Bridge代理定义 |
.claude/skills/ |
克劳德代码 | /urc 命令 |
.claude/hooks/ |
Claude代码 | 会话热度+收件箱挂钩 |
.agents/skills/ |
Codex | Codex桥接技能 |
插件系统```
.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消息传递（休眠）
词汇表
| 术语 | 它意味着什么 |
|---|---|
| 遥控器 | Claude Code功能，允许您从手机上的Claude应用程序控制会话 |
| 主控程序 | 模型上下文协议——人工智能代理如何与外部工具和服务通信 |
| 俳句 | 克劳德最快的模型——用于中继，因为它只是传递信息 |
| 终端复用器 | 终端多路复用器——在一个窗口的窗格中运行多个会话 |
| 窗格 | tmux内部的终端会话，由ID标识，如 %875 |
| 推 | 转弯完成时，从目标窗格返回中继的响应传递 |
故障排除
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错误引起的：
CLAUDE_CODE_REMOTE（为所有RC会话内部设置）禁用5分钟WebSocket保活CLAUDE_CODE_REMOTE_SEND_KEEPALIVES（替换）是重计数门控的——仅在活动模型处理期间发送保活消息，而在空闲期间不发送- 结果：空闲的RC会话没有保活机制，服务器会注销它们
对URC的影响： 中继会话在大约20分钟的不活动后会失去电话连接。中继进程保持活动状态，但手机显示“已断开连接”/“未知网络错误”
状态： 提交了带有完整源代码分析的Bug报告。在实施变通方案之前等待Anthropic的回应。看门狗（重置服务器端定时器的周期性活动）是已知的解决方法，但在上游明确之前被推迟。
已知限制
- 双子座自动重连赛：
send.sh报告delivered一块垂死的玻璃。下一条消息会触发重新连接。 - 快速注射表面： 中继通过bash变量传递电话消息
send.sh。风险低（手机用户是机器所有者），但内容没有经过消毒。 - 基于提示的功能没有自动测试： 推送归因、自动重新连接和健康仪表板是代理提示中的行为指令，而不是可执行代码。
许可证
麻省理工学院
