Herald - The Self Hosted Mcp Bridge Between Claude Chat And Claude Code

- Native MCP bridge using Anthropic’s official protocol
- Async task execution with progress checking and results
- Git branch isolation per task; main branch stays untouched
- Bidirectional bridge: Claude Chat → Claude Code and Claude Code → Herald
- Multi-project support with per-project tool restrictions
- SQLite persistence for task history across restarts
- Single ~15MB Go binary, zero CGO, only 6 dependencies

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

<details>
<summary>Or build from source (requires Go 1.26+)</summary>

git clone https://github.com/btouchard/herald.git
cd herald && make build
Don't have a domain or reverse proxy? Use ngrok to expose Herald instantly over HTTPS:
1. Get ngrok auth token
Sign up at ngrok.com (free plan works) and grab your auth token from the dashboard.
2. Enable tunnel in config
Edit ~/.config/herald/herald.yaml:

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

<details>
<summary><strong>Docker Compose with Traefik</strong></summary>

services:
  traefik:
    image: traefik:v3
    command:
      - "--entrypoints.websecure.address=:443"
      - "[email protected]"
      - "--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"

</details>

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