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

At a glance

How it runs
CLIWeb app
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
Node.js 22+pnpm 10+GitGitHub CLI (gh)An authenticated agent CLI or an API key for a supported providerShell / CLINetwork accessLocal filesystem
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)

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.

  1. An individual developer handling several independent features can run one isolated worktree per task to reduce branch conflicts.
  2. A team that wants draft PRs from short feature descriptions can automate implementation, commits, pushes, and PR creation.
  3. Developers using different coding agents can switch among built-in CLI agents, API providers, or local model providers for each feature or repository.
  4. Engineering teams that want to review requirements and plans before code is written can enable the spec-driven phases and approval gates.
  5. 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/cli
  • npm 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/cli
npm i -g @shepai/cli

How 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 --pr

Start the web control center:

shep start

The 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?

Pros
  • 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.
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
53/ 100 5-point scale 2.7 / 5
Trust 14/29
Reliability 6/14
Adaptability 10/18
Convention 12/18
Effectiveness 7/13
Verifiability 4/8
Why each dimension lost points
Trust14 / 29 · 2.4/5

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.

Reliability6 / 14 · 2.1/5

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.

Adaptability10 / 18 · 2.8/5

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.

Convention12 / 18 · 3.3/5

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.

Effectiveness7 / 13 · 2.7/5

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.

Verifiability4 / 8 · 2.5/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 13, 2026 Reviewed revision 56301d59a0d5
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/shep.svg)](https://followagents.com/en/agents/shep)
<a href="https://followagents.com/en/agents/shep"><img src="https://followagents.com/badge/shep.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v1.253.1
    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 ↗
  2. v1.253.0
    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 ↗
  3. v1.252.2
    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?
The README says Shep stores data locally. Code goes only to the agent you configure and is subject to that agent’s privacy terms.
What happens if an agent produces bad code?
Shep opens a draft PR and runs project CI. If CI fails, the agent can read the logs and attempt a fix, up to 3 retries by default; then it pauses and notifies you.
Can Shep merge pull requests automatically?
Not by default. Automatic merging after CI passes requires explicitly enabling --allow-merge.
Can a team share one Shep service?
The README describes Shep as running locally per developer. Features are delivered as branches and PRs through the team’s existing review process.
Is Shep Development Orchestrator free?
The software is free, but Shep Development Orchestrator calls an AI model, and you pay that model provider for usage (or run a local model).
Is Shep Development Orchestrator open source?
Yes. The source code is on GitHub (shep-ai/shep) under the MIT licence.
Is Shep Development Orchestrator safe to use?
FollowAgents' FARS review (Nov 13, 2026) scored Shep Development Orchestrator 14/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is Shep Development Orchestrator still maintained?
Yes. The latest commit on GitHub is from 2026-11-02, within the last 30 days. The latest release is v1.253.1 (2026-10-31).
Who makes Shep Development Orchestrator?
Shep Development Orchestrator is published on GitHub by the account shep-ai. FollowAgents has not verified which person or company is behind that account.
What is Shep Development Orchestrator's official website?
The project's GitHub repository lists https://shep.bot as its website. That link is set by the repository owner; the source code itself is on GitHub (shep-ai/shep).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts