Herald

Herald is a self-hosted MCP server that connects Claude Chat and Claude Code through the official Custom Connectors protocol, allowing users to remotely control code operations on their workstations from devices such as mobile phones, enabling bidirectional task scheduling and session synchronization.

Developer tools Artificial intelligence chatbots #Remote code control #MCP bridging #Self-hosted tool #Asynchronous tasks .Go

rating : 2.5 points

downloads : 3.2K

update time : 2026-03-12

Open Site

What is Herald?

Herald is a self-hosted Model Context Protocol (MCP) server that connects Claude Chat (used in browsers or on mobile phones) and Claude Code (running in your terminal). Through this bridge, you can issue instructions to Claude Chat from any device, and Herald will launch Claude Code on your workstation to perform actual code operations, such as reading, modifying, testing, and submitting code.

How to use Herald?

1. Install and run the Herald server on your workstation. 2. Add Herald as a custom connector in Claude Chat. 3. Send code task instructions to Claude Chat from your mobile phone, tablet, or browser. 4. Herald launches Claude Code on the workstation to execute tasks. 5. View the task progress and results through Claude Chat.

Use cases

- Suddenly come up with an idea for code improvement while using your phone on the couch. - Need to handle urgent code problems via your phone when you're out. - Collaborate on development across multiple devices and want to check the code status on your phone. - Need to remotely monitor long-running code tasks. - Seamlessly switch development work between different devices.

Main features

Bidirectional MCP bridging

Use Anthropic's official custom connector protocol to establish a bidirectional communication channel between Claude Chat and Claude Code.

Asynchronous task execution

Immediately return the task ID after starting a task. Claude Code executes in the background, and you can check the progress and get the results at any time.

Git branch isolation

Each task runs on an independent Git branch to ensure that the main branch remains unaffected. It supports automatic creation, submission, and merging.

Session recovery

Supports multi-round Claude Code conversations, allowing you to continue working from where you left off. It also supports session recovery from different devices.

Multi-project management

You can configure multiple projects, each with independent tool permission settings, achieving sandbox isolation by project.

MCP push notifications

Herald pushes task updates to Claude Chat through the MCP server, eliminating the need for manual polling to check the status.

Single binary deployment

A single Go executable file of approximately 15MB, no Docker or runtime environment required, zero CGO dependencies, and cross-platform support.

Advantages

Official protocol support: Uses Anthropic's official MCP custom connector protocol, not a hacky solution.

Code localization: Your code always stays on your local machine and is not uploaded to the cloud.

Mobile-friendly: You can fully control code development from mobile devices such as phones and tablets.

Self-hosted: A 100% self-hosted solution, with complete control over your data.

Lightweight: Only 6 dependencies, simple and fast to install and deploy.

No CGO: Pure Go implementation, easy to compile across platforms.

Limitations

Requires Claude Code: You must install the Claude Code CLI on your workstation.

Network configuration: Requires HTTPS access, and you need to configure a reverse proxy or use ngrok.

Workstation operation: The Herald server needs to run on your workstation all the time.

Early stage: Currently in the alpha version, and the API may change.

Learning curve: You need to understand the concepts of MCP and OAuth configuration.

How to use

Install Herald

Download and install the Herald binary file on your workstation.

Configure the project

Create a configuration file and set up your project and access domain name.

Start the server

Run the Herald server, and it will generate a client key.

Configure Claude Chat

Add Herald as a custom connector in Claude Chat.

Start using

Send code task instructions to Claude Chat from any device.

Usage examples

Remote code refactoring

While using your phone on the couch, you find that the authentication logic in the code needs to be refactored.

Emergency Bug fix

You receive a Bug report in the production environment when you're out and need to fix it immediately.

Feature development monitoring

Start a long-running feature development and want to monitor the progress from your phone.

Multi-device collaboration

Start development in the office and want to continue working on your tablet when you get home.

Frequently Asked Questions

Is Herald secure? Will my code be uploaded to the cloud?

Do I need a public IP or domain name?

Which operating systems does Herald support?

What operations can Claude Code perform? Are there any limitations?

What should I do if a task execution times out?

How can I resume a development session from different devices?

Is Herald free?

Related resources

Official documentation

Complete Herald usage documentation and configuration guide.

GitHub repository

Source code, issue tracking, and contribution guide.

Claude Code documentation

Official installation and usage documentation for the Claude Code CLI.

MCP protocol documentation

Official specification of the Model Context Protocol.

ngrok service

Service for creating HTTPS tunnels (built-in support in Herald).

Example configuration file

Complete Herald configuration example.

🚀 Herald

Code from your phone. Seriously. The self-hosted MCP bridge between Claude Chat and Claude Code.

🚀 Quick Start

Prerequisites

Claude Code CLI installed, HTTPS via ngrok (built-in) or a domain with reverse proxy.

1. Install

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. Configure

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

3. Run

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

Edit ~/.config/herald/herald.yaml with your domain and projects:

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/"

Then connect from Claude Chat:

Claude Chat → Settings → Custom Connectors
Add connector: https://herald.yourdomain.com/mcp
Authenticate via OAuth
Done — Claude Chat now has 10 new tools to control your workstation

Quick Start with ngrok (No Reverse Proxy Needed)

Don't have a domain or reverse proxy? Use ngrok to expose Herald instantly over HTTPS:

1. Get ngrok auth token

2. Enable tunnel in config

Edit ~/.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. Run Herald

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

Connect from Claude Chat using the ngrok URL shown in the banner. That's it — no Traefik, Caddy, or DNS setup required.

⚠️ Important Note

