Herald

🚀 Herald

スマートフォンからコードを記述できます。本当に。Claude ChatとClaude Codeの間のセルフホスト型MCPブリッジです。

🚀 クイックスタート

あなたがソファに座ってスマートフォンを持っているとしましょう。Claude Chatを開き、次のように入力します。

"my-apiの認証ミドルウェアをJWTを使うようにリファクタリングして、テストを実行してください。"

4分後、すべて完了します。ブランチが作成され、コードがリファクタリングされ、テストが合格し、変更がコミットされます。あなたはノートパソコンを開くことなく、ワークステーションがすべての作業を行いました。

これがHeraldです。

前提条件

Claude Code CLIがインストールされていること、ngrok（組み込み）を使用したHTTPSまたはリバースプロキシ付きのドメインが必要です。

1. インストール

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

git clone https://github.com/btouchard/herald.git
cd herald && make build
# バイナリは./bin/heraldにあります

2. 設定

mkdir -p ~/.config/herald
cp configs/herald.example.yaml ~/.config/herald/herald.yaml
# ドメインとプロジェクトを編集します（以下を参照）

3. 実行

herald serve
# クライアントシークレットは初回起動時に自動生成され、コンソールに表示されます

~/.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から接続します。

1. Claude Chat → 設定 → カスタムコネクタ
2. コネクタを追加: https://herald.yourdomain.com/mcp
3. OAuthで認証
4. 完了 — Claude Chatには、ワークステーションを制御するための10個の新しいツールが追加されました。

ngrokを使ったクイックスタート（リバースプロキシ不要）

ドメインやリバースプロキシがない場合、ngrokを使ってHeraldをHTTPSで即座に公開できます。

1. ngrokの認証トークンを取得

ngrok.comにサインアップし（無料プランでも可）、ダッシュボードから認証トークンを取得します。

2. 設定でトンネルを有効にする

~/.config/herald/herald.yamlを編集します。

tunnel:
  enabled: true
  provider: "ngrok"
  authtoken: "2abc..."  # またはHERALD_NGROK_AUTHTOKEN環境変数を設定
  # domain: "my-herald.ngrok-free.app"  # オプション: 固定ドメイン（有料プラン）

3. Heraldを実行

herald serve
# トンネルURLがバナーに表示されます:
#   Tunnel: https://abc123.ngrok-free.app (ngrok)

バナーに表示されたngrok URLを使ってClaude Chatから接続します。これで完了です — TraefikやCaddy、DNSの設定は不要です。

注意: ngrokトンネルはオプションです。すでにリバースプロキシ（Traefik/Caddy）を持っている場合は、tunnel.enabled: falseにして通常通りドメインを使ってください。

server:
  host: "127.0.0.1"          # 常にローカルホスト — リバースプロキシが外部を処理
  port: 8420
  public_url: "https://herald.yourdomain.com"
  log_level: "info"           # debug, info, warn, error
  log_file: ""                # オプションのログ出力ファイルパス

auth:
  client_id: "herald-claude-chat"
  # client_secretは自動生成されます — 必要に応じてHERALD_CLIENT_SECRET環境変数で上書き
  access_token_ttl: 1h
  refresh_token_ttl: 720h    # 30日
  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_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               # ngrokトンネルを有効にするにはtrueに設定
  provider: "ngrok"
  authtoken: ""                # またはHERALD_NGROK_AUTHTOKEN環境変数を設定
  # domain: ""                 # オプション: 固定ドメイン（有料ngrokプラン）

rate_limit:
  requests_per_minute: 200
  burst: 100

✨ 主な機能

コア機能

• ネイティブMCPブリッジ — Anthropicの公式カスタムコネクタプロトコルを使用します。ハックでも、ラッパーでも、プロキシでもありません。
• 非同期タスク実行 — タスクを開始し、進捗を確認し、結果を取得できます。Claude Codeはバックグラウンドで実行されるため、他の作業を続けることができます。
• Gitブランチ分離 — 各タスクは独自のブランチで実行されます。メインブランチは変更されません。
• セッション再開 — 複数ターンのClaude Code会話が可能です。中断したところから再開できます。
• 双方向ブリッジ — Claude Codeはherald_pushを介してセッションコンテキストをHeraldにプッシュでき、別のデバイスからのリモート監視と続きの作業が可能です。

マルチプロジェクト機能

• 複数のプロジェクト — 必要なだけのプロジェクトを設定でき、それぞれ独自の設定を持つことができます。
• プロジェクトごとのツール制限 — Claude Codeが使用できるツールを正確に制御できます。各プロジェクトごとに完全なサンドボックス化が可能です。

運用機能

• MCPプッシュ通知 — HeraldはMCPサーバー通知を介してタスクの更新を直接Claude Chatにプッシュします。ポーリングは必要ありません。
• SQLite永続化 — タスクはサーバーの再起動後も保持されます。完全な履歴が残り、完全に検索可能です。

エンジニアリング機能

• シングルバイナリ — 約15MBのGo実行ファイル1つです。Docker、ランタイム、node_modulesは必要ありません。
• Zero CGO — 純粋なGoで構築されています。Linux、macOS、Windows、ARMにクロスコンパイル可能です。
• 6つの依存関係 — chi、mcp-go、modernc/sqlite、uuid、yaml、testify。これがすべての依存関係ツリーです。

💻 使用例

基本的な使用法

Claude Chatからタスクを開始する例です。

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ツール

Heraldは、MCPプロトコルを介してClaude Chatが自動的に検出する10個のツールを公開します。

セキュリティ

HeraldはClaude Codeをネットワークに公開します。これには真摯に向き合っています。

アーキテクチャ

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)

設計原則: シングルバイナリ（すべてが1つのGo実行ファイルにコンパイルされる）、非同期優先（各タスクはゴルーチン）、ステートレスなMCPとステートフルなバックエンド、フェイルセーフ（Heraldのクラッシュが実行中のClaude Codeプロセスを殺さない）。

デプロイメント

Heraldはネイティブバイナリとして実行するのが最適です（Claude Codeとファイルに直接アクセスできます）。Dockerもオプションとして利用できます。

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"

ロードマップ

アイデアがあれば、issueを作成してください。私たちはユーザーが必要とするものを開発します。

コントリビュート

Heraldは初期のアルファ版です — プロジェクトを形作る最適な時期です。

# 始める
git clone https://github.com/btouchard/herald.git
cd herald
make build && make test

# ブランチを作成
git checkout -b feat/your-feature

# コードを記述、テスト、リント
make lint && make test

# PRを作成

コミットメッセージはConventional Commits（feat:、fix:、refactor:、docs:）に従ってください。

バグ修正、新しい通知バックエンド、ドキュメントの改善など、すべてのコントリビューションを歓迎します。

なぜHeraldを選ぶのか

Heraldは、Anthropicが独自の統合に使用するのと同じプロトコルを使用しています。リバースエンジニアリング、非公式API、次のアップデートで壊れるハックはありません。

📄 ライセンス

AGPL-3.0 License — Benjamin Touchardによって構築されました。

もしHeraldがあなたの時間を節約してくれたら、スターをつけてください。これにより、他の人がこのプロジェクトを見つけやすくなります。