Herald

Code from your phone. Seriously.

The self-hosted MCP bridge between Claude Chat and Claude Code.

Documentation · Quick Start · How It Works · Features · Security · Roadmap

🇫🇷 Version française

______________________________________________________________________

你在沙发上。在你的手机上。您打开Claude Chat并键入：

*“在我的api中重构身份验证中间件，以使用JWT而不是会话Cookie。运行测试。”*

四分钟后，就完成了。创建分支、重构代码、通过测试、提交更改。你的工作站完成了所有的工作。你从未打开过笔记本电脑。

那是《先驱报》。

问题

Claude Chat和Claude Code是两个生活在完全不同世界中的出色工具。

	克劳德聊天	克劳德代码
哪里	浏览器、手机、任何地方	您的终端
什么	对话、分析、思考	阅读、编写和发布实际代码
差距	不能碰你的代码库	不能离开你的办公桌

你一直在他们之间复制粘贴。或者更糟的是，你一直在等着回到办公桌前。结束了。

解决方案

Herald是一个自托管的MCP服务器，使用Anthropic的官方工具将Claude Chat连接到Claude Code 自定义连接器协议。One Go二进制。零黑客攻击。

  You (phone/tablet/browser)
       │
       │  "Add rate limiting to the API"
       ▼
  Claude Chat ──── MCP over HTTPS ────► Herald (your workstation)
                                           │
                                           ▼
                                        Claude Code
                                           ├── reads your codebase
                                           ├── writes the code
                                           ├── runs the tests
                                           └── commits to a branch

  You (terminal)
       │
       │  Claude Code calls herald_push
       ▼
  Claude Code ──── MCP ────► Herald ────► Claude Chat picks it up
                                           └── session context, summary,
                                               files modified, git branch

桥是双向.Claude Chat将任务分派给Claude Code，Claude Code可以将会话上下文推送回Herald，以便从另一台设备进行远程监控和继续。

你的代码永远不会离开你的机器。《先驱报》只是精心策划。

运作原理

You (Claude Chat)          Herald                     Claude Code
─────────────────          ──────                     ───────────
"Refactor auth..."    ──►  start_task
                           → creates branch
                           → spawns Claude Code  ──►  reads codebase
                                                      refactors code
                                                      runs tests
                                                      commits changes
                      ◄──  task_id: herald-a1b2c3d4

"How's it going?"     ──►  check_task
                      ◄──  ✅ Completed (4m 12s)
                           4 files changed (+127/-23)

"Show me the diff"    ──►  get_diff
                      ◄──  auth/middleware.go
                           +func ValidateJWT(...)
                           -func CheckSession(...)

三个工具。这就是核心循环。开始、检查、获得结果——无论你在哪里。

逆流：克劳德代码→ 先驱

在终端中工作并想从手机继续？Claude Code将其会议推送给Herald：

You (terminal)             Claude Code                Herald
──────────────             ───────────                ──────
"Push this to Herald"  ──►  herald_push
                             → session_id, summary,
                               files, branch       ──►  linked task created
                                                         🔗 visible in list_tasks

You (phone, later)         Claude Chat                Herald
──────────────────         ───────────                ──────
"What sessions are         list_tasks
 waiting for me?"     ──►  (status: linked)      ──►  🔗 herald-a1b2c3d4
                                                         my-api / feat/auth

"Resume that session"  ──► start_task
                            (session_id)          ──►  picks up where you left off

特性

核心

本地MCP网桥 --使用Anthropic的官方自定义连接器协议。不是黑客，不是包装，不是代理。
异步任务执行 --开始任务，检查进度，获得结果。当你做其他事情时，Claude Code在后台运行。
Git分支隔离 --每个任务都在自己的分支上运行。你的主要分支保持不变。
会话恢复 --多回合克劳德代码对话。从你停止的地方继续。
双向桥梁 --Claude Code可以通过以下方式将会话上下文推送到Herald herald_push 用于远程监控和从另一设备继续。

多项目

多个项目 --根据需要配置任意多的项目，每个项目都有自己的设置。
每个项目的工具限制 --精确控制Claude Code可以使用哪些工具。每个项目都有完整的沙盒。

运营

MCP推送通知 --Herald通过MCP服务器通知将任务更新直接推送到Claude Chat。不需要投票。
SQLite持久性 --任务在服务器重启后仍然存在。完整的历史记录，完全可搜索。

工程

单个二进制 --One Go可执行文件，约15MB。没有Docker，没有运行时，没有node_modules。
零CGO --纯粹的去。交叉编译到Linux、macOS、Windows、ARM。
6依赖关系 --迟、高国健、modernc/sqlite、uuid、yaml作证。这就是整个依赖树。

快速开始

先决条件: 克劳德代码CLI 通过ngrok（内置）安装HTTPS或使用反向代理的域。

1.安装

