Skip to content

Add Herdsman support to your agent

If you build a coding agent, you can make it a first-class citizen in Herdsman from your own code. You don’t need a pull request to Herdsman, and you don’t need to wait for a Herdsman release.

Once your agent reports to Herdsman, users get:

  • your agent’s name and idle, working, or blocked state in the sidebar and in herdsman agent list
  • notifications when it finishes or needs a decision
  • herdsman agent wait and other automation that waits on agent state
  • the same session back in the same pane after a Herdsman server restart

Herdsman owns the integrations for agents whose vendors don’t ship one. If you maintain your agent, owning the integration yourself means you can fix it on your own release schedule.

Every process in a Herdsman pane inherits these environment variables:

Variable Meaning
HERDSMAN_ENV 1 inside Herdsman
HERDSMAN_PANE_ID The pane your agent runs in
HERDSMAN_BIN_PATH The Herdsman binary that owns this pane
HERDSMAN_SOCKET_PATH Herdsman’s API socket

Your agent makes three kinds of reports through "$HERDSMAN_BIN_PATH":

  1. State. Report idle, working, or blocked whenever it changes.
  2. Resume command. Report the command that reopens the current session.
  3. Release. Release the pane when your agent exits.

Only report when HERDSMAN_ENV=1 and the other variables are set. Outside Herdsman, your integration should do nothing.

Terminal window
"$HERDSMAN_BIN_PATH" pane report-agent "$HERDSMAN_PANE_ID" \
--source my-agent \
--agent my-agent \
--state working \
--seq 1
  • Report working when a turn starts, idle when your agent is ready for input, and blocked when it needs the user to decide something. Add --message to explain a block.
  • --agent is the name users see. Use your own agent’s name, not the name of an agent Herdsman already supports.
  • --source identifies your integration. Keep it stable and unique. Don’t start it with herdsman:, because Herdsman’s own integrations use that prefix.
  • --seq is optional but recommended. It must increase with every report from your source, including across sessions and restarts of your agent. A timestamp works well. Herdsman ignores reports whose number is not higher than the last one it accepted, so late or out-of-order reports can’t overwrite newer state.

To change how your agent appears without changing its state, such as a title or custom status text, see Custom status labels.

Put the command that resumes the current session after --. Include the options that session needs, such as the model or permission mode, so the resumed session behaves the same:

Terminal window
"$HERDSMAN_BIN_PATH" pane report-agent "$HERDSMAN_PANE_ID" \
--source my-agent \
--agent my-agent \
--state idle \
--seq 2 \
--agent-session-id "$SESSION_ID" \
-- my-agent --resume "$SESSION_ID" --model my-model

You can attach the command to any state report, or send it with pane report-agent-session when only the session changes. Report it again whenever your agent switches sessions.

After a Herdsman server restart, Herdsman opens the pane in the same directory and runs that command there. The command must follow these rules:

  • The first word is a plain command name on the user’s PATH, such as my-agent, not a path.
  • No argument contains an apostrophe or a control character.
  • At most 64 arguments and 8 KiB in total.
  • Your source must hold the pane first, so send a state report with report-agent before or along with the command. Otherwise Herdsman answers with resume_not_accepted.

Herdsman rejects a command that breaks the first three rules with invalid_resume_argv and does not apply that report. Users can turn off resume with [session] resume_agents_on_restore = false.

Terminal window
"$HERDSMAN_BIN_PATH" pane release-agent "$HERDSMAN_PANE_ID" \
--source my-agent \
--agent my-agent \
--seq 3

Releasing clears your agent’s name, state, and resume command from the pane right away. Only release when the user actually quits. If your agent replaces one session with another in the same process, report the new session instead of releasing.

If your agent exits without releasing, Herdsman notices once the pane is back at its idle shell prompt and clears the agent and its resume command. This usually takes a second or two. It is a safety net, not a replacement for releasing.

  • Don’t let Herdsman slow your agent down. Send reports in the background or with a short timeout, and ignore failures.
  • Send only the latest state. If several changes queue up while a report is in flight, drop the older ones.
  • Resume commands need Herdr 0.9.2 or later. Older versions ignore them, so state reports and release keep working there.

HERDSMAN_BIN_PATH and the CLI are the portable choice, including on Windows. If your agent needs direct IPC, send the equivalent pane.report_agent, pane.report_agent_session, and pane.release_agent requests described in the Socket API. The resume command goes in the resume_argv array.

Start your agent in a Herdsman pane, then check what Herdsman sees:

Terminal window
herdsman pane get "$HERDSMAN_PANE_ID"
herdsman agent list

To test restore without touching your normal session, use a separate named session:

  1. Start herdsman --session my-agent-test, then run your agent in a pane.
  2. Stop that session with herdsman session stop my-agent-test.
  3. Start herdsman --session my-agent-test again. The pane should run your resume command and your agent should report again.