Skip to content
Back to search

herdr-subagent

Run opencode, agy, codex, or claude as a visible, steerable pseudo-subagent in herdr, reporting back through a compact report file.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jpbaking--herdr-subagent/badge.svg)](/listings/jpbaking--herdr-subagent)

HTML

<a href="/listings/jpbaking--herdr-subagent"><img src="/api/listings/jpbaking--herdr-subagent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installation is agent-guided only; there are no install scripts. Paste this into Antigravity CLI, Codex, Claude Code, Gemini CLI, Cline, or OpenCode:

Install herdr-subagent. Using git with my existing credentials (do not
download raw files or archives), clone https://github.com/jpbaking/herdr-subagent
at tag v0.1.3 with --depth 1 and git's terminal prompt disabled
(GIT_TERMINAL_PROMPT=0) into a new temporary directory outside any project;
a "not a commit" warning about the tag is normal. If the clone fails for lack
of credentials, stop and tell me how to sign in. Then read AGENT-INSTALL.md
from that clone and follow it exactly. Merge with—never blindly overwrite—any
existing files, ask me which harnesses to install for, and report every file
you created or changed.

This prompt pins release `v0.1.3`. To install another release, change the tag; to track the default branch, drop `at tag v0.1.3`. On a fork, mirror, or enterprise host, substitute the remote you clone from.

**What the prompt does:** your agent clones this repository with your own git credentials and executes [AGENT-INSTALL.md](./AGENT-INSTALL.md), the authoritative install contract. It writes only the skill directory, to these user-global paths, and changes no instruction files and nothing in your repos:

| Harness | Skill destination | | --- | --- | | Antigravity CLI (`agy`) | `~/.gemini/antigravity-cli/skills/herdr-subagent/` | | Claude Code | `~/.claude/skills/herdr-subagent/` | | Codex, Gemini CLI, Cline, OpenCode | `~/.agents/skills/herdr-subagent/` |

