Herdr Agent Factory — Community Research & Architecture

01 · Executive verdict

Use Herdr as an execution substrate, not as the source of truth.

✓

Excellent at

Persistent PTY panes, workspaces, worktrees, agent visibility, local control, waits, event subscriptions, plugins, and human supervision.

!

Does not provide

A durable task queue, leases, authorization between workers, conflict arbitration, model routing, cost governance, or exactly-once execution.

→

Recommended shape

One scheduler owns task truth; Herdr adapters provision one isolated worktree and pane per mutable attempt; workers exchange versioned artifacts.

The key distinction

Herdr can start, observe, read, signal, and wait on agents. Those primitives make orchestration possible; they do not decide what is safe to dispatch or when work is accepted.

High confidence

02 · Community evidence

What people are actually doing

The strongest pattern is controlled concurrency: role separation, worktree isolation, artifact handoffs, and visible review gates. The evidence does not support an autonomous, self-correcting swarm.

X · official29,202 views

Plugins are a first-class workflow surface

Herdr's official account demonstrated PR review and follow-up edits inside Herdr, recommending existing plugins or a custom plugin for a different UX. The same thread describes popup, split, and overlay panes, keybindings, automation scripts, and plugins as an escalation path.

Open primary post ↗

X · operator17 Jul 2026

A command center for workspaces and agents

Stefano Sandes reported a custom Cmd+P-style plugin for switching among workspaces and agents and invoking plugins or internal actions. This is a human routing layer—not autonomous strategy.

Open post ↗

X · operatorStrongest factory pattern

Nested tasks, worktrees, sequential context reuse

Fabian Schuh described a plugin that walks nested beans in a milestone: worktrees at milestone and epic/feature levels; tasks run sequentially, reuse context, and commit per task. It optimizes context continuity and Git safety over maximum fan-out.

Open post ↗

Reddit · operatorHermes + OpenCode + Herdr

Specs beat Kanban prompts

A home-server operator separated roles into Hermes profiles, used OpenCode as a coding worker, and Herdr for sessions. Markdown spec handoffs, Git guardrails, and a second reviewing session worked; direct Kanban instruction and continuous self-improvement did not.

Open collected search ↗

Reddit · ecosystemworking / idle / done / blocked

The product value is an attention queue

The tmux-agents-mon discussion, explicitly inspired by Herdr, focuses on knowing which agent needs attention. Operators value persistent terminals and state rollups because forgotten panes—not lack of raw spawn capacity—become the bottleneck.

Open collected search ↗

GitHub · discovery onlyNot source-audited

Early ecosystem leads

Search surfaced projects named herdr-goal-skill, herdr-factory, pi-apnea, pi-bstn-subagents, herdr-lazy, and PR/session plugins. These are leads, not evidence: the assigned GitHub lane could not safely verify its exact Helium window and did not inspect repository content.

Open repository search ↗

Evidence boundary. X and Reddit posts establish that these operators reported these workflows. They do not prove reliability, causality, or production readiness. The GitHub ecosystem lane is explicitly incomplete; no repository descriptions from it are treated as facts.

03 · Official Herdr capabilities

The primitives a factory can safely build on

Layer

Verified surface

Factory meaning

RuntimePersistent server-owned PTYs; workspace → tab → pane hierarchy; named sessions; local and SSH attach.Durable floor

AgentsDetect/start/attach/list/read/send; semantic states; waits; state rollups; native session references where supported.Visible workers

ControlCLI plus newline-delimited JSON over a Unix socket or Windows named pipe; schema is discoverable from the installed binary.Adapter boundary

GitCreate/open/list/remove worktrees and associate them with workspaces.Isolation primitive

PluginsOut-of-process executable packages with actions, event hooks, terminal panes, and link handlers; full local command authority.Power + risk

Representative CLI loop

# Create an isolated workspace
herdr workspace create --cwd ~/project --label api

# Start a worker in a split
herdr agent start reviewer --cwd ~/project --split right -- pi

# Start a worker in a known workspace/tab
herdr agent start docs --workspace w1 --tab w1:t1 -- claude

# Observe and wait
herdr pane read w1:p2 --source recent --lines 50
herdr wait agent-status w1:p1 --status done

Install the agent-facing skill

npx skills add ogulcancelik/herdr --skill herdr -g

# Runtime safety condition
test "$HERDR_ENV" = "1"

# Inspect the exact protocol for this binary
herdr api schema --json
herdr api snapshot