The ngrok tunnel is optional. If you already have a reverse proxy (Traefik/Caddy), leave tunnel.enabled: false and use your domain as usual.

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

✨ Features

Core

Native MCP bridge — Uses Anthropic's official Custom Connectors protocol. Not a hack, not a wrapper, not a proxy.
Async task execution — Start tasks, check progress, get results. Claude Code runs in the background while you do other things.
Git branch isolation — Each task runs on its own branch. Your main branch stays untouched.
Session resumption — Multi-turn Claude Code conversations. Pick up where you left off.
Bidirectional bridge — Claude Code can push session context to Herald via herald_push for remote monitoring and continuation from another device.

Multi-Project

Multiple projects — Configure as many projects as you need, each with its own settings.
Per-project tool restrictions — Control exactly which tools Claude Code can use. Full sandboxing per project.

Operations

MCP push notifications — Herald pushes task updates directly to Claude Chat via MCP server notifications. No polling needed.
SQLite persistence — Tasks survive server restarts. Full history, fully searchable.

Engineering

Single binary — One Go executable, ~15MB. No Docker, no runtime, no node_modules.
Zero CGO — Pure Go. Cross-compiles to Linux, macOS, Windows, ARM.
6 dependencies — chi, mcp-go, modernc/sqlite, uuid, yaml, testify. That's the entire dependency tree.

💻 Usage Examples

Basic Usage

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(...)

Advanced Usage

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

📚 Documentation

The Problem

Claude Chat and Claude Code are two brilliant tools that live in completely separate worlds.

Property	Claude Chat	Claude Code
Where	Browser, phone, anywhere	Your terminal
What	Conversations, analysis, thinking	Reads, writes, and ships actual code
Gap	Can't touch your codebase	Can't leave your desk

You've been copy-pasting between them. Or worse — you've been waiting until you're back at your desk. That's over.

The Solution

Herald is a self-hosted MCP server that bridges Claude Chat to Claude Code using Anthropic's official Custom Connectors protocol. One Go binary. Zero hacks.

  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

The bridge is bidirectional. Claude Chat dispatches tasks to Claude Code, and Claude Code can push session context back to Herald for remote monitoring and continuation from another device.

Your code never leaves your machine. Herald just orchestrates.

How It Works

Three tools form the core loop. You can start, check, and get results from wherever you are.

MCP Tools

Herald exposes 10 tools that Claude Chat discovers automatically via the MCP protocol:

Tool	What it does
`start_task`	Launch a Claude Code task. Returns an ID immediately. Supports priority, timeout, session resumption, and Git branch options.
`check_task`	Check status and progress. Optionally include recent output.
`get_result`	Get the full result of a completed task (`summary`, `full`, or `json`).
`list_tasks`	List tasks with filters — status, project, time range.
`cancel_task`	Cancel a running or queued task. Optionally revert Git changes.
`get_diff`	Git diff for a task's branch or uncommitted changes.
`list_projects`	List configured projects with Git status.
`read_file`	Read a file from a project (path-safe — cannot escape project root).
`herald_push`	Push a Claude Code session to Herald for remote monitoring and continuation from another device.
`get_logs`	View logs and activity history.

Security

Herald exposes Claude Code to the network. We take that seriously.

Layer	Protection
Network	Binds to `127.0.0.1` only. HTTPS via built-in ngrok tunnel or reverse proxy (Traefik/Caddy).
Auth	OAuth 2.1 with PKCE. Every request needs a valid Bearer token.
Tokens	Access tokens: 1h. Refresh tokens: 30d, rotated on each use.
Filesystem	Path traversal protection on all file operations. Symlink escapes blocked.
Execution	Per-project tool restrictions. No blanket `--dangerously-skip-permissions`.
Rate limiting	200 req/min per token (configurable).
Timeouts	Every task has a deadline (default: 30min). No runaway processes.
Prompts	Passed to Claude Code unmodified. No injection, no enrichment, no rewriting.
Audit	Every action logged with timestamp and identity.

Architecture

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)

Design principles: single binary (everything compiled into one Go executable), async-first (each task is a goroutine), stateless MCP with stateful backend, fail-safe (Herald crash doesn't kill running Claude Code processes).

Tech stack

Component	Choice	Why
Language	Go 1.26	Single binary, cross-compilation, goroutines
MCP	mcp-go	Streamable HTTP, official protocol support
Router	chi	Lightweight, stdlib-compatible
Database	modernc.org/sqlite	Pure Go, zero CGO
Logging	`log/slog`	Go stdlib, structured
Config	`gopkg.in/yaml.v3`	Standard YAML

6 direct dependencies. No ORM. No logging framework. No build toolchain.

Deployment

Herald runs best as a native binary (direct access to Claude Code and your files). Docker is available as an option.

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"

Roadmap

Version	Status	Focus
v0.1	✅ Done	Core MCP server, async tasks, Git integration, OAuth 2.1, SQLite
v0.2	🚧 In progress	Shared memory — bidirectional context between Claude Chat and Claude Code
v0.3	🚀 Future	Stable API, plugin system

Have an idea? Open an issue. We build what users need.

🔧 Technical Details

Why Herald?

	Herald	Copy-paste workflow	Other tools
Official protocol	MCP Custom Connectors	N/A	Custom APIs, fragile
Your code stays local	Always	Yes	Depends
Works from phone	Native	No	Rarely
Self-hosted	100%	N/A	Often SaaS
Dependencies	6	N/A	50 - 200+
Setup time	~5 minutes	N/A	30min+
CGO required	No	N/A	Often

Herald uses the same protocol Anthropic built for their own integrations. No reverse engineering, no unofficial APIs, no hacks that break on the next update.