# Shep

> Run parallel coding agents in isolated git worktrees, from one line to a pull request

- Category: AI Coding / Autonomous Coding Agents
- Language: TypeScript
- Licence: MIT
- Repository: https://github.com/shep-ai/shep
- Website: https://shep.bot
- Canonical page: https://ai-tldr.dev/tools/shep/
- Updated: 2026-02-02

## In short

Shep is a local-first orchestrator for running several coding agents at once. Each feature gets its own git worktree on its own branch, so your working directory is never touched and parallel agents cannot collide on branches. It sits in the Autonomous Coding Agents category of the AI Coding tools and is open-source, written in TypeScript and licensed MIT.

## Overview

Shep is a local-first orchestrator for running several coding agents at once. Each feature gets its own git worktree on its own branch, so your working directory is never touched and parallel agents cannot collide on branches. From a one-line description Shep drives the whole cycle: optional spec gates, implementation, commit, push, CI watching with auto-fix, and a draft pull request — leaving you the diff review and the merge button.

It is agent-agnostic by design. Claude Code, Cursor CLI and Gemini CLI are built in, and any other terminal agent CLI can be driven through a generic executor. You can swap the agent or the model per feature and per repository, so neither choice becomes a lock-in. The default flow is fast — prompt, implement, commit, push, PR — while `--no-fast` turns on the spec-driven pipeline, where requirements, research and a plan are written as versioned YAML artifacts with approval gates before any code is written.

Everything the CLI does is also available in a web control centre at `localhost:4050`: a live graph of every repository and feature, real-time status, diff review, interactive chat and one-click open in your IDE. Shep runs entirely on your machine — state lives in `~/.shep/` as SQLite, and your code goes only to whichever agent you configured, under that agent's own terms. The project notes there are no Shep servers to send anything to.

## What it does

- One isolated git worktree and branch per feature, so several agents run in parallel without touching your working directory
- Full prompt-to-PR cycle: implement, commit, push, watch CI, auto-fix failures (three retries by default), open a draft pull request
- Agent-agnostic — Claude Code, Cursor CLI and Gemini CLI built in, any other terminal agent CLI through the generic executor
- Optional spec-driven mode where requirements, research and plan land as versioned YAML with approval gates before code is written
- Web control centre at localhost:4050 with a live repo/feature graph, diff review, chat and IDE hand-off — everything the CLI can do
- Per-feature flags for push, PR, auto-merge, model and target repo, with global defaults set once via `shep settings`
- Local-first: state in ~/.shep/ as SQLite, code sent only to the agent you configure

## Getting started

Shep is an npm package. It needs Node.js 22 or newer, Git, the GitHub CLI (`gh`), and at least one authenticated agent CLI (`claude`, `cursor` or `gemini`).

1. Install

   Try it without installing, or install the CLI globally.

```bash
npx @shepai/cli        # opens the dashboard at localhost:4050
npm i -g @shepai/cli   # or install globally
```

2. Ship one feature

   From inside a repository, describe the change in a sentence. Shep creates the worktree, runs the agent, commits, pushes and opens the PR.

```bash
cd ~/projects/my-app
shep feat new "add a /health endpoint that returns uptime and version" --push --pr
```

3. Go parallel

   Start several features at once — each gets its own worktree and branch, all monitored from one place.

```bash
shep feat new "add stripe payments" --push --pr
shep feat new "add dark mode toggle" --push --pr
shep feat new "fix login redirect bug" --push --pr
```

4. Follow and steer the work

   List and inspect features, approve or reject a spec phase, read agent logs, or stop a run outright.

```bash
shep feat ls
shep feat show <id>
shep feat approve <id>
shep feat reject <id> --feedback
shep agent logs <id>
shep agent stop <id>
```

5. Set defaults once

   Stop repeating flags by writing them into the workflow settings, and choose the agent, model and IDE Shep should use.

```bash
shep settings workflow
shep settings agent
shep settings model
shep settings ide
```

## When to use it

- Reach for it when more than one agent session at a time turns into branch chaos
- Reach for it to take a backlog of small, independent changes from description to open pull requests overnight
- Reach for it when CI failures should be read and fixed by the agent before you look at the diff
- Reach for it when a feature is big enough to want written requirements and a plan approved before any code is generated

## Version history

- 2026-02-02: Covered by AI/TLDR: an MIT-licensed CLI and web dashboard that runs multiple AI coding agents in parallel, each in an isolated git worktree, automating the prompt-to-PR lifecycle with CI watching and auto-fix.