claudeers.
// Automation & Workflows

stampede

Text tasks to your Grok Bot. It reaches your Mac over Tailscale, where Claude Code does the job, adding other agents (Codex, Cursor and more) as needed. Noth…

// Automation & Workflows[ cli ][ api ][ desktop ][ web ][ claude ]#claude#agent-orchestration#ai-agents#claude-code#cli#codex#cursor#developer-tools#automation◷ MIT$open-sourceupdated 8 days ago

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up stampede (claude-skill project) into my current project.
Found on https://claudeers.com/stampede
Repo: https://github.com/vib-z/stampede
Homepage/docs: https://vib-z.github.io/stampede/
Detected install method: claude-skill → # copy this skill into .claude/skills/stampede/
Category: automation. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or install directly (claude-skill)
# copy the skill dir into your project:
# .claude/skills/stampede/   (or ~/.claude/skills/stampede/ for all projects)
// or clone
git clone https://github.com/vib-z/stampede

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguagePython

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

stampede

You text a task to your Grok Bot. It reaches your Mac over Tailscale, where a Claude Code lead does the job in Herdr and adds Codex or Cursor panes only when parallel work helps. Nothing is merged, pushed, sent or spent until you say yes.

Grok Bot is the setup we recommend, but you don't need it: stampede also runs when you start it straight from Claude, Codex or any agent (Without a bot). Either way you can watch every agent in Herdr, and every question comes back to you.

Let a Grok Bot set it up. Stompy is a Grok Bot that sets up stampede between your Grok Bot and your Mac, end to end, and keeps it healthy.

Demo: a task texted to Grok Bot reaches a Mac over Tailscale, a Claude Code lead works on it in Herdr with a Codex and a Cursor worker beside it, the bot asks before merging, then reports back.

An animated mock-up of one job, 27 Oct 2026.

Install · Updating · How it works · Walkthrough · Front doors · Safety · Reference · Docs · Changelog

New releases: on GitHub, Watch, then Custom, then Releases.
The site: vib-z.github.io/stampede


How it flows

Started from Grok Bot, the setup we recommend:

flowchart LR
    you(["You, in chat"]) --> bot["Grok Bot"]
    bot -- "SSH over Tailscale" --> mac["Your Mac, always on,<br/>running Herdr"]
    mac --> lead["Claude Code lead"]
    lead -- "only when it's worth it" --> workers["Codex and Claude Code<br/>workers, in Herdr panes"]
    workers -- "reports, by hooks" --> lead
    lead -- "gate question" --> bot
    bot -- "asks you in chat,<br/>records your yes" --> merge(["Draft PR merged"])
    lead -. "or Moshi, if you<br/>started it locally" .-> phone(["Your phone"])
    phone -. "your tap" .-> merge
    mac -. "or answer in Herdr" .-> merge
    lead -. "result, by webhook" .-> bot

Without a bot

stampede works fully on its own with Herdr, Claude Code and this repo: start a job straight from Claude, Codex, Cursor or any agent, or from a Claude pane in Herdr (Front doors). Gate questions then reach your phone through Moshi, if you use it, or you answer in Herdr.

Either way:

  • One ask, one lead. A Claude Code lead plans the job and does it.
  • Workers only when it's worth it. The lead opens a Codex or Claude Code worker in its own Herdr pane for parallel work, another model or a reviewer, and works alone otherwise.
  • Hooks, not polling. Workers report to the lead through hooks, and you can watch every pane in Herdr.
  • Your yes on every merge, push, send, spend or close. The gate question goes back to whoever started the job, and a yes typed in a Claude lead's Herdr pane works too (for a Codex lead and on Herdr Core only the recorded yes counts). The lead keeps working while it waits.

Quick start

On a Mac or a Linux machine with Herdr 0.9.4 or later, Claude Code signed in, Python 3.9 or later, git, jq and curl:

git clone https://github.com/vib-z/stampede.git ~/stampede
~/stampede/install.sh
export PATH="$HOME/.local/bin:$PATH"   # add this line to your shell profile too
herdr-doctor                           # exit 0, with Herdr running

Your first ask. Once per Mac, run the unattended setup, so the lead can start workers with no visit to their panes. Run herdr-trust ~/code/my-app once for your repo, open it in Herdr, start Claude in a pane, and type:

With stampede: add a /health endpoint with a test, have a reviewer on another model check it, then open a draft PR.

Then from your phone (recommended). Set up Grok Bot's SSH, Tailscale and webhook once (remote/grokbot/), and send the same ask in chat.

On Herdr Core instead of the Herdr TUI. With Herdr Core (hc 0.1.13 or later) installed and running, run herdr-doctor --core, then ask "With stampede, on Herdr Core: ...". The front door runs stampede new --core, and each agent runs in a Core terminal of its own (Herdr Core).

Limits.

  • macOS and Linux. On macOS you load the event relay's two launchd jobs yourself; on Linux install.sh starts the same timers (systemd user units, or one flock-guarded loop when systemctl --user does not answer). On Linux a whole job ran live on the Herdr TUI and on Herdr Core (Ubuntu 24.04 arm64, stand-in agents; docs/LINUX.md says exactly what was real); a signed-in agent, the systemd timers, Moshi paired and a bot over SSH have not been run there yet.
  • The lead is Claude by default (any Claude model, set by FLEET_LEAD_MODEL), or Codex with stampede new --lead codex on the Herdr TUI. Workers can be Claude, Codex or Cursor (on Herdr Core, Claude or Codex in Core terminals, and Cursor, Hermes or Kimi handed to Herdr TUI panes).
  • Version 0.1.x, and early: commands and files may still change.
  • For big jobs. A small job runs as one agent session in a single tagged Herdr pane (FAQ).