AGENT-INSTALL.md also covers update and uninstall.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 161 lines
  1. # herdr-subagent
  2. A skill that turns any interactive coding-agent CLI running in
  3. [herdr](https://herdr.dev) into a **visible pseudo-subagent**. Your planner
  4. agent spawns a delegate (opencode by default; also `agy`, `codex`, or
  5. `claude`) in a herdr pane or tab, hands it a self-contained task, and then
  6. reads only a compact report file. It never reads the delegate's raw trace. You
  7. can watch the delegate work live in herdr's agent list.
  8. The delegate session stays open while the planner reviews the report. The
  9. planner can **steer** it with follow-up prompts that keep the session's
  10. context, and it **closes** the pane or tab once it accepts the result.
  11. The skill installs into Antigravity CLI, Codex, Claude Code, Gemini CLI,
  12. Cline, and OpenCode, any of which can act as the planner.
  13. https://github.com/user-attachments/assets/9b6b6661-b1ad-4d85-8be9-f75b2600ee60
  14. ## How it works
  15. ```text
  16. planner (you) delegate (herdr pane or tab)
  17. ─────────────── ────────────────────────────
  18. spawn sub-<task> opencode ──▶ interactive opencode starts
  19. prompt <prompt-file> ──▶ works; you can watch it
  20. wait (background, one notice) ◀── writes report, last line STATUS: …
  21. review: re-run checks, read diffs
  22. steer <follow-up> ──▶ continues with its context intact
  23. close ──▶ pane or tab closes
  24. ```
  25. - **Report contract.** Every prompt gets the same footer. The delegate writes
  26. a Markdown report (what it did, evidence, open questions) to
  27. `$TMPDIR/herdr-subagent/<name>-<time>.md` (`/tmp/…` when `TMPDIR` is
  28. unset). Its last line is `STATUS: success`, `STATUS: escalate - <question>`,
  29. or `STATUS: failed - <reason>`.
  30. - **Escalate, don't guess.** A delegate stuck on a decision escalates with
  31. the exact question. The planner answers it in the same open session.
  32. - **Wait outcomes.** `wait` exits with 0 success, 2 escalate, 3 failed,
  33. 4 blocked (a permission prompt is waiting in the pane), 5 idle without a
  34. report, 6 session gone, or 7 timeout.
  35. - **Layouts.** By default the first two open delegates share a column to the
  36. right of the planner, stacked top to bottom, and the third and later ones
  37. each get a background tab. `--layout split` or `--layout tab` overrides it.
  38. - **Concurrency.** The skill follows your stated limit, or one running
  39. delegate per model backend. Use that for a local model server that serves
  40. one session at a time.
  41. - **Goal Ledger.** With the
  42. [goal-ledger](https://github.com/jpbaking/goal-ledger) skills, this is the
  43. transport for a delegated phase. The executor gets the standard
  44. `goal-ledger-execute` prompt, `needs-human` escalations are answered in the
  45. phase file and then steered into the same session, and the session closes
  46. after the planner accepts the phase.
  47. ## Requirements
  48. - [herdr](https://herdr.dev) 0.7.5 or later, with the planner running inside it
  49. - `bash` and `jq`
  50. - At least one delegate CLI, installed, signed in, and on `PATH`:
  51. | Delegate | Verified |
  52. | --- | --- |
  53. | `opencode` | full lifecycle, split and tab, multi-turn steer, escalation |
  54. | `codex` | full round-trip |
  55. | `agy` | full round-trip |
  56. | `claude` | full round-trip |
  57. See [`references/harnesses.md`](.agents/skills/herdr-subagent/references/harnesses.md)
  58. for per-CLI flags and caveats. Tested on Linux; macOS should work but is
  59. untested. Windows needs WSL. `cline` is not supported, because herdr 0.7.5
  60. does not detect it as an agent.
  61. ## Install
  62. Installation is agent-guided only; there are no install scripts. Paste this
  63. into Antigravity CLI, Codex, Claude Code, Gemini CLI, Cline, or OpenCode:
  64. ```text
  65. Install herdr-subagent. Using git with my existing credentials (do not
  66. download raw files or archives), clone https://github.com/jpbaking/herdr-subagent
  67. at tag v0.1.3 with --depth 1 and git's terminal prompt disabled
  68. (GIT_TERMINAL_PROMPT=0) into a new temporary directory outside any project;
  69. a "not a commit" warning about the tag is normal. If the clone fails for lack
  70. of credentials, stop and tell me how to sign in. Then read AGENT-INSTALL.md
  71. from that clone and follow it exactly. Merge with—never blindly overwrite—any
  72. existing files, ask me which harnesses to install for, and report every file
  73. you created or changed.
  74. ```
  75. This prompt pins release `v0.1.3`. To install another release, change the
  76. tag; to track the default branch, drop `at tag v0.1.3`. On a fork, mirror, or
  77. enterprise host, substitute the remote you clone from.
  78. **What the prompt does:** your agent clones this repository with your own git
  79. credentials and executes [AGENT-INSTALL.md](./AGENT-INSTALL.md), the
  80. authoritative install contract. It writes only the skill directory, to these
  81. user-global paths, and changes no instruction files and nothing in your repos:
  82. | Harness | Skill destination |
  83. | --- | --- |
  84. | Antigravity CLI (`agy`) | `~/.gemini/antigravity-cli/skills/herdr-subagent/` |
  85. | Claude Code | `~/.claude/skills/herdr-subagent/` |
  86. | Codex, Gemini CLI, Cline, OpenCode | `~/.agents/skills/herdr-subagent/` |
  87. AGENT-INSTALL.md also covers update and uninstall.
  88. ## Usage
  89. Start your planner agent inside herdr and ask for the skill by name:
  90. - any harness: "Use the herdr-subagent skill to have opencode survey `src/`."
  91. - `agy`, Claude Code, Cline: `/herdr-subagent`
  92. - Codex: type `$` and select `herdr-subagent`
  93. - OpenCode: `@herdr-subagent`
  94. - Gemini CLI: name the skill in the prompt
  95. You can also run the bundled script yourself:
  96. ```sh
  97. S=~/.claude/skills/herdr-subagent/scripts/herdr-subagent.sh # or your harness's path
  98. $S spawn sub-survey opencode # auto layout; --layout split|tab; -- <cli flags>
  99. $S prompt sub-survey task.txt # prints the report path
  100. $S wait sub-survey /tmp/herdr-subagent/sub-survey-….md
  101. $S read sub-survey 40 # pane tail, for blocked/idle cases
  102. $S list
  103. $S close sub-survey
  104. ```
  105. ## Repository layout
  106. ```text
  107. AGENT-INSTALL.md # install contract (authoritative)
  108. AGENTS.md # contributor instructions
  109. CLAUDE.md # @AGENTS.md bridge for Claude Code
  110. .gemini/settings.json # points Gemini CLI at AGENTS.md
  111. .agents/skills/herdr-subagent/ # authoritative skill (the only install source)
  112. SKILL.md
  113. references/harnesses.md
  114. scripts/herdr-subagent.sh
  115. .claude/skills/herdr-subagent/ # generated byte-identical mirror
  116. tests/contract-test.sh # install-contract walk-through for CI
  117. ```
  118. ## Development
  119. ```sh
  120. bash -n .agents/skills/herdr-subagent/scripts/herdr-subagent.sh
  121. shellcheck .agents/skills/herdr-subagent/scripts/herdr-subagent.sh tests/contract-test.sh
  122. diff -r .agents/skills .claude/skills
  123. tests/contract-test.sh # walks AGENT-INSTALL.md against a scratch HOME
  124. ```
  125. The contract test clones the committed `HEAD` of this checkout, so commit
  126. first. Set `REMOTE` and `TAG` to test a published release instead. CI runs
  127. all of these on Linux and macOS. The delegate round-trips need a live herdr
  128. session and signed-in CLIs, so they are verified by hand before each release
  129. and recorded in `references/harnesses.md`.
  130. ## License
  131. This repository is licensed under [0BSD](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.