README

Heeler




herdr 的原生 iOS 伴侣应用 —— herdr 是一个 agent 优先的终端运行时。










English | 简体中文 | 繁體中文 | 日本語



---

Heeler 是 iPhone 和 iPad 上独立的 herdr 移动客户端和 Agent 控制台，用于远程操作 Claude Code、Codex 和其他编程 Agent。Agent 在你自己的 Host 上通过 Herdr TUI 或 Herdr 桌面端（herdr-core）运行，Heeler 通过 SSH 连接。跨机器查看多个 Agent，按「谁需要你」排序，再打开实时终端或支持的 Chat 对话发送指令。

 截图

| Agent Console | 实时终端 | Chat |
| --- | --- | --- |
|  |  |  |

| Keyboard | Changes | Terminals |
| --- | --- | --- |
|  |  |  |

| Skills | Hosts | 实时活动 |
| --- | --- | --- |
|  |  |  |

| Usage | 小组件 | 锁屏小组件 |
| --- | --- | --- |
|  |  |  |



查看 iPad 截图

 功能

- Console —— 所有机器上的 Agent 汇成一个按状态排序的列表（Blocked
  排最前），可按 Host 过滤，实时更新。
- Herdr 桌面端与 herdr-core —— 连接 macOS、Linux 与 Windows 原生环境上的
  Herdr 桌面端或无界面 herdr-core。Console 跟随桌面端的空间与标签页，实时终端、
  Chat、Composer、New Agent 和 New Workspace 同样可用
  （了解更多）。
- Attach —— libghostty 渲染的 Agent 真实终端：原生历史回看、也能驱动全屏
  TUI 的惯性触摸滚动、长按选择、接管失效的终端占用者，并静默收集网页链接
  供稍后打开。
- Chat —— 以原生消息而不是终端画面阅读 Agent 的对话，在 Composer 里
  回复，并用按钮回答 Blocked 的 Agent；支持 Claude Code、Codex、Pi、
  Oh My Pi、Grok Build 和 OpenCode（了解更多）。
- Composer —— 在本地用完整的 iOS 键盘起草（自动纠错、输入法、听写），
  一次 Send 投递；工具键盘另有 Agent 控制键、Agent Skills、可复用的
  Snippets 和终端外观。
- Terminal —— 在 Agent 的目录打开普通 shell，带 Text / Keys 两种模式，
  每个工作区复用同一个 tab。
- 附件 —— 把照片或最大 64 MiB 的文件经 SFTP 暂存到 Host，并把路径
  插入草稿。
- 扫码配对 —— 扫描 Pairing Code 即可添加机器；密钥在设备上生成，私钥
  不离开 Keychain，配对码同时固定 host key 指纹。
- 通知 + 实时活动 —— Agent 进入 Blocked 或 Done 时的端到端加密推送，
  以及锁屏 / 灵动岛上实时跟踪 Agent 的横幅；中继永远读不到内容
  （PRIVACY.md）。
- Usage —— Claude Code 与 Codex 的 Usage Limits 及重置时间，以及最多
  30 天的 Token Usage 和估算 API 费用，可汇总所有 Host 或只看一台；主屏和
  锁屏小组件随时可见（了解更多）。
- Worktrees —— 让 Agent 从工作区仓库的干净检出上启动。
- 外观 —— 跟随系统 / 浅色 / 深色；30 个终端主题，浅色深色各有独立
  槽位；内置 JetBrains Mono 与 IBM Plex Mono；双指缩放字号。
- 跳板机 —— 经 SSH 跳板访问不可直连的机器，两跳各自校验密钥。

 连接原理

在 macOS 和 Linux Host 上，Heeler 通过 SSH 使用 herdr 的 JSON API：每个请求经 direct-streamlocal
通道直连 herdr.sock，一条长连接承载事件流，交互终端则在 SSH PTY 上运行
herdr agent attach --takeover。前提只有 SSH 访问和一个运行中的
herdr —— 不改服务器、不装额外软件包。SSH 服务器需允许 stream-local 转发
（OpenSSH 默认开启）；若被关闭，引导流程会明确指出。

Windows 原生 Host（herdr = 0.9.3）通过 SSH 连接，需手动添加。

herdr-core Host（包括运行 Herdr 桌面端的机器）需手动添加，并确认 Server Kind。Heeler 与 core 之间只有一条分帧链路：macOS 和 Linux 上经 direct-streamlocal 通道直连 core 的套接字，Windows 原生环境上经 SSH exec 运行 herdr-core connect。在 macOS 和 Linux 上，连接本身绝不会启动 core。可选的 Host Helper 在 macOS 和 Linux 上提供通知、实时活动和 Usage（连接 herdr-core）。

如需通过 Tailscale、ZeroTier 或 EasyTier 访问机器，请参阅 Overlay Network 设置教程。教程涵盖 macOS 安装、Mac 上不装 VPN 的 Tailscale 方案、Heeler 配置和连接验证。Heeler 在应用内加入这些网络，无需配置 iOS 系统 VPN；需要带有 Settings  Overlay Networks 的 Heeler 版本。

查看 Heeler 配置截图，包括 Tailscale、ZeroTier 以及 EasyTier 两种模式（Network 与 Config Server）的设置界面。

不可直连的机器可以放在 SSH 跳板机之后：

- 逐步搭建远程访问
- 架构、安全边界与 VPS 迁移手册

一个 Host 可以有多条路由，例如在家用局域网地址，在外走 Overlay Network 或跳板机：多路由使用教程。

 安装

从 App Store 或
TestFlight 安装 Heeler。

- macOS / Linux： 安装 herdr，启用 SSH，再按下方步骤配对。
- Windows 原生环境： 参见 Windows 设置指南。
- Herdr 桌面端 / herdr-core： 先启动桌面端或 herdr-core 并启用 SSH，再手动添加 Host，参见连接 herdr-core。需要 Heeler 0.1.18 或更

Top issues

Discussions

Latest release

Build record

json
{
  "candidate": {
    "tag": "builds/0.1.18/44",
    "version": "0.1.18",
    "build": 44,
    "source": "3af1066588eab5eb615a2f63aacc2acc1f6ba35e",
    "plugin": "0.9.0",
    "bundle_id": "dev.bybee.heeler",
    "platform": "IOS"
  },
  "state": "valid",
  "run_id": "42161415744",
  "run_attempt": "1",
  "observed_at": "2026-11-06T04:27:34.813192+00:00",
  "ipa_sha256": "5544018ca21d605c658d673f68d5d0ed626a9642a37378c8b27af98f025a916a",
  "toolchain": "Xcode 27.2\nBuild version 27B52",
  "apple_build_id": "3cacdfa4-b28e-447b-9d1f-f9240b4ecf65",
  "apple_processing_state":