Herald

Agents

Coding agents can reach you through Herald when they finish, get stuck or need a decision, even when you are away from the terminal. Skills teach Claude Code and Codex when and how to use the CLI; @herald-run/mcp is an MCP server that gives any other MCP client Herald tools.

Herald can also take the place of an agent harness's own question tool, such as Claude Code's AskUserQuestion: an agent told to ask through Herald sends every question to one inbox, answerable from your phone or desktop. The herald-ask skill and MCP ask take questions in AskUserQuestion's shape. To route every question, say so in the agent's instructions (CLAUDE.md, AGENTS.md), for example: Ask me every question through the herald-ask skill instead of AskUserQuestion.

An agent setting Herald up for you can read herald.run/agents: this material, pricing and the setup steps condensed into one Markdown page.

Claude Code and Codex

npm install -g @herald-run/cli
herald login

Then install the skills from herald.run/skills, one SKILL.md per skill: Claude Code reads ~/.claude/skills/<name>/ (or .claude/skills/ in a repository), Codex ~/.codex/skills/<name>/ (or .agents/skills/). Restart the agent afterwards. The skills:

  • herald-send-file: send a report, log, image or PDF with a summary.
  • herald-ask: ask for approval, a choice, questions or form input, before risky steps or in place of the agent's own question tool, and wait.
  • herald-get-secret: request a credential straight into a private file.
  • herald-share-secret: send a credential from a file through encrypted delivery.
  • herald-get-file: request a sensitive file straight into a private file.

MCP clients

Run the server over stdio with npx -y @herald-run/mcp. For example, in a client's JSON config:

{
  "mcpServers": {
    "herald": { "command": "npx", "args": ["-y", "@herald-run/mcp"] }
  }
}

It authenticates with HERALD_API_KEY (or HERALD_TOKEN) if set, otherwise with the CLI's stored login for HERALD_PROFILE. HERALD_URL selects another server. Use a connection with only the scopes the agent needs.

Tools

Tool Arguments Returns
send title, body (Markdown), files (paths), replyTo {id, status}
ask title, body, one of approval, choices, fields, schema; files, deadline, wait {status, values, actionId, approved | choice}
wait id, wait status and answer
cancel id the cancelled request
get_message id the full record
list_messages search, status, direction, before summaries, newest first
thread id the thread, oldest first
upload_file path an attachment
download_file id, messageId (carries the file), path (new file) {path, size}
request_secret path (new file), label, title, wait {id, status: "stored", path}
send_secret path, title, wait {id, status: "delivered"}
request_file path (new file), label, title, body, wait {id, status: "stored", path}

ask and wait block for wait (default 10 minutes) and then return status: "pending" with the message ID, so the agent can keep working and call wait later; the request itself stays open until its deadline (default 1 hour). Durations look like 90s, 10m or 2h.

Secret values and requested files never appear in tool results: request_secret and request_file write to a new file with mode 0600, and send_secret reads it from one. Point tools at those files instead of printing them.

Scripts and CI

Scripts can call the CLI directly too: herald send and herald ask cover every message, form, file and secret through flags, and herald register the task types; see the CLI reference. In CI, set HERALD_API_KEY from a secret and gate steps on an approve button as in the Quickstart.