{
  "markdown": "<p align=\"center\">\n  <h1 align=\"center\">Herald</h1>\n  <p align=\"center\">\n    <strong>Code from your phone. Seriously.</strong>\n    <br />\n    <em>The self-hosted MCP bridge between Claude Chat and Claude Code.</em>\n  </p>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://go.dev\"><img src=\"https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go&logoColor=white\" alt=\"Go 1.26+\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-AGPL--3.0-blue.svg\" alt=\"AGPL-3.0 License\"></a>\n  <a href=\"https://github.com/btouchard/herald/stargazers\"><img src=\"https://img.shields.io/github/stars/btouchard/herald?style=social\" alt=\"GitHub Stars\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://btouchard.github.io/herald/\">Documentation</a> &middot;\n  <a href=\"#quick-start\">Quick Start</a> &middot;\n  <a href=\"#how-it-works\">How It Works</a> &middot;\n  <a href=\"#features\">Features</a> &middot;\n  <a href=\"#security\">Security</a> &middot;\n  <a href=\"#roadmap\">Roadmap</a>\n  <br />\n  🇫🇷 <a href=\"README_FR.md\">Version française</a>\n</p>\n\n---\n\n<img src=\"/assets/herald-hero.svg\">\n\nYou're on the couch. On your phone. You open Claude Chat and type:\n\n> *\"Refactor the auth middleware in my-api to use JWT instead of session cookies. Run the tests.\"*\n\nFour minutes later, it's done. Branch created, code refactored, tests passing, changes committed. Your workstation did all the work. You never opened your laptop.\n\n**That's Herald.**\n\n## The Problem\n\nClaude Chat and Claude Code are two brilliant tools that live in completely separate worlds.\n\n| | Claude Chat | Claude Code |\n|---|---|---|\n| **Where** | Browser, phone, anywhere | Your terminal |\n| **What** | Conversations, analysis, thinking | Reads, writes, and ships actual code |\n| **Gap** | Can't touch your codebase | Can't leave your desk |\n\nYou've been copy-pasting between them. Or worse — you've been waiting until you're back at your desk. That's over.\n\n## The Solution\n\nHerald is a self-hosted MCP server that bridges Claude Chat to Claude Code using Anthropic's official [Custom Connectors](https://support.claude.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers) protocol. One Go binary. Zero hacks.\n\n```\n  You (phone/tablet/browser)\n       │\n       │  \"Add rate limiting to the API\"\n       ▼\n  Claude Chat ──── MCP over HTTPS ────► Herald (your workstation)\n                                           │\n                                           ▼\n                                        Claude Code\n                                           ├── reads your codebase\n                                           ├── writes the code\n                                           ├── runs the tests\n                                           └── commits to a branch\n\n  You (terminal)\n       │\n       │  Claude Code calls herald_push\n       ▼\n  Claude Code ──── MCP ────► Herald ────► Claude Chat picks it up\n                                           └── session context, summary,\n                                               files modified, git branch\n```\n\nThe 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.\n\nYour code never leaves your machine. Herald just orchestrates.\n\n## How It Works\n\n```\nYou (Claude Chat)          Herald                     Claude Code\n─────────────────          ──────                     ───────────\n\"Refactor auth...\"    ──►  start_task\n                           → creates branch\n                           → spawns Claude Code  ──►  reads codebase\n                                                      refactors code\n                                                      runs tests\n                                                      commits changes\n                      ◄──  task_id: herald-a1b2c3d4\n\n\"How's it going?\"     ──►  check_task\n                      ◄──  ✅ Completed (4m 12s)\n                           4 files changed (+127/-23)\n\n\"Show me the diff\"    ──►  get_diff\n                      ◄──  auth/middleware.go\n                           +func ValidateJWT(...)\n                           -func CheckSession(...)\n```\n\nThree tools. That's the core loop. Start, check, get results — all from wherever you are.\n\n### Reverse flow: Claude Code → Herald\n\nWorking in your terminal and want to continue from your phone? Claude Code pushes its session to Herald:\n\n```\nYou (terminal)             Claude Code                Herald\n──────────────             ───────────                ──────\n\"Push this to Herald\"  ──►  herald_push\n                             → session_id, summary,\n                               files, branch       ──►  linked task created\n                                                         🔗 visible in list_tasks\n\nYou (phone, later)         Claude Chat                Herald\n──────────────────         ───────────                ──────\n\"What sessions are         list_tasks\n waiting for me?\"     ──►  (status: linked)      ──►  🔗 herald-a1b2c3d4\n                                                         my-api / feat/auth\n\n\"Resume that session\"  ──► start_task\n                            (session_id)          ──►  picks up where you left off\n```\n\n## Features\n\n### Core\n\n- **Native MCP bridge** — Uses Anthropic's official Custom Connectors protocol. Not a hack, not a wrapper, not a proxy.\n- **Async task execution** — Start tasks, check progress, get results. Claude Code runs in the background while you do other things.\n- **Git branch isolation** — Each task runs on its own branch. Your main branch stays untouched.\n- **Session resumption** — Multi-turn Claude Code conversations. Pick up where you left off.\n- **Bidirectional bridge** — Claude Code can push session context to Herald via `herald_push` for remote monitoring and continuation from another device.\n\n### Multi-Project\n\n- **Multiple projects** — Configure as many projects as you need, each with its own settings.\n- **Per-project tool restrictions** — Control exactly which tools Claude Code can use. Full sandboxing per project.\n\n### Operations\n\n- **MCP push notifications** — Herald pushes task updates directly to Claude Chat via MCP server notifications. No polling needed.\n- **SQLite persistence** — Tasks survive server restarts. Full history, fully searchable.\n\n### Engineering\n\n- **Single binary** — One Go executable, ~15MB. No Docker, no runtime, no node_modules.\n- **Zero CGO** — Pure Go. Cross-compiles to Linux, macOS, Windows, ARM.\n- **6 dependencies** — chi, mcp-go, modernc/sqlite, uuid, yaml, testify. That's the entire dependency tree.\n\n## Quick Start\n\n**Prerequisites**: [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed, HTTPS via ngrok (built-in) or a domain with reverse proxy.\n\n**1. Install**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/btouchard/herald/main/install.sh | sh\n```\n\n<details>\n<summary>Or build from source (requires Go 1.26+)</summary>\n\n```bash\ngit clone https://github.com/btouchard/herald.git\ncd herald && make build\n# Binary is in ./bin/herald\n```\n</details>\n\n**2. Configure**\n\n```bash\nmkdir -p ~/.config/herald\ncp configs/herald.example.yaml ~/.config/herald/herald.yaml\n# Edit with your domain and projects (see below)\n```\n\n**3. Run**\n\n```bash\nherald serve\n# Client secret is auto-generated on first start and displayed in the console\n```\n\nEdit `~/.config/herald/herald.yaml` with your domain and projects:\n\n```yaml\nserver:\n  host: \"127.0.0.1\"\n  port: 8420\n  public_url: \"https://herald.yourdomain.com\"\n\nauth:\n  client_id: \"herald-claude-chat\"\n\nprojects:\n  my-api:\n    path: \"/home/you/projects/my-api\"\n    description: \"Main backend API\"\n    default: true\n    allowed_tools:\n      - \"Read\"\n      - \"Write\"\n      - \"Edit\"\n      - \"Bash(git *)\"\n      - \"Bash(go *)\"\n      - \"Bash(make *)\"\n    git:\n      auto_branch: true\n      branch_prefix: \"herald/\"\n```\n\nThen connect from Claude Chat:\n\n1. **Claude Chat** → **Settings** → **Custom Connectors**\n2. Add connector: `https://herald.yourdomain.com/mcp`\n3. Authenticate via OAuth\n4. Done — Claude Chat now has 10 new tools to control your workstation\n\n### Quick Start with ngrok (No Reverse Proxy Needed)\n\nDon't have a domain or reverse proxy? Use ngrok to expose Herald instantly over HTTPS:\n\n**1. Get ngrok auth token**\n\nSign up at [ngrok.com](https://ngrok.com) (free plan works) and grab your auth token from the [dashboard](https://dashboard.ngrok.com/get-started/your-authtoken).\n\n**2. Enable tunnel in config**\n\nEdit `~/.config/herald/herald.yaml`:\n\n```yaml\ntunnel:\n  enabled: true\n  provider: \"ngrok\"\n  authtoken: \"2abc...\"  # or set HERALD_NGROK_AUTHTOKEN env var\n  # domain: \"my-herald.ngrok-free.app\"  # optional: fixed domain (paid plans)\n```\n\n**3. Run Herald**\n\n```bash\nherald serve\n# Tunnel URL appears in the banner:\n#   Tunnel: https://abc123.ngrok-free.app (ngrok)\n```\n\nConnect from Claude Chat using the ngrok URL shown in the banner. That's it — no Traefik, Caddy, or DNS setup required.\n\n> **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.\n\n<details>\n<summary><strong>Full configuration reference</strong></summary>\n\n```yaml\nserver:\n  host: \"127.0.0.1\"          # Always localhost — reverse proxy handles external\n  port: 8420\n  public_url: \"https://herald.yourdomain.com\"\n  log_level: \"info\"           # debug, info, warn, error\n  log_file: \"\"                # Optional file path for log output\n\nauth:\n  client_id: \"herald-claude-chat\"\n  # client_secret is auto-generated — override with HERALD_CLIENT_SECRET env var if needed\n  access_token_ttl: 1h\n  refresh_token_ttl: 720h    # 30 days\n  redirect_uris:\n    - \"https://claude.ai/oauth/callback\"\n    - \"https://claude.ai/api/oauth/callback\"\n    - \"https://claude.ai/api/mcp/auth_callback\"\n\ndatabase:\n  path: \"~/.config/herald/herald.db\"\n  retention_days: 90\n\nexecution:\n  claude_path: \"claude\"\n  model: \"claude-sonnet-4-5-20250929\"  # Default model for tasks\n  default_timeout: 30m\n  max_timeout: 2h\n  work_dir: \"~/.config/herald/work\"\n  max_concurrent: 3\n  max_prompt_size: 102400    # 100KB\n  max_output_size: 1048576   # 1MB\n  env:\n    CLAUDE_CODE_ENTRYPOINT: \"herald\"\n    CLAUDE_CODE_DISABLE_AUTO_UPDATE: \"1\"\n\nprojects:\n  my-api:\n    path: \"/home/you/projects/my-api\"\n    description: \"Main backend API\"\n    default: true\n    allowed_tools:\n      - \"Read\"\n      - \"Write\"\n      - \"Edit\"\n      - \"Bash(git *)\"\n      - \"Bash(go *)\"\n      - \"Bash(make *)\"\n    max_concurrent_tasks: 1\n    git:\n      auto_branch: true\n      auto_stash: true\n      auto_commit: true\n      branch_prefix: \"herald/\"\n\ntunnel:\n  enabled: false               # Set to true to enable ngrok tunnel\n  provider: \"ngrok\"\n  authtoken: \"\"                # or set HERALD_NGROK_AUTHTOKEN env var\n  # domain: \"\"                 # optional: fixed domain (paid ngrok plans)\n\nrate_limit:\n  requests_per_minute: 200\n  burst: 100\n\n```\n\n</details>\n\n## MCP Tools\n\nHerald exposes 10 tools that Claude Chat discovers automatically via the MCP protocol:\n\n| Tool | What it does |\n|---|---|\n| `start_task` | Launch a Claude Code task. Returns an ID immediately. Supports priority, timeout, session resumption, and Git branch options. |\n| `check_task` | Check status and progress. Optionally include recent output. |\n| `get_result` | Get the full result of a completed task (`summary`, `full`, or `json`). |\n| `list_tasks` | List tasks with filters — status, project, time range. |\n| `cancel_task` | Cancel a running or queued task. Optionally revert Git changes. |\n| `get_diff` | Git diff for a task's branch or uncommitted changes. |\n| `list_projects` | List configured projects with Git status. |\n| `read_file` | Read a file from a project (path-safe — cannot escape project root). |\n| `herald_push` | Push a Claude Code session to Herald for remote monitoring and continuation from another device. |\n| `get_logs` | View logs and activity history. |\n\n## Security\n\nHerald exposes Claude Code to the network. We take that seriously.\n\n| Layer | Protection |\n|---|---|\n| **Network** | Binds to `127.0.0.1` only. HTTPS via built-in ngrok tunnel or reverse proxy (Traefik/Caddy). |\n| **Auth** | OAuth 2.1 with PKCE. Every request needs a valid Bearer token. |\n| **Tokens** | Access tokens: 1h. Refresh tokens: 30d, rotated on each use. |\n| **Filesystem** | Path traversal protection on all file operations. Symlink escapes blocked. |\n| **Execution** | Per-project tool restrictions. No blanket `--dangerously-skip-permissions`. |\n| **Rate limiting** | 200 req/min per token (configurable). |\n| **Timeouts** | Every task has a deadline (default: 30min). No runaway processes. |\n| **Prompts** | Passed to Claude Code unmodified. No injection, no enrichment, no rewriting. |\n| **Audit** | Every action logged with timestamp and identity. |\n\n## Architecture\n\n```\nClaude Chat (mobile/web)\n  → HTTPS (MCP Streamable HTTP + OAuth 2.1)\n  → Traefik / Caddy (TLS termination)\n  → Herald (Go binary, port 8420)\n    ├── MCP Handler (/mcp)\n    ├── OAuth 2.1 Server (PKCE, token rotation)\n    ├── Task Manager (goroutine pool, priority queue)\n    ├── Executor Registry (pluggable backends, default: Claude Code)\n    ├── SQLite (persistence)\n    └── MCP Notifications (server push via SSE)\n```\n\n**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).\n\n<details>\n<summary><strong>Tech stack</strong></summary>\n\n| Component | Choice | Why |\n|---|---|---|\n| Language | Go 1.26 | Single binary, cross-compilation, goroutines |\n| MCP | [mcp-go](https://github.com/mark3labs/mcp-go) | Streamable HTTP, official protocol support |\n| Router | [chi](https://github.com/go-chi/chi) | Lightweight, stdlib-compatible |\n| Database | [modernc.org/sqlite](https://gitlab.com/cznic/sqlite) | Pure Go, zero CGO |\n| Logging | `log/slog` | Go stdlib, structured |\n| Config | `gopkg.in/yaml.v3` | Standard YAML |\n\n6 direct dependencies. No ORM. No logging framework. No build toolchain.\n\n</details>\n\n## Deployment\n\nHerald runs best as a native binary (direct access to Claude Code and your files). Docker is available as an option.\n\n<details>\n<summary><strong>Docker Compose with Traefik</strong></summary>\n\n```yaml\nservices:\n  traefik:\n    image: traefik:v3\n    command:\n      - \"--entrypoints.websecure.address=:443\"\n      - \"--certificatesresolvers.le.acme.email=you@example.com\"\n      - \"--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json\"\n      - \"--certificatesresolvers.le.acme.httpchallenge.entrypoint=web\"\n    ports:\n      - \"443:443\"\n    volumes:\n      - \"./letsencrypt:/letsencrypt\"\n\n  herald:\n    build: .\n    network_mode: host\n    volumes:\n      - \"~/.config/herald:/root/.config/herald\"\n      - \"~/projects:/root/projects:ro\"\n    labels:\n      - \"traefik.http.routers.herald.rule=Host(`herald.yourdomain.com`)\"\n      - \"traefik.http.routers.herald.tls.certresolver=le\"\n      - \"traefik.http.services.herald.loadbalancer.server.port=8420\"\n```\n\n</details>\n\n## Roadmap\n\n| Version  | Status | Focus |\n|----------|---|---|\n| **v0.1** | ✅ Done | Core MCP server, async tasks, Git integration, OAuth 2.1, SQLite |\n| **v0.2** | 🚧 In progress | Shared memory — bidirectional context between Claude Chat and Claude Code |\n| **v0.3** | 🚀 Future | Stable API, plugin system |\n\nHave an idea? [Open an issue](https://github.com/btouchard/herald/issues). We build what users need.\n\n## Contributing\n\nHerald is in early alpha — the best time to shape a project.\n\n```bash\n# Get started\ngit clone https://github.com/btouchard/herald.git\ncd herald\nmake build && make test\n\n# Create your branch\ngit checkout -b feat/your-feature\n\n# Code, test, lint\nmake lint && make test\n\n# Open a PR\n```\n\nCommit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`, `docs:`).\n\nWhether it's a bug fix, a new notification backend, or a documentation improvement — all contributions are welcome.\n\n## Why Herald?\n\n| | Herald | Copy-paste workflow | Other tools |\n|---|---|---|---|\n| **Official protocol** | MCP Custom Connectors | N/A | Custom APIs, fragile |\n| **Your code stays local** | Always | Yes | Depends |\n| **Works from phone** | Native | No | Rarely |\n| **Self-hosted** | 100% | N/A | Often SaaS |\n| **Dependencies** | 6 | N/A | 50-200+ |\n| **Setup time** | ~5 minutes | N/A | 30min+ |\n| **CGO required** | No | N/A | Often |\n\nHerald uses the same protocol Anthropic built for their own integrations. No reverse engineering, no unofficial APIs, no hacks that break on the next update.\n\n---\n\n<p align=\"center\">\n  <a href=\"LICENSE\"><strong>AGPL-3.0 License</strong></a> — Built by <a href=\"https://kolapsis.com\"><strong>Benjamin Touchard</strong></a>\n  <br /><br />\n  If Herald saves you time, <a href=\"https://github.com/btouchard/herald\">leave a star</a>. It helps others find the project.\n</p>\n",
  "bytes": 17005,
  "sha": "185ce30579e7301629f1738c22cb45757bf55e60af531cc0483b12b87b5f59b9",
  "repo_slug": "btouchard/herald",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_btouchard_herald_6475149f/readme"
}