herdr-comms

Files (7)

• SKILL.md
• herdr-await · assets/
• herdr-claude-session · assets/
• herdr-close · assets/
• herdr-say · assets/
• herdr-spawn · assets/
• herdr-wake · assets/

SKILL.md (first lines)

# herdr-comms

Thin wrappers over native Herdr. Herdr itself owns the transport; these
exist only for the failure modes it leaves to the caller, and for parking an
idle Claude agent so it holds no memory while it waits.

Every wrapper acts only in the caller's Herdr session,
`${HERDR_SESSION:-default}`: pane, tab, and space ids repeat across sessions.
`octo-lite-state` prints the caller's session state directory, holding `lanes/`
(lane records, hand-off logs, notes, `archive/`), `operator.toml`, and
`operator.handoffs.jsonl` (spec `#session-state`).

## Spawn an agent

```
herdr-spawn --workspace ID --name NAME --label LABEL --cwd DIR --role ROLE \
  -- claude    # default
herdr-spawn --workspace ID --name NAME --label LABEL --cwd DIR --role ROLE \
  -- codex     # non-default alternative
herdr-spawn --workspace ID --name NAME --label LABEL --cwd DIR --role ROLE \
  -- pi        # non-default alternative
```

A lane worker spawns into its lane space, `--workspace "$HERDR_WORKSPACE_ID"`,
named `<role>-<ticket>` lowercase (`implementer-ann-64`). A pane never moves
between spaces: Herdr rewrites its ids.

Spawn bare, then send the brief with `herdr-say`, or with `herdr-await` to wait
on the agent (below). Nothing follows the runtime:
with an inline prompt, `herdr agent start` times out waiting for readiness.

One tab, one pane, one agent, at an explicit worktree. Prints:

```
name= role= tab= pane= cwd= contract= provider_session_id=
```

The runtime comes from the agent definition and each CLI's own defaults. This
pins no model, effort, or service tier.

`--role` is not just a label. A Claude agent loads its own contract through
`--agent ROLE`, which `herdr-spawn` passes with `--name NAME`, so Claude's own
session list names it as Herdr does. Codex has no custom-agent file, so
the contract at `~/.claude/agents/ROLE.md` is passed as `-c developer_instructions=...`. It
binds at the developer layer and the agent waits for its brief; a contract sent
as a prompt is worked as a task. Pi has neither, so it gets the contract file
through `--append-system-prompt FILE`. The output reports `contract=` so a
silent miss is visible.

`--operating-model FILE` is optional. It hands that file to the agent at start,
so no global instruction file is needed: Claude gets
`--append-system-prompt-file FILE`, Codex gets it ahead of the contract in
`developer_instructions`, pi gets `--append-system-prompt FILE` ahead of the
contract's. It defaults to `$OCTO_LITE_OPERATING_MODEL`, and the
spawn exports that path into the new tab, so every child inherits the model
without passing the flag. Without either, nothing changes.

A new tab gets the Herdr server's environment, so the spawn always exports the
caller's `HOME` into it. The agent and every child it spawns keep the caller's
home: git identity, consent, and sessions.

Codex runs with `--no-daemon`, so its thread and commands live in the tab's own
process tree, not the shared app-server that outlives the tab.

It wraps `herdr tab create` and `herdr agent start`, and handles three things
those leave to the caller:

- A freshly created pane is not yet at a shell prompt. Herdr reports
  `agent_pane_busy`; only that code is retried, with backoff.
- An agent that opens its trusted-folder dialog makes `agent start` report
  `agent_not_ready`. That is a started agent waiting on a keystroke, not a
  failure.
- The dialog is answered at the **pane**, never blindly. A blocked agent refuses
  agent-level input, and the highlighted row may be `No, exit`, where a bare
  Enter kills the agent being spawned. The selection is moved onto the trust
  option and verified before confirming.

Any failure closes the tab, so a failed spawn never leaves an orphan.

`--resume SESSION` (Claude only) starts a parked agent as it was launched:
Claude gets `--name NAME --agent ROLE --resume SESSION` and keeps its
conversation. An owner resumes through `octo-lite-start --cwd WORKTREE --name
LANE --resume SESSION`, in a new lane space. `herdr-say` does both for you; see below.

## Close an agent or a lane space

```
herdr-close TAB
herdr-close SPACE
```

The teardown step. An id with a colon (`w5:t2`) is a tab, one without (`w5`) is
a space. Closes it, then sends TERM to every process of the caller's session
whose environ carries `HERDR_TAB_ID=TAB` or `HERDR_WORKSPACE_ID=SPACE`, which
catches detached children that close alone leaves running, and ends whole each
`herdr-await` of the caller's own pane on an agent in it, by name or pane id,
read from `herdr agent list` before the close, sending no message (a `--notice`
wait prints `closed by its caller`): you closed it, so no stop reads as news of
an agent spawned again under the same name (spec `#transport-close-waits`).
Another caller's wait on it ends as gone at its bound. Parking (below) closes
the same way. Run it from outside
what it closes: the spawner closes a tab, the operator closes a finished lane's
own space, or only its owner tab when the lane started in a shared space.
Prints one closed hand-off line (`at kind tab|space close_rc killed`; spec
`#transport-close-line`), which an owner closing a consumed worker appends to
the lane's hand-off log, and exits with the close status.

## Park an idle agent

```
herdr-close --park PANE >>"$lanes/<lane>.handoffs.jsonl"
```

`$lanes` is `$(octo-lite-state)/lanes`. Reads the Claude session of PANE, a
pane of the caller's session, by `herdr-claude-session` (below), closes its
tab, or its whole space when that tab is the space's only one (a lane owner in
its own space), and prints one parked line (`at kind pane name role cwd
session`) on stdout, even when the close fails; its closed line goes to
stderr. The role is the session record's, else the one a worker's spawn name

From varelaseb/octo-lite, Apache-2.0.

More from varelaseb/octo-lite