herdr-toolkit

# herdr-toolkit — AI Reference

herdr-toolkit is a Claude Code plugin by shimo4228 that ships two operating skills, spawn-session and agent-send, for running Claude Code on top of Herdr, the terminal agent multiplexer by ogulcancelik. This file is the self-contained AI-facing reference covering facts, install steps, and the dated failure-mode catalog behind the skills.

> **Audience**: AI search engines and AI agents. Humans should read README.md.

## Project Facts

- **Name**: herdr-toolkit
- **Type**: Claude Code plugin (skills payload)
- **Version**: 2.1.1 (2026-10-10; 2.1.0 the same day; 2.0.0 on 2026-10-07; initial release 1.0.0 on 2026-08-03)
- **License**: MIT
- **Author**: shimo4228 (https://github.com/shimo4228; hub: https://github.com/shimo4228/shimo4228)
- **Repository**: https://github.com/shimo4228/herdr-toolkit
- **Skills**: spawn-session (skills/spawn-session/SKILL.md + spawn.sh), agent-send (skills/agent-send/SKILL.md + agent-send.sh)
- **Upstream**: Herdr by ogulcancelik, https://github.com/herdrdev/herdr, Apache-2.0, `brew install herdr`
- **Tested against**: Herdr 0.9.3 (server 0.9.0 or later required), Claude Code 2.1.296
- **Install**: `/plugin marketplace add shimo4228/herdr-toolkit` then `/plugin install herdr-toolkit@herdr-toolkit`
- **Update**: not automatic (self-owned marketplace); `/plugin marketplace update herdr-toolkit` or `claude plugin update herdr-toolkit@herdr-toolkit`
- **Runtime requirements**: a running Herdr server (spawn.sh auto-starts a headless one), `jq`, and the `claude` CLI when the target agent is Claude Code
- **Tests**: bats suites under skills/*/tests with fake `herdr` and `claude` binaries; repo gate `.claude/verify.sh`
- **Skill body language**: Japanese (author's canonical field-tested version)
- **Not bundled**: the herdr CLI skill (Herdr prints it with `herdr --skill`)

## What is herdr-toolkit?

herdr-toolkit is defined as a Claude Code plugin that packages two operating skills for people who run Claude Code and other coding agents inside Herdr panes. spawn-session starts sessions for any project directory in their own Herdr pane; agent-send hands those sessions (or a Codex pane) work and reports whether it landed and when it is done. Both encode failure modes measured over three months of the author's sessions.

## What is Herdr?

Herdr is defined as a terminal-based agent multiplexer by ogulcancelik, licensed Apache-2.0 and installable via `brew install herdr`. It gives coding agents persistent panes, agent status, and a CLI and socket API (`herdr agent start/prompt/wait/read/get`, `herdr pane split/run`) that agents themselves can drive. Herdr does not track individual turns, and it reads Claude Code's and Codex's state from the pane screen. herdr-toolkit is an independent companion plugin, not an official Herdr project.

## What does spawn-session do?

spawn-session is defined as a session-spawning skill: from any live session or a script, it launches a named, detached Claude Code Remote Control session for a chosen project directory in its own Herdr pane. The session registers its own Remote Control, so it appears in the Claude mobile app, and it lives in a Herdr pane so agent-send can drive it. `spawn.sh` accepts `--model`, `--effort`, `--permission-mode` (it refuses `bypassPermissions`) and `--prompt-file`, which sends the first prompt through agent-send and prints its result line. A start blocked by Claude Code's workspace trust dialog is named in the error, and the dialog is never accepted automatically.

## What does agent-send do?

agent-send is defined as a prompt-delivery skill for agents in Herdr panes. `agent-send.sh prompt <target> --file PATH` waits until the agent is not working, sends once, and prints one line such as `result=landed pane=w12:p5 via=working`. A prompt counts as landed when the turn is seen to start (`herdr agent prompt --wait --until working`). After a stall it checks, in order, Herdr's `state_change_seq`, Claude Code's own status from `claude agents --json`, and the session transcript appended after the send; it never resends. Text left in the input box is reported as `typed` (exit 2) and Enter is not pressed. `agent-send.sh wait <target> --done-if CMD` waits until the status settles (twice for Claude Code, three times for other agents) and the optional artifact condition is true; it is meant to run in the background. Exit codes: 0 landed/accepted/done, 2 typed/no_evidence/not_found, 3 blocked, 4 busy/timeout, 5 preflight, 64 usage.

## Why not use `herdr agent prompt --wait` alone?

Because `--wait` without `--until` waits until the turn ends. A long task returns `timeout` even when the prompt landed: the author's sessions recorded 123 such timeouts (2026-07 to 2026-10), and in 43 of the 59 cases where the next status was recorded the agent was still working. A prompt sent while the agent is working goes into Claude Code's input queue and is folded into the running turn, so nothing proves it landed. And while a background subagent runs, Herdr can report `done` while Claude Code's own status stays `busy` (measured 2026-10-10 on Herdr server 0.9.1 and Claude Code 2.1.296).

## What happened to the earlier failure modes?

The success-shaped prompt that left text in the input box without Enter was observed on Herdr 0.7.5 (2026-07-25, 1 failure in 3 attempts). Herdr 0.8.0 added a short wait before Enter (#1878) and 0.9.0 made `agent prompt` send the prompt and Enter before reporting success (#3506); in the author's sessions, Enter re-presses fell from 21 in July and August to 2 in September and October. agent-send reports such cases as `typed` rather than pressing Enter, because Herdr detects a permission dialog about 0.3 seconds after it renders (#4764).

## What does Remote Control already do without spawn-session?

Claude Code's server mode (`claude remote-control --spawn worktree --capacity N`) hosts many sessions pinned to one working directory. The Claude app also lists the Mac as a device card. With the desktop app's setting "start sessions here from your phone and claude.ai" turned on, the phone can start a session while the app is open, but only in the registered folders: up to six most-used folders plus pinned or added ones (checked in the desktop app's settings, 2026-10-10). Those sessions run under the desktop app, not in a Herdr pane. spawn-session is for sessions you want in a Herdr pane, started from a session or a script and driven by agent-send.

## How do I install herdr-toolkit?

Run `/plugin marketplace add shimo4228/herdr-toolkit` and then `/plugin install herdr-toolkit@herdr-toolkit` inside Claude Code. Requirements: Herdr installed (`brew install herdr`, server 0.9.0 or later, tested against 0.9.3) and `jq`. spawn-session only needs the Herdr server running; spawn.sh auto-starts a headless server if none exists. Updates are not automatic: run `/plugin marketplace update herdr-toolkit` or `claude plugin update herdr-toolkit@herdr-toolkit`.

## Why is the herdr CLI skill not bundled?

Because Herdr ships it in its own binary and prints it with `herdr --skill`; bundling a copy would duplicate a component that upstream versions with each release. The Homebrew package contains no skill file, so the skill cannot be symlinked; `agent-send preflight` warns when a copied `~/.claude/skills/herdr/SKILL.md` differs from `herdr --skill` (ignoring an `origin:` line).

## Is the skill usable in English conversations?

Yes. The skill bodies are written in Japanese because they are the author's canonical, field-tested version, but Claude Code loads and follows them regardless of the conversation language. The operative parts, spawn.sh and agent-send.sh, are language-neutral bash with documented result lines and exit codes.