Herald is a self-hosted MCP server that bridges Claude Chat to Claude Code over the official Custom Connectors protocol. It lets you orchestrate code chores from any device, so you can draft a changelist, run tests, and push results without being tied to a single workstation or browser tab.

How to use

You connect Claude Chat to Herald using a built‑in MCP connector. Once linked, you can start tasks in Claude Code from your phone or laptop, monitor progress, and pull back summaries, file changes, and git branches back into Claude Chat. Tasks run in isolation on their own branches, and you can resume multi‑turn conversations or remote sessions from any device.

How to install

Prerequisites: you need a domain with HTTPS and access to Claude Code. You will also run Herald as a native binary or via Docker. Follow these steps to install and run Herald.

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
# Binary is in ./bin/herald

</details> ``` ## Configuration and startup

Create a config directory and a configuration file. Then run Herald so Claude Chat can connect and start managing Maven-style tasks.

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

Connect Claude Chat to Herald at the MCP URL shown after first start, such as https://herald.yourdomain.com/mcp. Authenticate via OAuth and you will see the new tools appear in Claude Chat.

## Using with Claude Chat and Claude Code

After linking, you can start a task from Claude Chat and watch Herald chore the work in Claude Code. You’ll receive a task ID immediately, with status updates and eventual results including a summary, differing files, and any git changes.

Start a task by sending a request from Claude Chat

Claude Code runs in the background and pushes updates to Herald

```json
{
  "task": "start_task",
  "project": "my-api",
  "operation": "Refactor auth middleware",
  "branch_prefix": "herald/"
}

Use Claude Chat to check progress and retrieve the final results when ready.

## Security and best practices

Herald remains self-contained on your network. It binds to localhost by default, with TLS termination handled by a reverse proxy. It uses OAuth 2.1 with PKCE, rotating tokens, and per‑project tool restrictions to limit what Claude Code can do within each project.

## Configuration notes

The configuration supports multiple projects, per‑project tool restrictions, and a rotation of access tokens. Edit the YAML to add projects, define allowed tools, and control Git behavior. Low‑level details are designed to keep your main branch safe while enabling rapid iteration.

## Deployment options

Herald is shipped as a single Go binary and can be run directly or via Docker. If you use Docker, you can pair Herald with Traefik or Caddy for TLS termination and expose the MCP endpoint at a public domain.

Docker Compose snippet (example)

services: herald: image: herald:latest volumes: - "/.config/herald:/root/.config/herald" - "/projects:/root/projects:ro" environment: - HERALD_DOMAIN=herald.yourdomain.com

## Troubleshooting and tips

If Claude Chat cannot connect, verify the MCP URL is reachable, TLS is handled by your proxy, and tokens are valid. Check logs for OAuth issues, token rotation, or rate limit messages. Ensure the domain is accessible and the reverse proxy forwards to port 8420.

## Tools you get with Herald

Herald exposes a set of MCP tools that Claude Chat discovers automatically. These tools let you start tasks, monitor progress, fetch results, manage sessions, and inspect code changes.

## Notes on MCP configuration references

To connect Claude Chat, configure the MCP endpoint at your domain with the path /mcp and complete the OAuth flow to authorize Claude Chat to invoke tasks on Herald.

## Available tools

### start\_task

Launch a Claude Code task. Returns an ID immediately and supports priority, timeout, session resumption, and Git branch options.

### check\_task

Check status and progress. Optionally include recently produced output.

### get\_result

Retrieve the full result of a completed task, with options like summary, full, or json.

### list\_tasks

List tasks with filters such as status, project, and time range.

### cancel\_task

Cancel a running or queued task and optionally revert Git changes.

### get\_diff

Show a Git diff for a task's branch or uncommitted changes.

### list\_projects

List configured projects with their Git status.

### read\_file

Read a file from a project with path safeguards to prevent escaping the 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.