pstack-herdr

pstack for Claude Code and Codex, with delegated agents running as visible Herdr panes.

This is a fork of michael-denyer/pstack-claude, the Claude Code and Codex port of Lauren Tan's pstack. It has 54 Agent Skills: 31 public skills and 23 principle-* leaves. The skill tree is synced against upstream 12d587d from cursor/plugins/pstack.

Inside Herdr (HERDR_ENV=1), workflows that delegate start real Claude Code or Codex workers in Herdr panes, routed by role. You can watch and answer each worker. Outside Herdr, the plugin behaves like pstack-claude.

Install

Claude Code

/plugin marketplace add TiewKH/pstack-herdr
/plugin install pstack@pstack-claude

Codex

codex plugin marketplace add TiewKH/pstack-herdr
codex plugin add pstack@pstack-claude

Run setup-pstack to change model defaults, set a reasoning effort per role (for example arena runners: opus @xhigh, fable @max, which Claude Code dispatches through the plugin's pstack:effort-<level> or pstack:poteto-agent-<level> agents; roles without a level keep the session's effort unless the sheet's default effort line names one), or turn automatic routing off. The plugin installs the routing hook on Claude Code and Codex; Codex asks you to trust it through /hooks before it runs. In Claude Code, use /pstack:setup-pstack. For skills-only installs and other runtimes, see shared installation.

Use it with Herdr

1. Install Herdr, then its integrations for the CLIs you use: herdr integration install claude and herdr integration install codex.
2. Inside Herdr, run /pstack:setup-pstack. It writes ~/.config/pstack-herdr/routes.yaml, which maps each role to a Claude or Codex profile, model, and effort. config/routes.example.yaml shows the format.
3. Start the coordinator inside Herdr and give poteto-mode a task:

Use poteto-mode to fix the search filter resetting when I change pages.

poteto-mode picks the playbook. For a bug, it reproduces the failure, investigates with how and why, delegates the fix to an implementation worker, and reruns the failing case.

How delegation works

Layer	Owns
pstack skills	decomposition, roles, worktree isolation, synthesis, review, verification
herdr-dispatch.ts	pane creation, profile environment, CLI startup, prompt delivery, waiting, output reads, pane cleanup, delegation depth
herdr-agent-gate.sh	on Claude Code, denies the native Agent tool inside Herdr and returns the dispatcher command
Herdr	panes, agent status, visibility
Claude Code, Codex	the delegated work

Skills keep Claude's Agent vocabulary. herdr-tools.md translates it to dispatcher calls when HERDR_ENV=1, the same way codex-tools.md does for Codex. HERDR.md is the runtime contract: roles, routing, depth limits, isolation, and the dispatcher's lifecycle.

More

• Skills and slash commands
• Runtime setup
• Models and dependencies
• Maintenance and port scope
• Contributing and security reports

Data handling

pstack has no server or telemetry. Anything its skills ask your agent to read, including session transcripts, goes to your model provider. Scripts run locally, and PR tools use your GitHub CLI login. Herdr workers run as local Claude Code or Codex processes under the profiles you configure.

Attribution

• pstack and Poteto Mode by Lauren Tan (poteto), MIT.
• pstack-claude, the Claude Code and Codex port, by Michael Denyer.
• Imported cursor-team-kit skills by Cursor, MIT.
• Herdr by herdrdev, Apache-2.0. It is an external runtime, not vendored or relicensed here.

This fork's changes are also MIT-licensed. See NOTICE.md and LICENSE-cursor-team-kit.