curl -fsSL https://raw.githubusercontent.com/btouchard/herald/main/install.sh | sh

Or build from source (requires Go 1.26+)

git clone https://github.com/btouchard/herald.git
cd herald && make build
# Binary is in ./bin/herald

2.配置

mkdir -p ~/.config/herald
cp configs/herald.example.yaml ~/.config/herald/herald.yaml
# Edit with your domain and projects (see below)

3.跑步

herald serve
# Client secret is auto-generated on first start and displayed in the console

编辑 ~/.config/herald/herald.yaml 使用您的域名和项目：

server:
  host: "127.0.0.1"
  port: 8420
  public_url: "https://herald.yourdomain.com"

auth:
  client_id: "herald-claude-chat"

projects:
  my-api:
    path: "/home/you/projects/my-api"
    description: "Main backend API"
    default: true
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash(git *)"
      - "Bash(go *)"
      - "Bash(make *)"
    git:
      auto_branch: true
      branch_prefix: "herald/"

然后从Claude Chat连接：

克劳德聊天 → 设置 → 自定义连接器
添加连接器： https://herald.yourdomain.com/mcp
通过OAuth进行身份验证
完成--Claude Chat现在有10个新工具来控制您的工作站

快速开始使用ngrok（不需要反向代理）

没有域名或反向代理？使用ngrok通过HTTPS立即公开Herald：

1.获取ngrok认证令牌

注册地址： ngrok.com （免费计划有效）并从仪表盘.

2.在配置中启用隧道

编辑 ~/.config/herald/herald.yaml:

tunnel:
  enabled: true
  provider: "ngrok"
  authtoken: "2abc..."  # or set HERALD_NGROK_AUTHTOKEN env var
  # domain: "my-herald.ngrok-free.app"  # optional: fixed domain (paid plans)

3.运行先驱报

herald serve
# Tunnel URL appears in the banner:
#   Tunnel: https://abc123.ngrok-free.app (ngrok)

使用横幅中显示的ngrok URL从Claude Chat连接。就是这样——不需要Traefik、Caddy或DNS设置。

备注：恩罗克隧道是 可选的。如果您已经有反向代理（Traefik/Caddy），请离开 tunnel.enabled: false 并像往常一样使用您的域名。

Full configuration reference

server:
  host: "127.0.0.1"          # Always localhost — reverse proxy handles external
  port: 8420
  public_url: "https://herald.yourdomain.com"
  log_level: "info"           # debug, info, warn, error
  log_file: ""                # Optional file path for log output

auth:
  client_id: "herald-claude-chat"
  # client_secret is auto-generated — override with HERALD_CLIENT_SECRET env var if needed
  access_token_ttl: 1h
  refresh_token_ttl: 720h    # 30 days
  redirect_uris:
    - "https://claude.ai/oauth/callback"
    - "https://claude.ai/api/oauth/callback"
    - "https://claude.ai/api/mcp/auth_callback"

database:
  path: "~/.config/herald/herald.db"
  retention_days: 90

execution:
  claude_path: "claude"
  model: "claude-sonnet-4-5-20250929"  # Default model for tasks
  default_timeout: 30m
  max_timeout: 2h
  work_dir: "~/.config/herald/work"
  max_concurrent: 3
  max_prompt_size: 102400    # 100KB
  max_output_size: 1048576   # 1MB
  env:
    CLAUDE_CODE_ENTRYPOINT: "herald"
    CLAUDE_CODE_DISABLE_AUTO_UPDATE: "1"

projects:
  my-api:
    path: "/home/you/projects/my-api"
    description: "Main backend API"
    default: true
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash(git *)"
      - "Bash(go *)"
      - "Bash(make *)"
    max_concurrent_tasks: 1
    git:
      auto_branch: true
      auto_stash: true
      auto_commit: true
      branch_prefix: "herald/"

tunnel:
  enabled: false               # Set to true to enable ngrok tunnel
  provider: "ngrok"
  authtoken: ""                # or set HERALD_NGROK_AUTHTOKEN env var
  # domain: ""                 # optional: fixed domain (paid ngrok plans)

rate_limit:
  requests_per_minute: 200
  burst: 100

MCP工具

Herald公开了Claude Chat通过MCP协议自动发现的10个工具：

工具	它做什么
`start_task`	启动Claude Code任务。立即返回ID。支持优先级、超时、会话恢复和Git分支选项。
`check_task`	检查状态和进度。可选地包括最近的输出。
`get_result`	获取已完成任务的完整结果(`summary`, `full`，或 `json`).
`list_tasks`	列出带有筛选器的任务——状态、项目、时间范围。
`cancel_task`	取消正在运行或排队的任务。可选择还原Git更改。
`get_diff`	Git diff用于任务的分支或未提交的更改。
`list_projects`	列出具有Git状态的已配置项目。
`read_file`	从项目中读取文件（路径安全--无法转义项目根）。
`herald_push`	将Claude Code会话推送到Herald，以便从另一台设备进行远程监控和继续。
`get_logs`	查看日志和活动历史记录。

