Concepts & glossary
These are the terms Shepherd uses across the UI and this documentation. The same
definitions drive the inline term tooltips in the app (registry:
ui/src/lib/glossary.ts).
If you already know your way around, Settings → Device → “Hide info tooltips” (off by default, per-device) removes those dashed-underline glossary terms along with the app’s ⓘ info icons; the terms stay in the text as plain words. Status chip and badge tooltips are unaffected. This page remains the full reference either way.
Shepherd concepts
Section titled “Shepherd concepts”In Shepherd, a tracking issue whose sub-issues are wired by dependency edges — Shepherd spawns a session per ready child, collects their PRs on an integration branch, and lands everything as one final PR. (From Agile, where an epic is a large body of work split into smaller stories.)
Epic clock
Section titled “Epic clock”Measures how long an epic has run. It runs only while the epic runs and stands while it is paused or stopped. See How long will this epic take? for when it starts and stops and how the forecast builds on it.
Agent time
Section titled “Agent time”The summed run time of every agent session that worked on an epic’s steps. Parallel agents each count in full, so it can exceed how long the epic has run. See Agent time and waiting time.
Plan gate
Section titled “Plan gate”A checkpoint before execution: the agent first researches the task, asks you what it needs, and writes an implementation plan that a second agent adversarially reviews, revising until the plan holds up or a round limit is reached. Who releases the approved plan into execution depends on Autopilot — with Autopilot off you give the explicit Go; with it on (or for a drain-spawned session) Shepherd releases it itself. Both coding CLIs follow the same rule here, in either checkout mode: the automatic release needs a clearly identified task conversation, and a session Shepherd cannot attribute one to waits for your Go even with Autopilot on. Either way, a gated agent asks you its questions first: Autopilot stands down for the whole planning phase. If the plan file changes after it was approved, Shepherd marks it as edited and offers a re-review — during execution too; a re-review that requests changes returns the session to the planning phase and stops the agent implementing until the revised plan is approved.
Autopilot
Section titled “Autopilot”Best-effort automation that drives a task through its routine stops to an open pull request. It never merges — landing a PR is the merge train, which requires Autopilot and full-auto merge. Switched off, every step stays with you, and no automatic merge is possible at all. It also owns rebase recovery for the PRs it handed back: as soon as a PR falls behind its base branch or picks up a conflict, it is steered back to the agent to rebase — without waiting for CI or the critic, which would only be spent on the stale version. Open critic findings on the current version are fixed first. The critic waits for the rebased version, and CI runs again on it. Repeated attempts are capped (5 by default) so a genuine conflict pauses for you instead of thrashing; in a full-auto session the merge train owns that same recovery instead. Claude and Codex follow the same rule, in either checkout mode: unattended progress needs a clearly identified task conversation, and Autopilot stands down for a session Shepherd cannot attribute one to. The merge train is the exception — it still carries a Codex session only when Shepherd owns an isolated worktree.
Task amendment
Section titled “Task amendment”Operator-authored text added to a running task after it started, via Amend task… in a session’s card menu. It ranks alongside the original task and is shown to the critic, the plan reviewer and the recap, so it can widen or narrow what the work may contain — the original task itself stays on the record unchanged. It cannot excuse a bug or a security problem, and an agent can never write one: the routes that record an amendment are closed to agent ingress. Amendments are append-only — retracting one stops it reaching every prompt but leaves it in the record — and you can optionally send an amendment straight to the live agent as you record it.
Critic
Section titled “Critic”Shepherd’s isolated, read-only review agent that inspects each new push of a PR
and posts a verdict. It starts once the agent finishes its turn, in parallel with
CI (at the latest when CI goes green); if CI fails on the reviewed push, the
failure and the findings reach the agent as one message. Its built-in lenses are
the floor; a repository can add passes and known exclusions with a committed
REVIEW.md — see Review policy. Every point it raises carries a
severity: important is blocking work, sent back to the agent; nit is
non-blocking and only appears in the posted review’s Nits (non-blocking):
section. A verdict that raises nothing important is a comment, never a request
for changes.
Merge train
Section titled “Merge train”Shepherd’s queue that carries a ready PR through rebase and merge automatically, landing it once CI stays green.
REWORK
Section titled “REWORK”A session sent back to revise its work after the plan gate or PR critic requested changes, instead of approving it.
First-pass rate
Section titled “First-pass rate”The share of merged tasks the critic never asked to rework. A clean re-review of a later push (a CI fix, a rebase) still counts as a pass. Tasks that were never reviewed are left out of the calculation entirely rather than counted as passes.
First-push CI green
Section titled “First-push CI green”The share of merged tasks whose first observed CI result was green — the change passed CI outright, with no red round before it. It measures what Shepherd saw: a push made before the PR opened is not counted. Tasks in repos without CI, and tasks whose CI was never observed finishing, are left out rather than counted as failures.
Plan drift
Section titled “Plan drift”How far a merged change departed from the plan approved before it was written, as reported by the PR critic: none, minor or major. It never affects the review’s verdict — departing from a plan is legitimate. It is measured because a repo that drifts constantly is usually writing vague plans, not writing bad code.
Maintain loop
Section titled “Maintain loop”A daily check of Shepherd’s own health signals against declared thresholds. A mild breach is logged; a sustained one spawns a read-only agent that drafts a backlog issue for you to triage. For one pre-approved class of mechanical fix it skips the issue and opens a pull request instead. It watches Shepherd itself — never a production system.
One health signal plus the thresholds that decide what happens when it is crossed: tier 1 logs a reading, tier 2 spawns a diagnosis. A band whose remediation is mechanical enough to be pre-approved is promoted to tier 3 instead, which opens a pull request. A band below its minimum sample size reports nothing rather than a misleading number.
Inferred
Section titled “Inferred”Derived by the recap model from the code — not verified against the real diff. Treat it as a hint, not ground truth.
Lightweight repo
Section titled “Lightweight repo”A repo Shepherd drives with local git only — no Forge, no GitHub, no PRs, no remote. When a task finishes, the agent’s branch is squash-merged into the base branch locally; the operator pushes to a remote when they choose.
Weighted units
Section titled “Weighted units”A model-weighted measure of token spend that counts what actually draws down your subscription limits — output tokens cost far more than cached reads, so weighted units, not raw token counts, reflect true usage.
Cold cache
Section titled “Cold cache”A session’s prompt cache expires after an hour without activity — five minutes while a Claude subscription is drawing on usage credits. Once it has, the next turn re-sends the whole conversation at the cache-write rate instead of reading it back cheaply, which makes that single turn many times more expensive than the turns around it. A parked session that has gone cold carries a warn chip in The Herd and a matching marker in its status bar, estimating that first turn’s cost in weighted units so you can see it before you resume. Codex sessions and archived ones stay silent, as does anything below a small cost floor.
Reasoning effort
Section titled “Reasoning effort”A cost/quality dial (low, medium, high, xhigh, max, ultra) that sets
how much the model reasons before answering — higher effort spends more tokens
for deeper reasoning, lower is faster and cheaper. max allows deeper
reasoning; ultra also uses automatic subagents. Which levels are on offer
depends on the CLI and the model: Claude stops at max, and among the curated
Codex models only the newest ones reach ultra. Selectable per session in the New Task
picker — and when spawning a variant, comparison, or replacement — with a per-repo,
per-engine or global default in Settings, plus a per-role override for each satellite pass
(critic, planner, recap, doc-agent, namer,
autopilot) in the Settings agent matrix;
leave it at default to use the CLI’s own effort. Shepherd passes it to the
agent CLI as --effort (Claude) or model_reasoning_effort (Codex).
Satellite pass
Section titled “Satellite pass”An automated LLM pass Shepherd spawns alongside the main task agent — critic / PR-review, plan-gate, recap, or doc-agent. Its token spend is real overhead attributed back to the task, on top of the agent’s own authoring.
Host capacity
Section titled “Host capacity”Whether Shepherd’s systemd service — or the slice it runs in — sets a memory or
CPU ceiling (MemoryHigh, MemoryMax, CPUQuota). Without one, a burst of
concurrent sessions can consume all the host’s RAM or CPU and starve the box; the
Host capacity row in Settings → Diagnose warns until a limit is set. See
Operating Shepherd.
herdr runtime hygiene
Section titled “herdr runtime hygiene”Shepherd reconciling herdr’s panes and processes against its own session model to spot leftovers. It counts the panes that still hold a live process — deliberately not systemd’s Tasks figure for the herdr service, which counts threads. Each agent process spawns many, so a Tasks count in the thousands is normal and not by itself a process leak.
Sandbox membrane
Section titled “Sandbox membrane”The confined view of the filesystem Shepherd builds around an agent it starts, using bubblewrap. The agent sees the one worktree it is working in plus the programs it needs to run; everything else is hidden or read-only — so a prompt from an issue, a pull request or a plan cannot reach the rest of the machine. The residuals it deliberately does not close are listed on the Security page.
Shared browser
Section titled “Shared browser”A real Chromium window on the Shepherd host, one per repo, with a saved login profile. You log in there once and that repo’s agents continue in the same logged-in browser. Every agent on the repo can read every login in that profile. Off by default, turned on per repo — see Shared browser.
Handoff login
Section titled “Handoff login”You signing in to a service inside a repo’s Shared Browser — at the host or remotely in a session’s Browser tab — so an agent can continue as that logged-in user. An agent can ask you for one with a Login Request. See Log in for your agents.
Spawn prompt
Section titled “Spawn prompt”The standing instructions Shepherd assembles and hands an agent the moment it starts — safety notices and the directive for this kind of task. It rides every turn of the session, so its size is paid for again and again.
Access token
Section titled “Access token”A named credential a machine client sends in the Authorization header as a
bearer, instead of logging in with the operator password. Shepherd shows the
value once when you mint it and stores only a hash of it, so a single token can
be revoked on its own — unlike the shared SHEPHERD_TOKEN environment variable,
which every client presents identically. How far it reaches is its
token scope.
Token scope
Section titled “Token scope”How far a minted access token reaches, chosen when you create it
and fixed for its lifetime; the app labels it simply scope. Read can list
sessions, holds and git status and follow live updates. Submit adds handing
work in — starting a session, queueing or releasing a held task, attaching a
file, filing an issue. Full is the access you have yourself, including typing
into a running agent’s terminal. Anything a scope doesn’t cover is refused, so a
client can only do what you granted it. SHEPHERD_TOKEN has no scope; it always
has full reach.
Operator Assistant
Section titled “Operator Assistant”A Claude session Shepherd runs for you and grounds in its own telemetry, docs and source. Ask it why the herd stalled, an epic won’t drain or an agent died: it reads, explains and tells you what to do, and acts only when you ask — how far it may go (shell, steering, starting sessions, session control, approvals & merge, automation) is set in Settings → Assistant. See Operator Assistant.
Machine
Section titled “Machine”Another Shepherd instance this one is connected to, set up in Settings →
Machines with its address and an access token with scope
Full and access to all repositories, minted on that machine. Shepherd checks
each machine once a minute and shows its name, version, platform and projects
(the forge slugs of its checkouts), or why it can’t reach it: unreachable, not
authorized, or an incompatible version. Two Shepherds can connect each other; a
Shepherd cannot connect itself. Each machine keeps running its own sessions, and
they appear live in this Shepherd’s herd, grouped under the machine they run on
and labelled with it (for example MacBook · TASK-07). A session’s terminal opens
here as well and works as it does locally — this Shepherd passes it through to the
machine with the machine’s token, and only callers with full access reach it.
Steering, stopping and archiving a session, and reading its activity, diff and
files (including uploads to its scratchpad), work the same way: this Shepherd
checks the caller’s access as for a local session, sends the request to the
machine, and the machine runs it. The preview does too: the machine starts and
stops the dev server, and the preview opens from the machine’s own address in
your tailnet (its tailscale serve slot) — never from a port of this Shepherd. A
machine that can’t publish previews into the tailnet (no Tailscale name, or serve
permission refused) says so instead of offering a link. Its other actions —
merging, relaunching, resuming, reviews — are not offered here yet and are
refused, never run on this machine instead. Clearing merged sessions covers the connected machines
too and names any machine that did not answer. If a machine becomes unreachable,
its sessions stay with their last known state and are marked disconnected, nothing
is sent to it, and an open terminal says so and reopens once the machine is back;
a session disappears only once its machine no longer reports it. A new task can be
started on a machine that has its project checked out — Run on in the New Task
dialog, where Automatic lets Shepherd pick the machine by the task’s
requirements — and then the whole session runs there, from the
branch as pushed to origin.
Capability
Section titled “Capability”Something a Shepherd has verified it can run, checked as the user it runs as
rather than inferred from its platform: its platform (platform:linux,
platform:macos, platform:windows), Xcode and its SDKs and simulator, the
Android SDK, the agent CLIs it has installed and logged in (agent:claude,
agent:codex) and the sandbox profiles it can enforce (sandbox:trusted,
sandbox:standard, sandbox:autonomous). Each Shepherd checks every 5 minutes
and on demand, and serves the result with its age on GET /api/instance;
Settings → Machines shows it per machine and marks a check older
than 15 minutes as stale. A task created with requirements is checked again by
the receiving Shepherd when it accepts the task, and refused with each missing
capability named — stale information never starts a task. Windows machines are
listed but not released for tasks until platform compatibility is proven.
Requirement
Section titled “Requirement”A capability a task needs from the machine it runs on — for
example xcode, sdk:ios or android-sdk. In New Task they are chips under the
prompt; through the API, requirements. With Run on: Automatic, Shepherd starts
the task on a connected machine — or this one — that has every
requirement verified, preferring Linux over macOS, and shows which and why before
it starts. If none has them, nothing starts and the missing capability is named; if
the machine a task is meant for is offline, the task becomes a
waiting task — nothing starts elsewhere on its own. The machine
checks the requirements again when it accepts the task.
Waiting task
Section titled “Waiting task”A task Shepherd keeps for the machine it is meant for while that machine is asleep, out of reach or missing a requirement. It shows at the top of the herd, labelled with its machine — Waiting while the machine is away, Blocked while it is back but lacks a requirement or the project’s checkout — and nothing is sent until the machine is back and a fresh check of its capabilities and project passes; then it starts there by itself, attachments included. It never moves to another machine on its own: cancel it, or run it on another machine that fits now (Run here, Run on …). It survives a restart of this Shepherd. A task a busy machine has already accepted and holds shows as Busy instead.
Industry terms
Section titled “Industry terms”Pull request — a proposed set of code changes submitted for review and merging into a branch. (Wikipedia)
Continuous integration — automatically building and testing every change so problems surface early. (Wikipedia)
Telemetry
Section titled “Telemetry”Automatic collection of anonymous usage and diagnostic data from software, sent
back to its developers to guide improvements. In Shepherd it is off until you opt
in, respects DO_NOT_TRACK, and never includes code or personal data — see
Configuration.
(Wikipedia)
Lead time
Section titled “Lead time”How long a task took end to end: from the moment the session was created to the moment its pull request merged. Borrowed from lean manufacturing, where it measures the delay between a request and its delivery. (Wikipedia)
A filesystem’s record for one file or directory. A filesystem has a limited number of them, set when it is created — so it can run out of inodes while still having free space, and every new file then fails as though the disk were full. (Wikipedia)