The official agent skill instructs an agent to use Herdr's CLI only when HERDR_ENV=1. This is a useful environmental guard, not an authorization system.

Do not assume

Native queues, DAG scheduling, shared semantic memory, cross-agent authorization, conflict resolution, retry policy, model routing, or exactly-once execution.

Plugin trust boundary

Marketplace discovery is automatic and unreviewed. Plugins run as the user and receive Herdr context. Review code, pin immutable revisions, and restrict socket access.

04 · Matt Pocock's skills model

Small skills, explicit invocation edges, durable artifacts

Matt Pocock's public repository is a library of engineering practices, not a separate orchestration runtime. Its most valuable factory pattern is the split between user-invoked workflows and model-invoked disciplines.

User-invoked

Workflow / Foreman

Starts only from explicit human intent. It coordinates a flow and may call model-invoked skills. It should not call another user-invoked workflow.

Examples: implement, grill-with-docs, to-tickets, wayfinder

→

Model-invoked

Discipline / Worker skill

Loaded when the task matches. It performs one reusable discipline and emits a verifiable artifact rather than becoming a second foreman.

Examples: research, TDD, diagnosis, domain modeling, code review

01

Discover cheaply

Short metadata lets the harness route without injecting every instruction.

02

Load on demand

Read the selected SKILL.md fully; load linked references only when required.

03

Communicate by artifact

CONTEXT.md, ADRs, specs, tickets, tests, findings, and handoffs survive sessions.

04

Gate completion

A worker returns evidence—tests, diff, source URLs—not the assertion “done.”

Factory mapping

Pocock pattern	Herdr implementation	Control rule
User workflow	Factory foreman plugin/command	Human starts it; workers cannot recurse into peer workflows
Model discipline	Worker skill installed in its runtime	One bounded deliverable and output schema
Blocking edges	Task DAG in controller ledger	Only dispatch the ready frontier
Independent reviews	Two read-only reviewer panes	Standards and spec reports do not share context
Shared language	Versioned CONTEXT.md + ADR IDs	Summaries reference canonical artifacts, not full transcripts

05 · Recommended factory architecture

One authority, many isolated runtimes

Source of truth

Task ledger

Task state, parent/child graph, attempts, leases, ownership, budgets, messages, artifacts, and audit—not Herdr pane titles.

Isolation

One writer per worktree

A mutable attempt owns exactly one worktree and branch. Reviewers use read-only or detached checkouts. Integration is serialized.

Correctness

Typed completion

Herdr “done” is a visibility signal. Controller acceptance requires a schema-valid result, current lease, and evidence digest.

Backpressure

Weighted slots

Budget concurrency by model cost, CPU/RAM, provider headroom, and merge backlog—not by how many panes fit on screen.

Recovery

Leases + fencing

Expired attempts lose authority. Replacement attempts receive a new fencing token; ambiguous side effects enter quarantine.

Communication

Immutable handoffs

Workers exchange goal, constraints, commits, evidence, decisions, requested action, and digest—not inherited conversation history.

06 · “Each agent uses its own Herdr”

Prefer isolated scopes inside one control plane

Recommended default

Shared Herdr

• One Herdr server/session is the host-local execution surface.
• Each agent gets its own workspace, pane, worktree, branch, and attempt-scoped controller capability.
• HERDR_ENV=1 allows a worker to use the Herdr skill and request helpers through policy.
• The controller creates children and returns task IDs; the worker never receives unrestricted socket authority.
• Agents communicate through contracts and artifacts; Herdr events accelerate observation.

Use only for hard isolation

Named sessions

• One named Herdr session per trust boundary creates separate sockets, panes, and persisted state.
• A controller must communicate across those sockets; Herdr's socket is local, not a cross-host message bus.
• Recursive Herdr/tmux inside a Herdr pane reduces state visibility: the docs say agents inside tmux launched in a Herdr pane are not inspected.
• Nested servers increase recovery, socket permission, resource, and orphan-cleanup complexity.
• Use separate OS users/containers when trust isolation—not visual organization—is the reason.

Practical interpretation: “each agent has its own Herdr” should usually mean each agent owns a Herdr-managed execution scope. It should not mean every worker recursively boots an ungoverned scheduler and inherits the parent socket.

07 · Agent communication protocol

Messages are contracts, not chat transcripts

1

Offer

Sender writes an immutable, deduplicated handoff with goal, scope, requested action, and evidence.