安全

《先驱报》向网络曝光了克劳德密码。我们对此非常重视。

层	保护
网络	绑定到 `127.0.0.1` 只有。通过内置的ngrok隧道或反向代理（Traefik/Caddy）进行HTTPS。
认证	OAuth 2.1与PKCE。每个请求都需要一个有效的Bearer令牌。
代币	访问令牌：1小时。刷新令牌：30d，每次使用时轮换。
文件系统	对所有文件操作进行路径遍历保护。Symlink逃逸被阻止。
执行	每个项目的工具限制。没有毯子 `--dangerously-skip-permissions`.
速率限制	每个令牌需要200个/分钟（可配置）。
超时	每个任务都有一个截止日期（默认值：30分钟）。没有失控的进程。
提示	未经修改传递给克劳德代码。没有注入，没有充实，没有重写。
审计	每个操作都记录了时间戳和标识。

建筑

Claude Chat (mobile/web)
  → HTTPS (MCP Streamable HTTP + OAuth 2.1)
  → Traefik / Caddy (TLS termination)
  → Herald (Go binary, port 8420)
    ├── MCP Handler (/mcp)
    ├── OAuth 2.1 Server (PKCE, token rotation)
    ├── Task Manager (goroutine pool, priority queue)
    ├── Executor Registry (pluggable backends, default: Claude Code)
    ├── SQLite (persistence)
    └── MCP Notifications (server push via SSE)

设计原则：单二进制（所有内容都编译成一个Go可执行文件），异步优先（每个任务都是一个goroutine），无状态MCP和有状态后端，故障安全（Herald崩溃不会杀死正在运行的Claude Code进程）。

Tech stack

组件	选择	为什么
语言	Go 1.26	单二进制、交叉编译、goroutines
MCP	mcp走	流式HTTP，官方协议支持
路由器	气	轻量级，兼容stdlib
数据库	modernc.org/sqlite	纯Go，零CGO
日志记录	`log/slog`	转到结构化stdlib
配置	`gopkg.in/yaml.v3`	标准YAML

6个直接依赖关系。没有ORM。没有日志框架。没有构建工具链。

部署

Herald作为本机二进制文件运行效果最好（直接访问Claude Code和您的文件）。Docker是一个选项。

Docker Compose with Traefik

services:
  traefik:
    image: traefik:v3
    command:
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.le.acme.email=you@example.com"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
    ports:
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"

  herald:
    build: .
    network_mode: host
    volumes:
      - "~/.config/herald:/root/.config/herald"
      - "~/projects:/root/projects:ro"
    labels:
      - "traefik.http.routers.herald.rule=Host(`herald.yourdomain.com`)"
      - "traefik.http.routers.herald.tls.certresolver=le"
      - "traefik.http.services.herald.loadbalancer.server.port=8420"

路线图

版本	状态	焦点
v0.1	✅ 完成	核心MCP服务器、异步任务、Git集成、OAuth 2.1、SQLite
v0.2	🚧 进行中	共享内存——Claude Chat和Claude Code之间的双向上下文
v0.3	🚀 未来	稳定的API，插件系统

有主意吗？打开一个问题。我们构建用户需要的东西。

贡献

《先驱报》正处于早期alpha阶段，这是塑造项目的最佳时机。

# Get started
git clone https://github.com/btouchard/herald.git
cd herald
make build && make test

# Create your branch
git checkout -b feat/your-feature

# Code, test, lint
make lint && make test

# Open a PR

提交消息如下常规承诺 (feat:, fix:, refactor:, docs:).

无论是bug修复、新的通知后端还是文档改进，我们都欢迎您的贡献。

为什么是《先驱报》？

	先驱报	复制粘贴工作流程	其他工具
官方协议	MCP自定义连接器	不适用	自定义API，易碎
您的代码保持本地	总是	是	取决于
通过电话工作	本地	否	很少
自托管	100%	不适用	通常是SaaS
依赖项	6	N/A	50-200+
设置时间	~5分钟	N/A	30分钟+
需要CGO	否	不适用	经常

Herald使用为自己的集成而构建的Anthropic协议。没有逆向工程，没有非官方API，没有在下一次更新中中断的黑客攻击。

______________________________________________________________________

AGPL-3.0 License — Built by Benjamin Touchard

If Herald saves you time, leave a star. It helps others find the project.

Herald MCP

快速接入

详细介绍

问题

解决方案

运作原理

逆流：克劳德代码→ 先驱

特性

核心

多项目

运营

工程

快速开始

快速开始使用ngrok（不需要反向代理）

MCP工具

安全

建筑

部署

路线图

贡献

为什么是《先驱报》？

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP