herderp

A Claude Code plugin: a stdio MCP server wrapping the herdr CLI with curated one-shot tools, plus session necromancy — find and read a previous Claude Code agent session from a herdr "space."

What it does

• Curated herdr tools — MCP calls over the herdr CLI instead of hand-typing it. One tool per resource, each taking an action, so ~35 CLI subcommands cost six tools rather than thirty-five:

  • herdr_agent — list/get/read/send/focus/rename/start/wait/explain.

  • herdr_pane — list/get/run/close/rename/focus/split/swap/move.

  • herdr_tab and herdr_workspace — list/get/create/rename/focus/close.

  • herdr_worktree — list/create/open/remove.

  • herdr_session_list — herdr's own named server sessions (not Claude Code sessions).

  • herdr_host — list/add/remove/check the named remote hosts every tool above accepts via an optional host field (see below).

  Every result carries a hint naming the natural next call, and a missing field is rejected by name (herdr_agent{action:"get"} requires "target") rather than falling through to herdr's usage text. herdr's own integration plumbing (pane report-agent/report-metadata/release-agent) and the interactive agent attach --takeover are deliberately not exposed.

• Necromancy — catch up on past Claude Code work by reading session transcripts in place (reading only; nothing is ever revived):

  • necromancy_digest — "what's been happening here": the newest sessions of a space in one call (default 5, max 10), each with its ask, where it ended, and its newest anchors. Skips the running session, marks earlier catch-ups (catchUp), and leaves out headless SDK runs unless asked (headlessSkipped counts them).

  • necromancy_search_all — search the content of sessions when you know what happened but not where: one entry per matching session (its space, id, match count, a representative snippet, last activity), newest first. Scans the whole local history by default (up to 2000 transcripts); truncated/scanTruncated say when a bound cut it short.

  • necromancy_find_spaces — the projects with recorded sessions, joined with live herdr workspaces, newest-active first and capped; narrow with query. Degrades to an unlabeled list (degraded: true) if herdr is unreachable.

  • necromancy_resolve — turn a herdr agent handle (upublish:1 = workspace label upublish, tab labeled 1; :1 or a bare 1 = tab 1 in the current space) into the exact live session it addresses. Ambiguity and misses come back as candidates / a typed reason to fall through, not a wrong guess.

  • necromancy_list_sessions — every session in a space, newest first, marked live vs dead, with a preview, the herdr handle for live ones, and entrypoint for headless launches. Degrades to a still-usable list (marked) if herdr is unreachable.

  • necromancy_anchors — regex-extract a session's "always grab" set (ask, final state, commits, PRs, versions, files touched, errors, test results, decisions). Each item is {text, index} — the turn it came from — and each list keeps its newest entries, with omitted counting what was dropped. No model call.

  • necromancy_outline / necromancy_search / necromancy_read — read a session's turns: outline its shape (view: "spine" for just the asks and replies), search it by keyword or regex, and pull specific turns back verbatim (toolResultChars clips tool output), all capped on count and bytes.

• necromancy skill — picks the entry point (digest, cross-session search, handle, or a named space), reads only what matters, and stays honest about every cap.

• /herderp:ghost command — a one-shot catch-up: the previous session by default, or point it at a space, a handle, or a session id. Get a plain summary of what it did and where it stopped, with turn citations and questions to resume. Reading only — it never revives.

Related MCP server: goose-herdr

Remote hosts

Every herdr_* tool takes an optional host. Omit it for this machine's herdr server; name a registered host to drive the herdr server on another machine instead — herdr_agent{action:"prompt", target:"w6:p2E", text:"...", host:"ska"} asks an agent on ska. The necromancy tools read this machine's session files and take no host.

Hosts live in ~/.config/herderp/hosts.json (override with HERDERP_HOSTS_PATH), which herdr_host{action:"add"} writes for you and which is re-read on every call, so edits need no restart:

{
  "hosts": {
    "ska": {
      "ssh": "100.64.0.10",
      "user": "jane.doe@corp.example",
      "herdr": "/opt/homebrew/bin/herdr"
    },
    "box": "me@box.example"
  }
}

• ssh is the destination as ssh takes it: a hostname, IP, user@host, or a ~/.ssh/config alias. The string shorthand is just { "ssh": ... }.

• user (optional) is passed as ssh -l; use it for account names containing @, which user@host would mis-split.

• herdr (optional) is the remote binary when it is not on ssh's non-interactive PATH. ~/.local/bin and /opt/homebrew/bin are searched by default.

• socket (optional) selects a non-default remote server session via HERDR_SOCKET_PATH.

Each call is one ssh exec of the remote machine's own herdr binary, so the two herdr versions need not match and nothing long-lived has to be babysat. ssh runs in BatchMode (it will never prompt — keys or Tailscale SSH must already work; run herdr_host{action:"check"} once after adding a host to prove it) and accepts a new host key on first contact. herdr's exit status travels in-band, because Tailscale SSH reports exit 0 regardless of what the remote command returned. ssh's own failures come back as [host_unreachable], an unregistered name as [unknown_host] naming the known hosts.

How reading works

Claude sessions persist on disk at ~/.claude/projects/<cwd-slug>/<uuid>.jsonl independent of herdr pane life (the slug maps every non-alphanumeric character in the cwd to - — /, ., _, @ and the rest — without collapsing runs, so prod-_x becomes prod--x). Necromancy enumerates them from disk and reads their turns in place — no pane, no relaunch. The reader parses the raw jsonl, skips empty/oversized/malformed files by stat alone, and validates every session id against a strict UUID regex before touching the filesystem.

Requirements

• bun on PATH (the server runs under bun; dependencies auto-install on first launch — no bun install needed).

• A running herdr server and the Claude Code session store at ~/.claude/projects. Both degrade gracefully with a clear message if absent.

• For remote hosts: ssh on PATH and non-interactive access to each host (keys or Tailscale SSH).

Install

Via the rtd marketplace:

/plugin marketplace add ryanthedev/rtd-claude-inn
/plugin install herderp@rtd

Development

bun install
bun test            # unit + integration (side-effect-free)
bun run start       # boot the MCP server on stdio

Scope (v1)

Claude agents only; reading only (find, list, and read past sessions in place). Non-Claude agent kinds are a later seam.