Shep Development Orchestrator
Run coding agents in parallel Git worktrees and automate feature delivery through draft pull requests.
- Source repo
- shep-ai/shep
- Stars
- ★ 282
- Last updated
- 18d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeOpenAI API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An individual developer handling several independent features can run one isolated worktree per task to reduce branch conflicts.
- Not a fit if
- Teams that need one centrally shared service
- Teams that require merges without human review
- Website
- shep.bot ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-02latest release v1.253.1 (2026-10-31)
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Shep is a local-first, open-source development orchestrator with a CLI and a web control center at localhost:4050. It runs each feature in its own Git worktree and branch, supporting Claude Code, Kimi Code, Codex CLI, Copilot CLI, Cursor CLI, Gemini CLI, Cline, and several API or local HTTP providers. The default workflow starts with a feature description, then implements, commits, pushes, and opens a pull request; Shep can also watch CI and have an agent attempt fixes when it fails. For complex work, an optional YAML-based workflow adds requirements, research, and planning phases with approval gates before code is written. Shep runs on the developer’s machine and stores data in SQLite under ~/.shep/; its output is a branch and draft PR for human review.
When you run shep feat new <description>, Shep creates an isolated worktree and branch for the feature, then calls the configured agent CLI or a supported API provider to implement it. The optional spec-driven workflow creates versioned YAML requirements, research, and plan artifacts, with approval gates between phases. Shep can then commit changes, push the branch, open a draft PR, watch CI, and, if CI fails, give the logs to the agent and attempt a fix—up to 3 retries by default. The CLI manages features, agents, repositories, and settings; the web control center shows live status, diff review, and interactive chat, and can open a worktree in an IDE with one click.
- An individual developer handling several independent features can run one isolated worktree per task to reduce branch conflicts.
- A team that wants draft PRs from short feature descriptions can automate implementation, commits, pushes, and PR creation.
- Developers using different coding agents can switch among built-in CLI agents, API providers, or local model providers for each feature or repository.
- Engineering teams that want to review requirements and plans before code is written can enable the spec-driven phases and approval gates.
- Developers maintaining projects with CI can have Shep watch failure logs and let an agent attempt fixes.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npx @shepai/clinpm i -g @shepai/cli
- Runtime
- Node.js 22+
How do you install or deploy this agent?
Requires Node.js 22+, pnpm 10+, Git, GitHub CLI (gh), and an authenticated supported agent CLI. API providers require their respective API keys. Try it with npx or install the CLI globally:
npx @shepai/clinpm i -g @shepai/cliHow do you use this agent?
In the target Git repository, create a feature and ask Shep to push its branch and open a PR:
cd ~/projects/my-app
shep feat new "add a /health endpoint that returns uptime and version" --push --prStart the web control center:
shep startThe default address is localhost:4050. Add --no-fast to run the full spec-driven workflow for complex features. Run multiple shep feat new commands to start parallel tasks.
What are this agent's strengths and limitations?
- Each feature gets its own Git worktree and branch, keeping the current working directory untouched and reducing parallel task conflicts.
- Automates the path from feature description through commit, push, draft PR, and CI watching, with agent fix attempts when CI fails.
- Includes several CLI agents plus OpenRouter, Together AI, Ollama, and OpenAI-compatible proxy paths, which can be selected per feature.
- Complex tasks can use versioned YAML requirements, research, and plans with approval gates before coding begins.
- Requires Node.js, pnpm, Git, and GitHub CLI; the PR workflow also relies on an authenticated GitHub CLI.
- Coding agents must be installed and authenticated, or an API provider key must be supplied; users cover any model or API charges.
- Agents run non-interactively with permission-bypass flags by default; tighter permissions require configuring the agent separately.
- Shep is not a security scanner and cannot catch vulnerabilities that CI misses; usage metrics are collected by default, though they can be disabled.
- The documented product runs locally per developer; a centralized team service or shared deployment mode is not described.
How does this agent compare with similar options?
The README compares Shep with using a coding agent directly: the agent writes code, while Shep manages worktrees, commits, pushes, PRs, and CI watching.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Shep Development Orchestrator This agent | 53 · Major gaps | CLIFree + model costs | ★ 282 | 18d ago | TypeScript | Codex · Claude Code |
| dmux | 55 · Major gaps | CLIFree + model costs | ★ 1.8k | 3mo ago | HTML | Codex · Claude Code · OpenAI API |
| Open Dynamic Workflows | 69 · Some gaps | CLIFree + model costs | ★ 115 | 1mo ago | TypeScript | Codex · Claude Code |
| Agor | 68 · Some gaps | CLIFree + model costs | ★ 1.5k | 1d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The README describes worktree isolation, draft PRs by default, merge approval, a stop command, and local logs. It also explicitly says agents run non-interactively with permission-bypass flags by default, so least privilege is only partially addressed. Push, PR creation, and auto-merge can be enabled through flags or settings, providing approval gates, but confirmation details for high-impact actions are limited. The README and CLAUDE.md describe telemetry destinations, event categories, opt-out controls, and identity fields as opt-in. Tokens in the settings database are stored as plain text, leaving sensitive-data handling thin. SECURITY.md describes dependency-risk governance and CI security gates, but the packet does not establish lockfile controls or mitigation for individual dependency risks. External effects include agent execution, pushes, PRs, and telemetry, with some controls documented. The worktree is preserved after stopping and Git branches support recovery, so rollback support is adequate but not comprehensive. The author and repository are named, but publisher identity is unverified and cannot establish maintainer identity.
The docs describe isolated worktrees, CI monitoring, up to three auto-fix retries, and pausing after failure. This supports ordinary workflow reliability, but README, AGENTS.md, and other materials differ in CLI, product-scope, and workflow descriptions; the AGENTS.md excerpt is also incomplete. Prerequisites include Node, pnpm, Git, GitHub CLI, and an agent CLI, but dependency availability and fallback behavior are only partly addressed. The CLI entry point shows concrete database initialization and SQLite native binding error messages and remediation guidance, which is useful failure handling.
The materials cover individual local use, parallel features, multiple agent providers, existing repositories, and new apps, with both fast and spec-driven workflows. They state that Shep is not a security scanner, that code is sent to the selected agent, and that large-repository limits depend on the agent context window; capability boundaries are present but incomplete. Some skills define explicit trigger phrases, but the skill sample is not the whole product and some trigger descriptions are broad, limiting trigger precision. The setup guide specifies Node 22, pnpm 10, supporting tools, and multiple agent choices, giving useful environment guidance.
The README links to CLI, architecture, configuration, security, development, and getting-started documentation, and the guides provide installation steps, commands, and examples. Naming and concepts are mostly stable, though materials use varying product descriptions such as 'Autonomous AI Native SDLC Platform,' and the README's abbreviated command reference does not match the broader command list in the CLI entry point. The README has an FAQ and describes security limitations and some unsupported agents. The LICENSE contains the full MIT terms and merits full marks. package.json gives a version, SECURITY.md says only the latest release is supported, and AGENTS.md describes semantic-release rules; the packet does not include a full changelog. The security policy gives a private reporting channel and response targets, providing some maintenance responsibility evidence. Unverified publisher identity neither adds nor subtracts points.
The CLI, web UI, worktrees, parallel agents, CI repair, and PR flow produce branches and draft PRs that users can review. Compared with using one agent directly, Shep adds parallel coordination, run status, retries, and integration steps, showing practical marginal value. Cost is only partly addressed: the docs say reasoning effort, model choice, and parallel agents affect cost and latency, but provide no cost or resource estimates, so cost-benefit is scored conservatively.
The README links to documentation for telemetry, approvals, safety boundaries, and commands; package.json provides version and scripts; and SECURITY.md describes security processes. These make many claims traceable. Some claims are repeated across the README, getting-started guide, and configuration guide, but visible descriptions differ and the packet lacks enough source code to verify every claim, so cross-source corroboration is partial. The docs distinguish product descriptions, configuration, and limitations. This review treats explicit statements as evidence and does not infer that files outside the sample are absent.
- The README says agents use permission-bypass flags by default. Review the selected agent's effective permissions before use; worktree isolation does not constrain everything an agent can do on the host.
- The README says tokens are stored in plain text in the local settings database. Protect the Shep data directory and avoid placing tokens in untrusted environments.
- Telemetry is enabled by default. The docs describe opt-out controls and event scope; confirm local settings and organizational policy before deployment.
- This static assessment uses only the supplied documentation and source excerpts. The product was not run, and files outside the packet were not checked.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
<p align="center"> <a href="https://github.com/shep-ai/shep"> <img src="https://raw.githubusercontent.com/shep-ai/shep/main/docs/screenshots/shep-card.jpg" alt="Shep — run multiple AI agents in parallel" width="720" /> </a> </p> 🚀 Shep [v1.253.1](/compare/v1.253.0...v1.253.1) · _2026-10-31_ > _Routine maintenance pass_ — no new features, just keeping the internals tidy so the next release lands clean. 🐛 Bug Fixes …View on GitHub ↗ -
Release notes excerpt
<p align="center"> <a href="https://github.com/shep-ai/shep"> <img src="https://raw.githubusercontent.com/shep-ai/shep/main/docs/screenshots/shep-card.jpg" alt="Shep — run multiple AI agents in parallel" width="720" /> </a> </p> 🚀 Shep [v1.253.0](/compare/v1.252.2...v1.253.0) · _2026-10-30_ > _No user-facing changes_ — purely internal upkeep to keep the codebase tidy under the hood. ✨ Features …View on GitHub ↗ -
Release notes excerpt
<p align="center"> <a href="https://github.com/shep-ai/shep"> <img src="https://raw.githubusercontent.com/shep-ai/shep/main/docs/screenshots/shep-card.jpg" alt="Shep — run multiple AI agents in parallel" width="720" /> </a> </p> 🚀 Shep [v1.252.2](/compare/v1.252.1...v1.252.2) · _2026-10-29_ > All 40 open Dependabot alerts _cleared in one sweep_ — Next 16.4, TypeSpec 1.17 and patched transitive deps. 🐛 Bug Fixes …View on GitHub ↗
FAQ
Where does Shep send my code?
What happens if an agent produces bad code?
Can Shep merge pull requests automatically?
--allow-merge.Can a team share one Shep service?
Is Shep Development Orchestrator free?
Is Shep Development Orchestrator open source?
Is Shep Development Orchestrator safe to use?
Is Shep Development Orchestrator still maintained?
Who makes Shep Development Orchestrator?
What is Shep Development Orchestrator's official website?
Thanks — we use this to improve the page.