Getting Started

Initialize a Repository

Navigate to a git repository with a GitHub remote and run:

herd init

This will:

1. Create .herdos.yml — the configuration file with sensible defaults, auto-detecting your GitHub owner and repo from the git remote
2. Create .herd/ directory — with empty role instruction files (planner.md, worker.md, integrator.md) for customizing agent behavior per role
3. Create GitHub labels — the herd/* label taxonomy used to track issue status and type
4. Install workflow files — GitHub Actions workflows for workers, integrator, and monitor in .github/workflows/
5. Create runner files — Dockerfile.herd_runner (which FROMs the published ghcr.io/herd-os/herd-runner-base base image), docker-compose.herd.yml, and .env.herd.example for self-hosted runner setup (you can also run the container directly with docker run — see Deployment options)
6. Commit and open a PR — creates a herd/init-<version> branch, commits all generated files, pushes, and opens a PR. Review and merge the PR to apply the changes.

The installed version is recorded in .herd/state/version (gitignored) and used on subsequent runs to decide between install, update, and sync.

Enable Workflows

Workflows are installed but inactive until you enable them. After setting up runners (see Runner Setup), set the HERD_ENABLED repository variable:

gh variable set HERD_ENABLED --body true --repo <owner>/<repo>

This prevents a workflow storm if runners are online before the system is fully configured.

Skipping Steps

herd init --skip-labels       # Don't create GitHub labels
herd init --skip-workflows    # Don't install workflow files

Configuration

View all configuration:

herd config list

Get a specific value:

herd config get workers.max_concurrent

Set a value:

herd config set workers.max_concurrent 5
herd config set platform.owner my-org
herd config set pull_requests.auto_merge true

Open the config file in your editor:

herd config edit

See configuration.md for all available options.

Role Instruction Files

Customize how each HerdOS role behaves in your project by editing files in .herd/:

These files are created empty by herd init. Add your project-specific instructions and commit them — they’re shared across your team.

Planning Work

Decompose a feature into tasks with an interactive agent session:

herd plan "Add user authentication"

Pre-Flight Git Checks

Before launching the planning session, herd plan runs pre-flight git checks to ensure your local repository is in a clean, up-to-date state:

1. Fetches from origin — always runs; a fetch failure is non-fatal.
2. Branch check — if you’re on a branch other than the default branch, prompts: “You’re on branch ‘foo’. Switch to ‘<default>’ and pull latest? [Y/n]”
3. Behind remote check — if your local branch is behind the remote, prompts: “Local is N commits behind origin/<branch>. Pull latest? [Y/n]”
4. Dirty working tree warning — if you have uncommitted changes, shows: “Working tree has uncommitted changes. The planner will see your local state.”

If you accept a prompt to switch branches or pull but have a dirty working tree, the command exits with an error asking you to stash or commit first.

To bypass all pre-flight checks:

herd plan --skip-preflight "Add user authentication"

herd plan also does a best-effort lookup of the latest published herd release and prints a one-line warning if you are behind. The check is bounded by a 3-second timeout and is silently skipped on network errors, dev builds, or pre-release tags — see Installation → Upgrade notifications for the full behavior.

The planner automatically reads the repository structure, README, tech stack manifest, recent git history, and active batches to give the agent context about your project. The agent asks clarifying questions, then produces a decomposition with tasks, dependencies, and tier assignments. Before writing the plan file, the agent presents a high-level overview table (task number, title, tier, complexity, dependencies, manual flag). You can say “details” to see the full implementation plan, or “approve” to proceed immediately. You can approve at either step, request revisions, or reject — the agent only writes the plan file after explicit approval. Once approved and written, herd automatically creates issues and dispatches Tier 0 workers — no extra commands needed.

To plan without auto-dispatching Tier 0:

herd plan --no-dispatch "Add user authentication"

Preview what would be created:

herd plan --dry-run "Add user authentication"

If the batch name collides with an existing milestone, herd will retry with a numeric suffix (e.g. My batch (2), My batch (3), …) until it finds an unused name, up to 10 attempts. The original milestone is never reused — existing milestones may contain stale issues from a prior failed run, and mixing them with the new plan would be confusing. When a suffix is applied, herd prints an informational note to stdout (Note: batch name conflicted with existing milestone — using "My batch (2)" instead.); the resolved name is also used for the batch branch slug.

If issue creation fails after planning, the plan file is preserved and the exact --from-file command is printed. Use it to retry without re-running the agent session:

herd plan --from-file .herd/state/1234567890.json

Plan File Validation

After writing the plan file, the agent self-verifies it (re-reads the file, confirms the JSON parses, and checks the schema before declaring success). When the file is loaded — either at the end of an interactive session or via --from-file — herd applies the same structural checks:

• batch_name is non-empty.
• At least one task is present.
• Each task has a non-empty title and at least one acceptance_criteria entry.
• Every depends_on index is in range and does not reference its own task.
• complexity is one of low, medium, high, or empty.
• type is one of feature, bugfix, or empty.

If a check fails, herd fails fast and the error names the offending task index, title, and field — for example, task 3 ("Add login route"): depends_on[1]=7 is out of range [0,5). Edit the plan JSON to fix the issue and re-run herd plan --from-file <path> to retry without restarting the agent session.

Dispatching Workers

After planning, Tier 0 tasks are dispatched automatically. To manually dispatch:

# Dispatch a single issue
herd dispatch 42

# Dispatch all ready issues in a batch
herd dispatch --batch 5

# Dispatch across all batches
herd dispatch --all

# Override concurrency limit
herd dispatch --batch 5 --ignore-limit

Monitoring Progress

# Overview of all batches and active workers
herd status

# Detailed view of a specific batch
herd status --batch 5

# Auto-refreshing dashboard
herd status --watch

# Machine-readable output
herd status --json

# Runner status
herd status --runners

Live dashboard

herd dashboard is a read-only terminal UI that shows active workers, open batches, and recent failures, refreshing on a timer.

herd dashboard

Override the refresh interval with --refresh-seconds:

herd dashboard --refresh-seconds 30

The interval is clamped to 5–300 seconds (default 15).

Keybinds:

Each row in the active workers panel shows the issue number, issue title, and elapsed wall-clock time since the workflow started:

Active workers (2)
  #42 Add tenant scope to Rake tasks (4m 12s)
  #43 Wire dashboard refresh interval flag (49s)

Elapsed is rendered as Ns under a minute, Nm Ns under an hour, and Nh Nm beyond. Long titles are truncated with an ellipsis so the elapsed segment stays visible. If the issue title cannot be resolved, the row falls back to #N (elapsed); if the issue number is also unavailable, only (elapsed) is shown.

Each worker row is emitted as an OSC 8 hyperlink pointing at the workflow run; supporting terminals render them as clickable links and others fall back to plain text.

The dashboard is read-only and single-repo — cross-repo views and in-TUI actions are out of scope for v1.

See also: herd status for one-shot or JSON output.

Managing Batches

# List active batches
herd batch list

# Show detailed issue status for a batch
herd batch show 5

# Cancel a batch (stops workers, labels issues as cancelled, closes issues and PR, closes milestone)
herd batch cancel 5

# Alternatively, close the batch PR on GitHub without merging.
# This labels non-done issues as cancelled (not failed), closes the
# milestone, and deletes the branch.

What Happens After Dispatch

Once workers are dispatched, the system runs autonomously via GitHub Actions:

1. Workers execute — Each worker reads its assigned issue, runs your agent in headless mode on a self-hosted runner, and pushes changes to a worker branch (herd/worker/<number>-<slug>). If no changes are needed, the worker marks the issue as done without pushing.

2. Integrator consolidates — When a worker completes, the Integrator scans the batch’s milestone for every herd/status:done issue whose worker branch is still on the remote and merges each into the batch branch (herd/batch/<number>-<slug>), deleting each worker branch after a successful merge. The scan is idempotent and self-healing: if a prior integrator run was cancelled mid-loop, the next successful run picks up any stranded worker branches automatically. If a merge conflict is detected on a candidate branch, the behavior depends on integrator.on_conflict: with dispatch-resolver (default), a conflict-resolution worker is automatically dispatched; with notify, a comment is posted for manual resolution instead. Conflicts on one branch do not abort the loop — other candidates still consolidate.

3. Integrator advances — After consolidation, the Integrator checks if the current tier is complete. If so, it unblocks and dispatches the next tier. When all tiers are done, it rebases the batch branch onto main and opens a single batch PR.

   Herd stores generated reviewer-summary context as milestone metadata, so reruns can reuse it while older batches remain compatible.

4. Agent review — If integrator.review is enabled, an agent reviews the batch PR diff against all acceptance criteria. Large PRs are split into bounded chunks; each chunk is reviewed in strict output mode (no tool calls, JSON-only output — see Configuration: Agent Review), then HerdOS deduplicates findings and posts one aggregated result. Duplicate findings are collapsed before the PR comment is posted and before review fix issues are created. If coverage is incomplete for material source files, HerdOS requests changes instead of approving. HerdOS uses live GitHub PR metadata as authoritative for current mergeability, conflict state, head SHA, labels, and CI state. If the batch PR changes while a review is running, HerdOS discards that review result so it does not act on an outdated diff; the next trigger or a manual /herd review reviews the updated diff. After Herd approves a PR head SHA, repeated automatic review triggers for that same current head are logged no-ops instead of spending another review session; a new commit or manual /herd review asks for a fresh pass. If issues are found, the Integrator creates fix issues and dispatches fix workers. When repeated completed fix cycles are not reducing findings and those findings share package/root-cause clusters, HerdOS creates one strategy-level fix issue instead of another large endpoint-level fix issue. This cycle repeats up to review_max_fix_cycles times.

5. CI failure detection — When integrator.ci_workflows lists your CI workflow names, herd init installs workflow_run self-heal triggers for those exact GitHub Actions workflows on batch branches. If configured CI fails, the Integrator re-runs checks once (transient failure filter), then dispatches fix workers up to ci_max_fix_cycles. CheckCI pauses dispatching a new CI fix worker if any fix-type worker — review fix, CI fix, or conflict resolution — is still in progress in the same batch milestone. The Monitor and /herd fix-ci remain fallback paths.

6. Monitor patrols — A cron-triggered Action detects stale workers (in-progress with no active run), failed issues (auto-redispatches with exponential backoff), CI failures on batch PRs, and stuck PRs (open longer than max_pr_age_hours). It escalates to notify_users when retries are exhausted.

7. You review and merge — The batch PR arrives with a reviewer-facing summary, major changes, validation notes, and then the task/tier table. If pull_requests.auto_merge is true and the agent review passed, it merges automatically. If you close the PR without merging, cleanup still runs: non-done issues are labelled herd/status:cancelled, the milestone is closed, and the branch is deleted.

Role Instruction Files

Customize agent behavior for each role by editing files in .herd/:

• .herd/worker.md — Appended to the worker’s system prompt (e.g., “use table-driven tests”, “follow project coding standards”)
• .herd/integrator.md — Appended to the integrator’s review prompt (e.g., “be strict about error handling”)

These are loaded automatically when the respective role runs.

Failure Handling

• Worker failure — The issue is labeled herd/status:failed and the Monitor is triggered immediately for fast escalation
• Tier stuck — If any issue in a tier fails, the tier is stuck and the next tier won’t be dispatched until the failure is resolved (manually or by the Monitor’s auto-redispatch)
• Worker consolidation merge conflict — When a worker branch conflicts while the Integrator is merging it into the batch branch, integrator.on_conflict controls the response. With dispatch-resolver, the Integrator creates a conflict-resolution issue and dispatches a worker automatically; with notify, it posts a comment for manual resolution. The number of resolver attempts is limited by max_conflict_resolution_attempts; when that budget is exhausted, the batch enters cascade-failed state and the herd/cascade-failed label is applied to the batch PR — see design/execution.md → When cascades fail. If fresh GitHub PR metadata later reports the PR clean and mergeable, HerdOS automatically removes a stale herd/cascade-failed label; humans may still remove it manually after resolving the underlying conflict.
• Batch PR merge conflict — If an already-open batch PR becomes conflicted with its base branch, post /herd resolve-conflicts on the batch PR. HerdOS checks live GitHub mergeability, waits briefly when mergeability is unknown, and creates a focused conflict-resolution issue only when the PR currently conflicts with base. Use generic /herd fix for normal code fixes; it still includes PR conversation history for worker context.
• Review safety valve — If a single agent review finds more than 10 issues, fix workers are not created (to prevent runaway invocations). For chunked reviews, duplicate findings are deduplicated before the final PR comment and before fix workers are dispatched. The PR is flagged for manual intervention when the safety valve still applies.
• Review non-convergence — If several completed review-fix cycles do not reduce repeated package/root-cause clusters, HerdOS can optionally synthesize the dominant architectural/root-cause pattern, then creates and dispatches one strategy-level fix issue instead of asking for another /herd fix.
• Stale review result — If the batch PR changes during agent review, HerdOS discards that result instead of creating fix workers or approving based on an outdated diff. The updated diff is reviewed on a later trigger, or you can run /herd review manually.
• Duplicate approved-head review — If an automatic trigger fires after Herd has already approved the current PR head SHA, HerdOS logs the skip and does not start another review agent. Use /herd review when you want a fresh pass without pushing a new commit.
• Unparseable review output — If the review agent returns output that can’t be parsed, the Integrator retries once after a 5-second delay within the same invocation. If both attempts fail, it posts an agent-review failure comment on the batch PR. Run /herd review on the PR to retry — the Integrator does not silently drop the review.

Manual Tasks

Some tasks in a batch may be labeled herd/type:manual — these require human action (e.g., infrastructure setup, external service configuration). They appear in herd status with a 👤 icon. To complete a manual task, close the issue on GitHub. The Integrator detects the close event and advances the tier if all tasks are now complete.

Re-triggering Review

When a human submits a review on the batch PR, the Integrator’s re-review job runs automatically, invoking the agent for a fresh review against the current diff. This allows you to push manual fixes and have the agent re-evaluate.

Interactive PR Review

herd review <pr-number>

Opens an interactive read-only review session pre-loaded with diff coverage, comments, CI status, and the first review chunk. For large PRs, the initial prompt says only chunk 1/N is included so you can see the limitation. The agent reads code and discusses findings with you, and drafts /herd fix comments for any actionable changes — it never edits files locally. When you approve a draft, the agent posts it via gh pr comment, and herd’s batch workers handle the actual edit like any other fix task.

Comment Commands

You can interact with HerdOS by posting /herd commands as comments on issues and PRs. Commands are available to repository owners, members, and collaborators.

When you post a command, HerdOS reacts with 👀 to acknowledge it, executes the command, and posts the result as a reply.

Available Commands

Image support: When you attach screenshots to /herd fix comments, workers automatically download GitHub-hosted attachment images and can view them directly. This is useful for UI bug fixes — paste a screenshot of the problem or the desired result, and the worker will see it. Only GitHub attachment URLs are downloaded; external image URLs are left as-is for the agent to handle.

Examples

/herd fix-ci the Node version file is missing from the Docker image
/herd retry 42
/herd review focus on error handling in the auth module
/herd fix add missing error check in auth.go line 42
/herd integrate

/herd retry always re-runs the worker, and it is never a no-op just because a previous attempt’s progress checklist looks complete. If the previous attempt finished its work but failed pre-push validation, the retry re-invokes the agent with the saved validation errors (the agent is told the progress file is stale) rather than skipping straight to reporting — the agent is skipped only when both the progress file is complete and the worker’s validation marker is present. See design/execution.md → Retry Resume for details.

When the integrator fails during any step (consolidation, CI check, advancement, or review), it posts a comment on the relevant issue or batch PR with the error details and a reminder to retry with /herd integrate.

Quotes around the prompt text are optional. You can paste error logs, JSON snippets, or any text directly after the command — everything after the command name (including subsequent lines) is treated as the prompt. The quoted format (/herd fix "description") is also still supported.

The Monitor also uses comment commands internally — it posts /herd retry <N> and /herd fix-ci comments instead of dispatching directly, keeping all command execution flowing through a single handler.

User Feedback in Reviews

When /herd review runs on a PR, it collects non-HerdOS user comments from the PR and passes them to the review agent as context. This means:

• If a review flags a false positive, comment on the PR explaining why (e.g., “The nil check finding is a false positive — the caller guarantees non-nil”).
• On the next review cycle, the agent will see your comment and avoid re-flagging the same issue.
• User feedback is treated as authoritative by the review agent — if a user says a finding is a false positive or provides context explaining why the code is correct, the agent will accept that.

HerdOS bot comments (review findings, integrator messages, worker progress) are automatically excluded from user feedback collection. This works for both batch PRs and standalone PRs reviewed with /herd review.