herdr-cli

Files (16)

• ARCHITECTURE.md
• README.md
• SKILL.md
• implement.md · prompts/
• plan.md · prompts/
• research.md · prompts/
• review.md · prompts/
• cli-reference.md · references/
• reference.md · references/
• agent_profile.py · scripts/
• herdr-common.sh · scripts/
• pipeline-herdr.sh · scripts/
• run-claude-herdr.sh · scripts/
• run-opencode-herdr.sh · scripts/
• run-pi-herdr.sh · scripts/
• runagent · scripts/

SKILL.md (first lines)

# herdr — Terminal Workspace Manager for AI Agents

herdr is a terminal workspace manager that hosts and orchestrates AI coding agents (pi, Claude Code, Codex, Gemini, Cursor, Devin, and 15+ more) in persistent terminal sessions behind a UNIX socket.

## Primary Workflow — Launching and Using an Agent

__ATTENTION: Launch agents with the helper scripts (Decision Guide below), NOT with raw `herdr` CLI subcommands.__

### Decision Guide

| Situation | Use |
|---|---|
| Named role with a profile (system prompt + tools/skills/extension/MCP allowlists, sandbox) | `runagent <name> -p "..."` |
| Ad-hoc one-shot, model only, no profile | `run-<kind>-herdr.sh -m <model> -p "..."` |
| Multi-stage pipeline (research → plan → implement → review) | `pipeline-herdr.sh` |
| Reuse an existing workspace, inspect/drive a launch step by step, agent kind without a script (codex, gemini, …) | manual `herdr` CLI (fallback below) |

### Manual Workflow (fallback only)
1. **Ensure the server is running**: `herdr status`. If not, start with `herdr server`.
2. **Create a workspace** (auto-creates a default tab): `herdr workspace create --label "my-project"`.
3. **Get the default tab and pane**: `herdr tab list --workspace <ws_id>` and `herdr pane list --workspace <ws_id>`.
4. **Start an agent in the default pane**: `herdr agent start "agent-name" --kind pi --pane <pane_id>`.
5. **Send a task (synchronous)**: `herdr agent prompt "agent-name" "your instruction" --wait --timeout 60000`. (Omit `--until` to match `idle|done|blocked` automatically.)
6. **Read output**: `herdr agent read "agent-name" --source recent --lines 100`.

The workflow is complete when `--wait` returns. Verify with `herdr agent list`.

## Helper Scripts

Each script wraps the whole primary workflow (server check → workspace → tab → pane → agent
start → prompt → wait → read output) in one command.

| Script | Agent kind | Model format |
|--------|-----------|--------------|
| `scripts/run-pi-herdr.sh` | `pi` | `provider/model` (e.g. `evo/ornith-1.0-35b-Q6`) |
| `scripts/run-claude-herdr.sh` | `claude` | alias or full name (`sonnet`, `opus`, `haiku`, `claude-sonnet-4-5`) |
| `scripts/run-opencode-herdr.sh` | `opencode` | `provider/model` (e.g. `anthropic/claude-sonnet-4-5`) |
| `scripts/pipeline-herdr.sh` | multi-stage | per-stage `--<stage>-kind` / `--<stage>-model` |

The three `run-*` scripts share their workflow via `scripts/herdr-common.sh` (sourced, not
executed — edit it to change behavior for all three at once).