The full install, with every prerequisite: Install. A whole job, command by command: the walkthrough.

What is stampede?

stampede is multi-agent orchestration for Claude Code and Codex in Herdr: four skills and one command, installed by script or as a Herdr plugin. You ask once, in plain words: in a Claude pane in Herdr, from Claude or Codex desktop or Cursor, or, as we recommend, from your phone through Grok Bot. stampede starts one lead agent for the job. The lead writes a short plan and starts working at once. It brings in Codex workers, or Claude Code or Cursor ones, each in its own Herdr pane, only when that agent earns its place: work that runs in parallel, a different model, one reviewer, or the same task many times over. Workers report through hooks, so nobody polls. Gate questions come back to wherever you asked, and nothing that matters happens without your own yes.

Why. Running many agents by hand means stops between steps, too many small agents, rounds that wait on each other, and a lead that spends its day writing briefs. Real jobs showed all four (docs/RUNS.md). stampede is the lean answer: plan and go, work alone by default, wake on hooks, and ask you only what is yours to decide.

Who it is for. Anyone who runs Claude Code, Codex or Cursor and wants a whole job done from one ask, watched in Herdr and answered from a phone.

What it is. Four skills and one command:

partwhat it does
stampede (skill)the front door: say "use stampede" in any project chat and it writes the ask, opens a Herdr workspace for the project and starts the lead
herdr-fleetthe playbook the lead follows: plan, panes, hooks, review, gates, report, reopen
grokbot-herdrthe front door for a bot that reaches your machine over SSH
share-planshows you the plan before any agent starts, only when you ask
stampede (command)the command: new, start, tell, ask, cancel, approve

Works with

Agents. The lead runs on Claude Code, or on Codex when you pick it (stampede new --lead codex, Herdr TUI only). Workers run on Claude Code, Codex or Cursor, each started by stampede start --kind claude|codex|cursor with its own hooks and auto mode. A Herdr Core job also takes Hermes and Kimi workers, handed to Herdr TUI panes.

Claude Code logo
Claude Code
the lead, and workers
Codex logo
Codex
the lead if you pick it, workers and reviewers
Cursor logo
Cursor
workers

Tools.

Herdr logo
Herdr
the panes you watch
Moshi logo
Moshi
questions on your phone
Grok Bot logo
Grok Bot
the preferred bot
Tailscale logo
Tailscale
a bot's private link

Herdr Core (hc 0.1.13 or later), Herdr's terminal runtime, can run a whole job in place of the Herdr TUI: Herdr Core.

Herdr itself detects many more agent CLIs (its herdr agent start --help lists 24, from Gemini and Kimi to OpenCode and Copilot). Beyond Claude, Codex, Cursor, and Hermes and Kimi in a Core job, that is Herdr's support, not stampede's yet: stampede start refuses any other kind, and starting workers on them is planned. The marks belong to their owners and imply no endorsement (sources).

Works well with

pstack, optional. For coding jobs, the lead picks up pstack if you have it: data shape first, a contract commit, proof on the real surface. The lead is a normal Claude Code session, so an installed pstack loads on its own, and stampede's rules keep pstack's fan-out as Herdr panes you can watch. Not required: without it nothing changes. The rules: references/pstack.md.

See it

The build tab of a fleet in Herdr: four panes side by side. build-steps-plan and build-steps-run are Claude Code agents that have just finished; build-scripts and build-app are Codex agents still working.

Real, drawn: the build tab of the fleet that built stampede's first version, drawn from each pane's own screen text (herdr agent read), personal paths replaced with ~, 18 Oct 2026. A lean job opens fewer panes; each looks the same.

How it works

