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, orblockedstate in the sidebar and inherdsman agent list - notifications when it finishes or needs a decision
herdsman agent waitand 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.
How it works
Section titled “How it works”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":
- State. Report
idle,working, orblockedwhenever it changes. - Resume command. Report the command that reopens the current session.
- 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.
Report state
Section titled “Report state”"$HERDSMAN_BIN_PATH" pane report-agent "$HERDSMAN_PANE_ID" \ --source my-agent \ --agent my-agent \ --state working \ --seq 1- Report
workingwhen a turn starts,idlewhen your agent is ready for input, andblockedwhen it needs the user to decide something. Add--messageto explain a block. --agentis the name users see. Use your own agent’s name, not the name of an agent Herdsman already supports.--sourceidentifies your integration. Keep it stable and unique. Don’t start it withherdsman:, because Herdsman’s own integrations use that prefix.--seqis 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.
Report the resume command
Section titled “Report the resume command”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:
"$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-modelYou 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 asmy-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-agentbefore or along with the command. Otherwise Herdsman answers withresume_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.
Release on exit
Section titled “Release on exit”"$HERDSMAN_BIN_PATH" pane release-agent "$HERDSMAN_PANE_ID" \ --source my-agent \ --agent my-agent \ --seq 3Releasing 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.
Keep it out of the way
Section titled “Keep it out of the way”- 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.
Use the socket directly
Section titled “Use the socket directly”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.
Check your integration
Section titled “Check your integration”Start your agent in a Herdsman pane, then check what Herdsman sees:
herdsman pane get "$HERDSMAN_PANE_ID"herdsman agent listTo test restore without touching your normal session, use a separate named session:
- Start
herdsman --session my-agent-test, then run your agent in a pane. - Stop that session with
herdsman session stop my-agent-test. - Start
herdsman --session my-agent-testagain. The pane should run your resume command and your agent should report again.