**Options shared by all three `run-*` scripts:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--model <model>` | `-m` | Model (required) | — |
| `--prompt <text>` | `-p` | Task prompt (required) | — |
| `--timeout <ms>` | `-w` | Wait timeout | `120000` |
| `--name <name>` | `-n` | Agent name | auto from model |
| `--cwd <path>` | `-c` | Workspace working directory | current dir |
| `--label <label>` | `-l` | Workspace label | auto from model |
| `--no-keep` | `-nk` | Close the workspace when done | keep it open |
| `--no-wait` | `-nw` | Fire-and-forget: submit and exit | wait for completion |
| `--help` | `-h` | Full usage and examples | — |

**Agent-specific options:**

| Script | Option | Description |
|--------|--------|-------------|
| pi, claude | `-sp, --system-prompt <text>` | Replace the system prompt (claude also expands `@file`) |
| pi, claude | `-asp, --append-system-prompt <text>` | Append to the system prompt (repeatable) |
| pi | `-sk, --skill <path>` | Load a skill file or directory (repeatable) |
| pi | `-pr, --profile <name>` | Resolve skills from an agent profile (`~/.pi/agent/agents/<name>.md`) via `agent_profile.py` (same resolution as `runagent`) and add `--skill` flags |
| claude | `--agent <name>` / `--agents <json>` | Predefined subagent / inline subagent definitions |
| claude | `--permission-mode <mode>` | `default`, `acceptEdits`, `plan`, `bypassPermissions` |
| claude | `--yolo` | `--dangerously-skip-permissions` (sandboxes only) |
| opencode | `--agent <name>` | Predefined opencode agent (`opencode agent list`) |
| opencode | `--auto` | Auto-approve permissions not explicitly denied (dangerous) |

```bash
# One-shot task, workspace kept open afterwards
scripts/run-pi-herdr.sh -m "evo/ornith-1.0-35b-Q6" -p "Explain src/main.ts"

# Custom cwd and a longer timeout
scripts/run-claude-herdr.sh -m opus -p "Refactor the auth module" -c /path/to/project -w 180000

# Predefined subagent, auto-approve, close the workspace when done
scripts/run-opencode-herdr.sh -m "anthropic/claude-sonnet-4-5" -p "Review the diff" \
    --agent reviewer --auto --no-keep

# Fire-and-forget
scripts/run-pi-herdr.sh -m "qwen3.6-35b" -p "Run the full test suite" --no-wait

# Skills resolved from an agent profile (impl/review from the planka skill)
scripts/run-pi-herdr.sh --profile impl -m "dgx/qwen3.8-27b-q4" -p "Fix PLANKA-42" --no-wait
```

Run any script with `--help` (or no arguments) for its full option list and examples.

### `pipeline-herdr.sh` (Research → Plan → Implement → Review)

Deterministic multi-stage pipeline: one herdr workspace, one tab + agent per stage, strictly
sequential. Stages hand work forward through files in `<repo>/.agent-work/` (never through
prompt text). Each stage has a mechanical gate; a failed stage is re-run **once** with the gate
requirement and the transcript tail appended to its prompt.

```bash
# Default routing: plan on a strong model, research/implement on a local one
scripts/pipeline-herdr.sh /path/to/repo "Add retry with backoff to the API client"

# Override any stage
scripts/pipeline-herdr.sh /path/to/repo "Refactor config loader" \
    --plan-model opus --implement-model anthropic/claude-sonnet-4-5 --review-kind claude

# Resume after a failure (stages whose gate already passes are skipped)
scripts/pipeline-herdr.sh /path/to/repo --from-stage implement
```

| Stage | Artifact | Gate | Defaults |
|-------|----------|------|----------|
| research | `.agent-work/research.md` | exists, non-empty | `pi` / `dgx/qwen3.6-35b-mtp`, 1h |
| plan | `.agent-work/plan.md` | exists, non-empty | `claude` / `opus`, 1h |
| implement | `.agent-work/results.md` | ends with `RESULTS: all-pass` | `pi` / `dgx/qwen3.6-35b-mtp`, 3h |
| review | `.agent-work/review.md` | ends with `STATUS: clean` or `STATUS: open:<n>` | `pi` / `dgx/qwen3.8-27b`, 1h |

Stage behavior is defined by the static prompt files in `prompts/{research,plan,implement,review}.md`
— edit those to change what a stage does. The review stage re-runs the test commands itself
rather than trusting `results.md`.

From Kubementat/ai_agent_skills, MIT.

More from Kubementat/ai_agent_skills