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`).
Install
Try it without installing, or install the CLI globally.
npx @shepai/cli # opens the dashboard at localhost:4050
npm i -g @shepai/cli # or install globallyShip 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.
cd ~/projects/my-app
shep feat new "add a /health endpoint that returns uptime and version" --push --prGo parallel
Start several features at once — each gets its own worktree and branch, all monitored from one place.
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 --prFollow and steer the work
List and inspect features, approve or reject a spec phase, read agent logs, or stop a run outright.
shep feat ls
shep feat show <id>
shep feat approve <id>
shep feat reject <id> --feedback
shep agent logs <id>
shep agent stop <id>Set defaults once
Stop repeating flags by writing them into the workflow settings, and choose the agent, model and IDE Shep should use.
shep settings workflow
shep settings agent
shep settings model
shep settings ideCommands and code are distilled from the project's own documentation — always check the official repo for the latest.
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
How Shep compares
Shep alongside other open-source autonomous coding agents tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| opencode | ★ 208k | OpenCode is an open source AI coding agent that runs in your terminal, with built-in build and plan agents and an optional desktop app. |
| Claude Code | ★ 145k | Anthropic's agentic coding tool for the terminal, IDE and GitHub: it understands your codebase, executes routine tasks, explains code and handles git workflows from natural-language commands. |
| OpenAI Codex | ★ 125k | OpenAI's cloud and CLI coding agent that writes features, fixes bugs, and proposes code changes across a repo, running tasks in parallel. |
| Gemini CLI | ★ 107k | An open-source command-line AI agent from Google that connects your terminal to Gemini models for reading code, editing files, running shell commands, and searching the web. |
| Pi | ★ 106k | Minimal terminal coding agent harness with four built-in tools, extended through TypeScript extensions, skills and prompt templates instead of forks. |
| autoresearch | ★ 96.1k | Karpathy's minimal harness that hands a coding agent a single-GPU LLM training script and lets it run fixed five-minute experiments, keeping or discarding each change on its own. |
| OpenHands | ★ 88.2k | An open-source AI software-development agent that plans tasks, edits files, runs commands, and tests code, usable from a terminal CLI, a local web GUI, or a Python SDK. |
| Shep | ★ 253 | Run parallel coding agents in isolated git worktrees, from one line to a pull request |