The flow is the diagram at the top, step by step, for any front door:

  1. You ask once, in plain words, in a front door. It writes the ask to a file, runs stampede new --file <ask.md>, tells you the lead's name, and steps back.
  2. One lead plans and goes. lead-<slug> starts on Claude (Opus 5.5 at xhigh effort by default), or on Codex (GPT-6 Astra at ultra) with --lead codex, in auto mode, in a lead tab. It writes plan.md (the tasks, who does each, questions with a safe default, and the gates) and starts work.
  3. A pane only when it's worth it: parallel pieces of about 30 minutes or more (at most 4), another model or tool, one reviewer on another model, or the same task many times (6 at once). Each worker gets its own Herdr pane.
  4. Hooks, not polling. A worker's report, turn end, question or exit lands as a line in <job>/inbox.log (REPORT, TURN, QUESTION, GONE, and UNDELIVERED for a question or gate its bot has not heard), and Claude's file hook wakes the lead. A Codex lead has no file hook: stampede types each new line into its pane, marked [fleet-job inbox for <lead>, not typed by the owner], once it is idle and unfocused.
  5. Review only what ships, on another model, at most two rounds.
  6. Questions and gates go back to whoever started the job: a bot gets a question or gate event, asks you in chat and passes your answer back (a gate's yes recorded with approve-gate); a job you started locally asks on your phone through Moshi. On the TUI, a yes typed in a Claude lead's pane works; for a Codex lead, and on Core, only a recorded yes counts. The lead keeps working while it waits, and an agent's own say-so never counts.
  7. The lead reports back once. When the job is done or stopped for good it runs stampede finish <job> "<summary>". That is the one done event a bot outside Herdr gets for the job. While the job is open, plain turn ends in its workspace stay on the machine. Blocked, permission prompts, StopFailure, a stale or dead pane, questions and gates still go out. Then the lead asks whether to close.
  8. Workers exit when their work is merged or accepted. Nothing closes without your yes, and reopen.sh brings a closed job back.

Stateful lead, stateless workers. The lead holds your ask, the plan, the decisions and the judgement. A worker gets one brief and nothing else, so that brief carries the state: Goal, Why, Inputs, Constraints, Done when, Report back and If blocked, on the hand-off template. A thin brief is the usual cause of weak worker output. stampede start refuses a worker brief with a missing or empty section before starting anything. Pick a strong planner for the lead and a fast, capable executor for workers; both are settings, not code.

What lives where. Your Mac, always on, runs Herdr, the lead and the workers. A bot such as Grok Bot runs on its own computer and reaches the Mac over SSH and Tailscale. Or the whole thing runs on one remote computer. Either way, the lead and its workers share one machine; workers on a second machine are planned.

On Herdr Core the same flow runs in Core terminals instead of panes: the brief pointer is each agent's first prompt, tell prompts Codex with hc send by its status, Cursor, Hermes and Kimi workers run in Herdr TUI panes the job hands them to, and the job's follower, herdr-event-core, adds BLOCKED, ERROR, GONE, WAITED, LOST, STALE and RELAY DOWN lines to inbox.log and posts source hc events for a bot (Herdr Core).

The job folder

stampede new makes ~/code/herdr-jobs/jobs/<date>-<bot or local>-<slug>/ (FLEET_JOBS_ROOT moves the root), never inside your repo, so nothing lands in git; the repo stays the agents' working folder, and every agent gets --add-dir <job> to write there:

ask.md        your ask, word for word
workdir       the repo the agents work in
lead          the lead's name
plan.md       the lead's plan
briefs/       the generated lead brief, then worker briefs on the hand-off template
hooks/        each agent's hook settings and wake state; deliver.log for a Codex lead
inbox.log     REPORT, TURN, QUESTION, GONE and UNDELIVERED lines that wake the lead
inbox/        messages to each agent, one file per agent
questions/    a worker's questions, as files for the lead
asks/         questions out to your phone, while they wait
owner         the bot that started the job, when one did: its gates go back to it
workspace     the Herdr workspace id, or a Herdr Core job's key hc-<12 hex>; while the job is open,
              ~/.config/herdr-events/jobs/<id> names this job
backend       core, for a Herdr Core job (no file: the Herdr TUI)
endpoint      the Herdr Core a Core job was made on (HC_SESSION, HC_SOCKET);
              every later command uses it
core.json     a Core job's terminals: state, address, name, role, cwd per agent,
              and whether each Claude session ran
locks/        a Core job's launch locks, one per agent
relay-state.json   what a Core job's follower saw and sent
start-failed  why a Core job's start never ran
reopen-pending  a restarted Core lead that has not acknowledged both inbox files yet
finished      the one-line summary written by stampede finish
gates/        each gate asked (action, PR, commit) and your recorded yes
agents.tsv    who was started, and how: the reopen record
approved      the plan's fingerprint, for a --review job
front-door    present when a chat outside Herdr relays for you (new --front-door)
outbox/       what the lead posts for that chat to relay: NNN.md and NNN/ files
outbox.log    one line per post, read by stampede wait
REOPEN.md, reopen.sh   written by herdr-reopen-snapshot before a close (a Core job: at every start)

Install

Prerequisites (tested on macOS 27.2, 21 Oct 2026, and with Herdr 0.9.5, Herdr Core 0.1.19 and moshi-hook 0.4.50 on 8 Nov 2026 on macOS 27.2 and Ubuntu 24.04 arm64; Linux in detail: docs/LINUX.md):

toolversion testedneeded for
Herdr0.9.5 (0.9.4 or later: the plugin and herdr-doctor check it)the panes
Herdr Core hc0.1.19 (0.1.13 or later)a job on Herdr Core, optional
Claude Code2.1.306 (2.1.295 or later on Herdr Core, for its status)the lead, and workers
Codex CLI0.163.0 (0.165.0 checked for --no-daemon on Herdr Core)workers, optional
Cursor Agent2026.10.19workers, optional
Hermes Agent0.22.5 (flags checked with --help)handed workers of a Herdr Core job, optional
Kimi Code2.2.0 (flags checked with --help)handed workers of a Herdr Core job, optional
Python 3, git, jq, curl; on Linux also flock (util-linux) and ps (procps)Python 3.9 (the tests need 3.11), git 2.56, jq 1.7the scripts
Moshi moshi-hook0.4.50 (ask, notify and job flags checked with --help; on Linux, unpaired)questions on your phone, optional
Tailscale1.104.1a bot on another computer, optional

Step by step, on a Mac or a Linux machine with Herdr, Claude Code (signed in), Python 3 and git:

git clone https://github.com/vib-z/stampede.git ~/stampede
cd ~/stampede
./install.sh --dry-run               # prints each link it would make, changes nothing
./install.sh                         # links the skills and the commands
export PATH="$HOME/.local/bin:$PATH" # add this line to your shell profile too
stampede --version                   # 0.1.8
herdr-trust ~/code/my-app            # once per repo, before agents start there

Or as a Herdr plugin, where Herdr keeps the checkout and runs the same install.sh, plus the event hook:

herdr plugin install vib-z/stampede  # shows a preview and asks y/N; add --yes over SSH or from a bot
export PATH="$HOME/.local/bin:$PATH" # add this line to your shell profile too
herdr-doctor                         # Herdr hides the installer's output; exit 0 on a clean install, with Herdr running
herdr-trust ~/code/my-app            # once per repo, before agents start there

Then open your repo in Herdr, start Claude in a pane, and ask: "With stampede: ...". The walkthrough shows a whole job.

install.sh links the four skills into ~/.claude/skills/ and ~/.codex/skills/ (each only when ~/.claude or ~/.codex exists), and links stampede, fleet-job and the herdr-* helpers into ~/.local/bin. It is safe to re-run (ok for a link already in place) and never replaces anything already there (skip ... left as is), except, in a Herdr plugin install, its own link to the same file in an older checkout of that same install, which it moves to the new one (relinked). A clone relinks nothing. On Linux it also starts the event timers: systemd user timers when systemctl --user answers, otherwise one flock-guarded loop. --no-supervise skips that, --dry-run only prints it, and a HOME that is not the login home is skipped so a throwaway home never touches a real user manager. macOS still loads its launchd jobs by hand (watchdogs). herdr-trust marks a repo trusted for Claude, and for Codex when ~/.codex exists, so agents start without the folder-trust dialog; it refuses a repo outside FLEET_TRUST_ROOT (default ~/code), so keep your repos there or set the key.

Then, once: the settings that let agents start and run without a visit to their pane, which you run yourself: unattended-setup.md. A remote bot also needs the event relay. Both: docs/SETUP.md. To uninstall: docs/SETUP.md, Uninstall.

Updating

Once a day stampede tells you when a newer release is out; it never updates anything by itself. Then you update:

installed withupdate with
a clone and ./install.shstampede update
herdr plugin install vib-z/stampedeherdr plugin update stampede (add --yes from a bot, a script or SSH)

The daily check. At most once a day, stampede --version, stampede update --check and herdr-doctor ask GitHub for the latest release: one request without a token, given 3 s in all (DNS, connect and the reply), the answer cached for 24 h in ${XDG_CACHE_HOME:-~/.cache}/stampede/. When a newer release is out they print one line:

$ stampede --version
0.1.0
stampede 0.2.0 is out, this is 0.1.0: run stampede update

In a plugin install the line ends run herdr plugin update stampede --yes. stampede --version puts that line on stderr, after the version, and still exits 0; herdr-doctor prints it as a warn line, never a PROBLEM. Offline, rate-limited, a malformed reply or any other failure prints nothing and is cached too, so the next try is a day later. Turn the check off with export STAMPEDE_NO_UPDATE_CHECK=1 in your shell profile or ~/.config/stampede/config (Configure). To hear of a release on GitHub instead: on the repo page, Watch, then Custom, then Releases. How a release is cut: RELEASING.md.

stampede update is the guided updater: it updates only a clean checkout on main, and never overwrites a file of yours. It runs git fetch, fast-forwards with git merge --ff-only, reruns ./install.sh (which links any new skill or command), and ends with stampede 0.1.0 -> 0.2.0. It refuses with the reason, and changes no file, when the checkout has local changes or untracked files, is on another branch, or holds an ignored file at a path the update adds, which git would overwrite (refused: the update adds local-settings.txt, already in <checkout> (ignored by git, so it would be overwritten): move it away, then rerun). In a Herdr plugin install it changes nothing and prints herdr plugin update stampede --yes to run instead, though Herdr's checkout holds a .git.

A plugin update moves the links. Herdr gives each plugin install or update a new checkout folder and deletes the old one the next time its server starts. The installer it runs moves each stampede link that points at the same file in an older checkout of that same install to the new one, and leaves any other link alone (another plugin's, a backup's, one of yours); herdr-doctor reports a PROBLEM if stampede or a skill still resolves outside the checkout Herdr reports.

From 0.1.0, once. 0.1.0 has no stampede update (invalid choice: 'update'). Move the old clone aside, clone again to the same path and rerun the installer; the links keep their paths, so they work at once:

mv ~/stampede ~/stampede-0.1.0
git clone https://github.com/vib-z/stampede.git ~/stampede
~/stampede/install.sh

Keep anything of yours from ~/stampede-0.1.0, then delete it. From then on, stampede update. A plugin install pinned with --ref v0.1.0 stays pinned under herdr plugin update: herdr plugin install vib-z/stampede --yes drops the pin, and its installer moves the links.

Use: one job, start to finish

In a Herdr pane in your repo, ask your Claude chat: "With stampede: make hello.txt with hi, then have a reviewer on another model confirm it." The chat (a front door) writes the ask and starts the lead:

$ printf 'Make hello.txt with hi.\nThen have a reviewer on another model confirm it.\n' > ask.md
$ stampede new --file ask.md
recorded lead-make-hello-txt-with-hi (claude) in ~/code/herdr-jobs/jobs/2026-10-29-local-make-hello-txt-with-hi/agents.tsv
DELIVERED lead-make-hello-txt-with-hi (inbox file)
lead-make-hello-txt-with-hi ~/code/herdr-jobs/jobs/2026-10-29-local-make-hello-txt-with-hi

Inside Herdr, --workspace defaults to the current workspace and the lead gets a new lead tab; --pane <id> puts it in an empty pane instead, and --name <slug> names the job. A front door outside Herdr (a bot, a desktop app) has no current workspace, so it passes --workspace or --pane: it creates a workspace for the job (herdr workspace create) and passes its root pane, as in skills/stampede. The chat tells you lead-make-hello-txt-with-hi and stops.

Plan in chat, then fork it into the lead. A Claude chat where you and Claude already worked out the plan, in Herdr or the Claude desktop app, adds --fork "$CLAUDE_CODE_SESSION_ID": the lead starts as a fork of that chat (claude --resume <id> --fork-session), so it keeps the whole conversation and writes the agreed plan into plan.md instead of planning again. Your chat stays as it was. Put the agreed plan in the ask file too: it stays the source of truth, since a chat's saved transcript can miss some of its messages. The reopen record leaves the fork out, so reopen.sh resumes the lead's own session. Guide: remote/claude-code.md.

Pick the lead. The lead is Claude unless you ask for Codex: then the front door adds --lead codex (FLEET_LEAD_KIND=codex makes it your standing choice). A Codex lead runs GPT-6 Astra at ultra with its hooks and --approve-for-me; its brief pointer is typed into its pane at once:

$ stampede new --file ask.md --lead codex
recorded lead-make-hello-txt-with-hi (codex) in ~/code/herdr-jobs/jobs/2026-11-03-local-make-hello-txt-with-hi/agents.tsv
SUBMITTED lead-make-hello-txt-with-hi
lead-make-hello-txt-with-hi ~/code/herdr-jobs/jobs/2026-11-03-local-make-hello-txt-with-hi
$ stampede new --file ask.md --lead codex --fork "$CLAUDE_CODE_SESSION_ID"
fleet-job new: --fork forks a Claude chat, so it takes a Claude lead: drop --lead codex, or start without --fork

A Codex lead has no file hook, so stampede tell, the workers' hooks and its own turn ends start a short-lived deliverer that types its new inbox lines into its pane once it is idle, unfocused and has nothing typed in its prompt. Because text is typed there, it acts on a gate only after stampede gate-ok prints APPROVED. --core refuses --lead codex: a Herdr Core job's lead is Claude.

The lead reads ask.md, writes plan.md and goes on at once. Here it writes briefs/review-hello.md on the hand-off template, then starts one reviewer on another model:

$ J=~/code/herdr-jobs/jobs/2026-10-29-local-make-hello-txt-with-hi
$ stampede start $J review-hello --kind claude --pane <pane id> \
    --brief $J/briefs/review-hello.md \
    --model <another model> --effort max --report reports/review-hello.md
recorded review-hello (claude) in ~/code/herdr-jobs/jobs/2026-10-29-local-make-hello-txt-with-hi/agents.tsv
DELIVERED review-hello (inbox file)

When the reviewer writes reports/review-hello.md with Status: PASS in its first 10 lines and ends its turn, its hook adds REPORT reports/review-hello.md to inbox.log, which wakes the lead. A question for you, with the lead still working:

$ stampede ask $J "Keep the file in the repo root?" \
    --option Yes --option No
ASKED 1fecfa0be4dc (the answer goes to the lead inbox; cancel with: fleet-job cancel <job> 1fecfa0be4dc)

Your tap comes back as ANSWER ... in the lead's inbox. A gate (say, merging the draft PR) goes back to whoever started the job (Safety); you started this one in Herdr, so it is the lead's own question card or stampede ask --gate, on your phone. Then the lead writes a short report and asks whether to close the workspace; <job>/reopen.sh brings it back later.

Share the plan first

Say "share the plan first" and the front door adds --review. The lead then writes plan.md and ends its turn, and no pane can open until you approve that exact plan:

$ stampede new --file ask.md --name hello-review --review
recorded lead-hello-review (claude) in ~/code/herdr-jobs/jobs/2026-10-29-local-hello-review/agents.tsv
DELIVERED lead-hello-review (inbox file)
lead-hello-review ~/code/herdr-jobs/jobs/2026-10-29-local-hello-review
$ J=~/code/herdr-jobs/jobs/2026-10-29-local-hello-review
$ stampede start $J review-hello --kind codex \
    --pane <pane id> --brief <brief>
fleet-job start: the owner asked to see this plan: run fleet-job approve after their yes, and again after any change to the plan
$ stampede approve $J --by "owner in chat"
DELIVERED lead-hello-review (inbox file)
$ cat $J/approved
Approved: 2026-10-21 21:35 by owner in chat, plan 6ef5e2effdb06d6adf70e17da8726c05dd2d057a4a7ba23c4fbe3836eed14ffa

The start refusal exits 2. The approval holds a fingerprint of plan.md; any later change locks start again until a new approve. A change you ask for goes to the lead with stampede tell <job> lead "<your words>". The steps: share-plan.

A front door outside Herdr (the Claude desktop app)

When you talk to a chat outside Herdr, nobody watches the lead's pane, and a card or file the lead shows there reaches no one. The front door then starts the job with --front-door: the lead posts everything that is for you (the plan, questions, gates, files, its report) to <job>/outbox/, a hook turns its own question cards and SendUserFile into posts, and the front door waits on the outbox in the background and relays each item. Here a review job, with the chat as front door:

$ stampede new --file ask.md --pane <pane id> --name seller-copy --front-door --review
lead-seller-copy ~/code/herdr-jobs/jobs/2026-10-29-local-seller-copy
$ J=~/code/herdr-jobs/jobs/2026-10-29-local-seller-copy
$ stampede approve $J --by "owner in desktop chat: 'ok - lets go'"
fleet-job approve: the owner has not been shown this plan.md: the lead posts it (fleet-job post <job> "PLAN READY" --file plan.md), the front door sends it to the owner, and only their yes to it is approved
$ stampede post $J "PLAN READY: one Sonnet build, one review" --file $J/plan.md      # the lead
POSTED 001 for the front door to relay (~/code/herdr-jobs/jobs/2026-10-29-local-seller-copy/outbox/001.md)
$ stampede wait $J                                                                   # the front door, in the background
# 001 post

PLAN READY: one Sonnet build, one review

Files:
- ~/code/herdr-jobs/jobs/2026-10-29-local-seller-copy/outbox/001/plan.md
$ stampede approve $J --by "owner in desktop chat: 'approve as written'"
DELIVERED lead-seller-copy (inbox file)
$ stampede ask $J --gate --sha <commit> --pr 12 "mark PR #12 ready for review"        # the lead
GATE 83307febaa1a posted to the front door as outbox 002; act after fleet-job gate-ok ... prints APPROVED, or on the owner's yes typed in your pane
$ stampede approve-gate $J 83307febaa1a --sha <commit> --by "owner in desktop chat: 'mark it ready'"
APPROVED 83307febaa1a at <commit>

The front door shows you the plan file itself, and a yes to its own summary is never an approval. A gate's item carries the exact approve-gate line, which the front door runs with your words quoted. If the lead is held at a card anyway, stampede wait and stampede tell say BLOCKED_ON_CARD instead of pretending the message was read. The lead's finish posts a done item, and stampede wait says LEAD_GONE when Herdr no longer has the lead, so the front door is never left waiting on a job that ended. The front door's loop: skills/stampede; the lead's side: front-door.md.

Herdr Core

Herdr Core (hc 0.1.13 or later) is Herdr's terminal runtime: programs in persistent terminals that report their own status (OSC 7501), with labels and an event stream, and no workspaces, tabs or panes. stampede new --core runs a job there instead of on the Herdr TUI: Core is the job's backend, with its lead, follower and gates, and it can hand Cursor, Hermes or Kimi workers to Herdr TUI panes. A TUI-only job, and every TUI command, works as before. Install this version (install.sh, or stampede update) before a Core job: the lead runs the installed fleet-job, and the CLIs' relay hooks run from ~/.local/bin. An older copy can end a job without the stamp its follower waits for, and post plain turn ends to the default route.

What changes on Core, in short: each agent is its own terminal with no parent, so a worker never ends with the lead; its brief goes in with its start; its start, prompt and wake come from its own status, not its screen; one follower per job, herdr-event-core, reports every worker's block, error and exit to the lead (a hard kill included) and to a bot; a job outlives every window and comes back with reopen.sh; and only a recorded yes passes a gate. Cursor, Hermes and Kimi report no status, so a Core job hands them to Herdr TUI panes (below). The lead's playbook: references/core.md.

Check the machine once (this ran against a Mac's running core), then start the job from the repo (the job commands here ran against the test suite's fake hc, which answers as a real core does):

$ herdr-doctor --core
...
ok hc 0.1.13
ok Herdr Core answers (HC_SESSION default)
ok claude 2.1.312 reports its status (OSC 7501)
ok codex runs with --no-daemon
warn cursor-agent runs on the TUI only for stampede: it reports no OSC 7501 status on Herdr Core
...
$ stampede new --core --file ask.md --cwd ~/code/my-app
STARTED lead-add-health-endpoint-with (t2)
lead-add-health-endpoint-with <repo>/.herdr-add-health-endpoint-with

It wrote the job record first (backend, the key hc-a941d115ee38 in workspace, core.json), then started the follower (t1) and the lead (t2), each labelled stampede.job=<key>. The lead starts a worker with --cwd (default: the repo) instead of --pane, and talks to it by its status:

$ stampede start .herdr-add-health-endpoint-with review-health --kind codex \
    --brief .herdr-add-health-endpoint-with/briefs/review-health.md --report reports/review-health.md
STARTED review-health (t3)
$ stampede tell .herdr-add-health-endpoint-with review-health "Check the error path too"
SUBMITTED review-health (t3)
$ stampede tell .herdr-add-health-endpoint-with review-health "One more thing"
FAILED review-health (working: tell it after its turn)
$ stampede start .herdr-add-health-endpoint-with review-health --kind codex --brief <brief>
fleet-job start: review-health is already running at t3

The two FAILED and already running lines exit 2. When part of the job is gone (a reboot, a lost holder, the follower down), reopen.sh starts only what is missing:

$ bash .herdr-add-health-endpoint-with/reopen.sh --lead
RESTARTED relay-a941d115ee38 (t4)
$ bash .herdr-add-health-endpoint-with/reopen.sh
LIVE hc-a941d115ee38: no agent to restart

A lead that needs CI runs the wait as a labelled terminal, hc run --bg --no-parent --no-notify --name wait-ci-<pr> --label stampede.job=<key> --label stampede.role=wait -- gh pr checks <pr> --watch, and wakes on WAITED wait-ci-<pr> exit <code>. stampede finish ends the job as on the TUI, and the follower exits with it.

Hand an agent to a TUI pane

Core runs Claude and Codex. A Core job hands Cursor, Hermes or Kimi to a Herdr TUI pane at its shell prompt, with --pane in place of --cwd; the job, its follower, its inbox and its gates stay on Core (<pane> below stands for the pane id, <repo> for the repo; this ran against the fake hc and the tests' fake herdr):

$ stampede start .herdr-add-health-endpoint-with review-docs --kind cursor --pane "$P" \
    --brief .herdr-add-health-endpoint-with/briefs/review-docs.md --report reports/review-docs.md
STARTED review-docs (pane <pane>)
$ stampede tell .herdr-add-health-endpoint-with review-docs "Check the README too"
FAILED review-docs (working: tell it after its turn)
$ stampede tell .herdr-add-health-endpoint-with review-docs "Check the README too"
SUBMITTED review-docs (pane <pane>)
$ stampede start .herdr-add-health-endpoint-with review-docs --kind cursor --pane "$P" --brief <brief>
fleet-job start: review-docs is already running in pane <pane>
$ stampede start .herdr-add-health-endpoint-with review-api --kind kimi --pane "$P" --brief <brief>
fleet-job start: pane <pane> is handed to review-docs of <repo>/.herdr-add-health-endpoint-with: pick another pane; nothing started
$ stampede start .herdr-add-health-endpoint-with review-api --kind claude --pane "$P" --brief <brief>
fleet-job start: Herdr Core runs claude: start it with --cwd <dir>, never --pane

STARTED means Herdr showed the agent in its pane and took its brief pointer; the pointer passes the same checks as tell (idle, unfocused, an empty prompt it knows), so a draft in the prompt, an unknown prompt or an unclear read gives NOT BRIEFED with the fleet-job tell to send yourself, exit 1. Its identity is its name and pane, and its agent session once Herdr shows one; tell and reopen also use what the follower learned about it. The follower reads Herdr every 5 seconds on a thread of its own, so Herdr never holds up a Core event, and tells the lead as for a Core worker: TURN review-docs for Hermes and Kimi when Herdr's count of finished turns rises (Cursor's own stop hook writes its TURN), BLOCKED review-docs dialog, STALE and GONE review-docs exited; its bot events carry the pane id. While the job is open, the pane's mark in $HERDR_EVENTS_DIR/handed/ keeps every other event about it home, and the TUI watchdog skips it. tell prompts it once with herdr agent prompt, never a key, only while it is idle or done, unfocused, with an empty prompt and still the launch the job started. A reopen never starts it on Core and never types into it: LIVE review-docs (pane <pane>), NOT BRIEFED with the tell to send after reading its screen, or the exact start, each but LIVE with exit 1:

$ bash .herdr-add-health-endpoint-with/reopen.sh
NOT RUNNING review-docs (pane <pane>): start it again in a pane at its shell prompt: fleet-job start <repo>/.herdr-add-health-endpoint-with review-docs --kind cursor --pane <pane> --brief <repo>/.herdr-add-health-endpoint-with/briefs/review-docs.md --report reports/review-docs.md

On Herdr 0.9.5 (30 Oct 2026) a handed Cursor ran a live job; Herdr did not detect Hermes 0.22.5, so handing Hermes ends FAILED there (its CLI may still run in the pane: the line says how to end it). Kimi's empty prompt is not known yet, so a handed Kimi starts NOT BRIEFED and every tell to it fails closed: brief it by hand (planned, once its marker is verified). Hermes and Kimi run only this way: a TUI-only job refuses them. Watch a handed agent in its TUI pane: the Herdr app lists Core terminals only and never connects to the Herdr TUI server, so it never shows the agent, and it shows the job's Core lead and follower only by address (checked on 30 Oct 2026 with the Herdr app 0.1.9 on hc 0.1.14: no space, tab, terminal or agent for a handed Cursor, and no attach by its terminal id, pane id or name, from the app or hc attach). Details: core.md, Hand an agent to a TUI pane.

Front doors

Every front door writes the ask and runs stampede new; none plans or runs the job itself.

front doorhow you askwhere answers arriveguide
a chat in Herdrtype the ask in a Claude panethe lead's pane, plus a Moshi cardwalkthrough
Claude desktop or the Claude appRemote Control into a session on the machinethe lead's row in the Claude app, plus Moshiremote/claude-code.md
Codex desktop or the ChatGPT appCodex on the connected machineMoshiremote/codex.md
Cursora Cursor chat on the machine runs the same two commandsMoshiremote/other.md
Grok Bot (preferred bot)the bot reaches your Mac over SSH and Tailscalethe Grok chat, woken by a webhookremote/grokbot/, grokbot-herdr
any other botthe same as Grok Botits webhookremote/other.md
a whole remote computerHerdr, the CLIs and stampede on one boxany of the aboveremote/any-machine/

Any of them can run the job on Herdr Core instead: it passes --core --cwd <repo> in place of --pane or --workspace (Herdr Core).

Moshi, the phone side of every front door: remote/moshi.md.

Safety

  • Your own yes, every time: a merge to main, a push to main or another shared branch, a deploy, publishing, sending email or messages, any spend, and closing panes, tabs or a workspace. Pushing the job's own work branch and opening a draft PR need no ask.
  • Gates go back to whoever started the job. stampede new records the bot that started it (HERDR_EVENTS_OWNER, else the workspace's owner tag) in <job>/owner. The lead asks each gate with stampede ask <job> --gate --sha <commit> [--pr <n>] "<the exact action>":
    • started by a bot: a gate event goes to that bot (remote/events.md). The bot asks you in chat and, on your yes, runs stampede approve-gate <job> <gate> --sha <commit> --by "owner in <bot> chat" over SSH, which records it in <job>/gates/.
    • started locally: your phone, through FLEET_ASK_CMD (Moshi), records your tap the same way; or the lead's own question card.
    • started by a front door (--front-door): a post in <job>/outbox/. The front door shows you the exact action and, on your yes in its chat, runs stampede approve-gate ... --by "owner in <chat>: '<your words>'". An explicit order you already gave there for that exact action counts, quoted; anything vaguer goes back to you.
    • either way, on the Herdr TUI, a yes typed in a Claude lead's Herdr pane works.
  • The lead acts on your yes typed in its pane for that exact action (a Claude lead on the Herdr TUI only), or on a recorded yes for one gate at one commit: stampede gate-ok <job> <gate> --sha <the commit it acts on> prints APPROVED only when the record names that gate and that commit. A merge also passes --match-head-commit on that commit, so a push after your yes means asking again. approve-gate refuses inside Herdr, for a job started locally and for another commit: an agent's own say-so never counts, and nor does a plan, a brief or a yes passed on in a message.
  • A yes covers the gate as you were asked it. The record holds a digest of the gate's action, PR, commit and route: a gate changed after your yes makes gate-ok refuse, and the bot's approve command carries the same digest (--digest), so a gate changed between the question and your yes takes none. stampede finish cancels every question of the job still waiting on your phone.
  • A Codex lead counts only the recorded yes. stampede types its inbox into its pane, marked as from stampede, so text there proves nothing: it acts only after gate-ok prints APPROVED.
  • On Herdr Core only the recorded yes counts. If someone types yes or a similar gate approval in a job pane or terminal, the lead replies: "A typed yes does not count on Core; answer in the chat or on the phone that started this job." In a job started with stampede new --core the lead acts only after gate-ok prints APPROVED: a yes typed into the lead, an answer to its own question card, and any message never count, because on Core another program can type into any terminal (hc send, hc keys). Your tap on a phone card (FLEET_ASK_CMD) and a bot's approve-gate are recorded and count. approve-gate also refuses inside a Herdr Core terminal (HC_TERMINAL_ID, HC_TERMINAL_SOCKET or HC_SCOPE set) and under a herdr-core or hc process, so hc exec cannot run it: a bot runs it over plain ssh. Core's own blocked state is never a gate.
  • Auto mode, never no-checks mode, by default: Claude --permission-mode auto, Codex --approve-for-me, Cursor --auto-review, Hermes its default (a dangerous command asks), Kimi -y (a risky action asks). stampede start --yolo-in <worktree> runs a worker in its CLI's no-checks mode only when its pane's shell sits in its own linked git worktree, and never the lead.
  • Plan approval (only when you asked to see the plan) lets the lead work inside the job's own folder and branch; it is not a gate and covers no merge or spend.
  • Nothing closes by itself. The last step is always the question whether to close; no answer is a no.
  • Never touched: panes, tabs and workspaces the lead did not create; the pane you have focused; credentials and .env files.

Configure

…view the full README on GitHub.

// faq

What is stampede?

Text tasks to your Grok Bot. It reaches your Mac over Tailscale, where Claude Code does the job, adding other agents (Codex, Cursor and more) as needed. Nothing is merged, pushed, sent or spent until you say yes.. It is open-source on GitHub.

Is stampede free to use?

stampede is open-source under the MIT license, so it is free to use.

What category does stampede belong to?

stampede is listed under automation in the Claudeers registry of Claude-compatible tools.

8 views
★ 10 stars
unclaimed
updated 8 days ago

// embed badge

stampede on Claudeers
[![Claudeers](https://claudeers.com/api/badge/stampede.svg)](https://claudeers.com/stampede)

// retro hit counter

stampede hit counter
[![Hits](https://claudeers.com/api/counter/stampede.svg)](https://claudeers.com/stampede)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 260,254◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 110,676◷ MIT[ claude ]
→ see how stampede connects across the ecosystem