2

Validate

Controller checks schema, lease/fencing token, policy, artifact digests, and recipient capabilities.

3

Accept

Controller persists the receipt and schedules exactly one successor for the dedupe key.

4

Acknowledge

Recipient claims the task and records receipt before the sender releases its worktree.

{
  "contract_version": "1.0",
  "message_id": "uuidv7",
  "dedupe_key": "parent:step:purpose",
  "kind": "handoff",
  "from_attempt_id": "uuidv7",
  "to_task_id": "uuidv7",
  "traceparent": "00-<trace>-<span>-01",
  "task": {
    "goal": "...",
    "constraints": ["..."],
    "definition_of_done": ["..."]
  },
  "worktree": {
    "branch": "factory/root/task/attempt",
    "base_commit": "sha",
    "head": "sha",
    "mode": "read_only|writer"
  },
  "evidence": [
    {"uri": "artifact://...", "sha256": "...", "kind": "test"}
  ],
  "decision_log": [{"id": "ADR-004", "reason": "..."}],
  "requested_action": "review|continue|merge|answer",
  "expires_at": "RFC3339"
}

Authoritative task lifecycle

queued→ leased→ provisioning→ running→ waiting / handoff→ succeeded

Failure branches: retryable → bounded backoff → queued; ambiguous ownership/side effects → orphaned → quarantined; policy or exhausted attempts → failed_terminal.

08 · Operations & safety

Five controls before increasing fan-out

01Broker the Herdr socket

Give workers narrow commands such as “start approved child” and “read own logs,” not raw cross-pane input, plugin installation, or server shutdown.

02Isolate every writer

One task, worktree, branch, lease, and owner. Claim paths/contracts where semantic overlap exists. Merge through one serialized queue.

03Separate readers from actors

Web/issues/repo text is untrusted. Read with no secrets or egress; pass sanitized structured facts to capability-limited mutating workers.

04Bound every loop

Cap nesting depth, fan-out, weighted concurrency, turns, retries, wall time, queue size, token reservation, and merge backlog.

05Reconcile before dispatch

On restart, compare leases, process trees, Herdr panes, worktrees, branches, and artifacts. Quarantine ambiguous state before creating replacements.

Failure mode	Detection	Containment	Priority
False agent state	Compare Herdr status, process liveness, typed heartbeat, last progress	Never auto-accept from visual “done”	P0
Prompt injection	Track untrusted source → tool / egress edges	Reader/actor split, no secrets, human egress gate	P0
Plugin supply chain	Origin, resolved commit, hash, manifest inventory	Allowlist, review, immutable pin, staged update	P0
Runaway spawning	Descendant count, token velocity, queue and lease metrics	Single scheduler, max depth/fan-out/budget	P0
Orphans / retry storms	PID tree, lease TTL, attempt and idempotency key	Kill process group, jittered backoff, quarantine ambiguity	P1

09 · Build plan

Prove control before scaling the swarm

Phase 0 · 1–2 days

Adapter spike

Pin Herdr; capture the installed schema; create one worktree and agent; consume events; record all returned IDs; reconcile after restart without creating a second writer.

Phase 1 · 3–5 days

Safe local queue

Implement tasks, attempts, leases, fencing, outbox, budgets, and artifact digests. Start with SQLite for one host or PostgreSQL for concurrent controllers.

Phase 2 · 3–5 days

Handoffs and children

Add the versioned contract, acknowledgement handshake, idempotent spawnChild, role capabilities, depth/fan-out limits, and a human attention queue.

Phase 3 · 2–4 days

Failure drills

Kill workers, restart Herdr and the controller, expire leases, duplicate messages, simulate conflicts, and verify cleanup, quarantine, and merge serialization.

Minimum useful skill pack

factory-foreman · workflow research · discipline tdd · discipline code-review-standards · discipline code-review-spec · discipline

Run three representative projects before expanding: measure rework, worktree conflicts, accepted completions with test evidence, tokens per accepted task, and human intervention time.

10 · Source ledger

Primary sources first

Herdr official

Skills and control-plane references

Community material

Evidence quality and limitations

High: project docs, source, standards, specifications.
Medium: first-person operator reports with direct URLs.
Low / lead only: search snippets and uninspected repositories.
Two auxiliary Helium lanes could not verify their exact windows and intentionally produced no content claims.
No Herdr binary was installed or exercised; official capability claims are source-backed, not locally benchmarked.