Shep CLI
Shep runs several coding agents in parallel, each in its own git worktree, and takes every task through to a draft pull request
- 269 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Runs the agent with permission-bypass flags by default, so it executes commands and edits files without asking
- Pushes branches and opens pull requests on your behalf through GitHub CLI
- Sends usage metrics to the project team until you turn them off
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/shepDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Runs the agent with permission-bypass flags by default, so it executes commands and edits files without asking
- Pushes branches and opens pull requests on your behalf through GitHub CLI
- Sends usage metrics to the project team until you turn them off
This is third-party code. Review the repository files before installing.
What it does
Shep installs from npm as the @shepai/cli package and drives coding agents you already have: Claude Code, Kimi Code, Codex CLI, Copilot CLI, Cursor CLI, Gemini CLI or Cline. For each task it creates a separate git worktree on its own branch, so your working directory stays untouched and three tasks do not conflict. You describe a task in one line: shep feat new "add a /health endpoint" --push --pr. Shep then runs the agent, commits the result, pushes the branch and opens a draft pull request. If CI fails, the agent reads the logs and pushes a fix, three attempts by default, after which Shep stops and notifies you. For complex tasks the --no-fast flag enables the full cycle: requirements, research and a plan as versioned YAML files, with approval at each step before any code is written. The state of all repositories and tasks is visible in a web dashboard at localhost:4050, and the CLI does the same. The shep app new command starts a new application, and every later task attaches to it. Data lives locally in ~/.shep in SQLite, and your code goes only to the agent you chose.
Who it is for. For developers who run several tasks at once in Claude Code, Codex or Gemini CLI and want ready pull requests out of them.
Good fit when
- You want three to five independent tasks running on one repository without branch conflicts
- You want a task taken from description to a draft pull request in one command, including push and CI watching
- You need approved requirements and a plan before any code, and you are ready to approve each step
- You switch agents per task and want a single interface over Claude Code, Codex and Gemini CLI
Not a fit when
- You have a single task and the agent in a terminal is enough
- You cannot run an agent with permission-bypass flags: Shep passes them by default
- The repository has no GitHub CLI access: push and pull request flow uses gh
- You need a security scanner: Shep orchestrates agents and does not look for code vulnerabilities
Example request
Install Shep and run three tasks in parallel in this repository: dark mode, login redirect and a /health endpoint, each with a draft pull requestLimitations
Requires Node.js 22 or newer, pnpm 10, Git, GitHub CLI and an authenticated CLI of at least one agent. Shep runs the agent without interactive prompts and by default passes permission-skipping flags, for example --dangerously-skip-permissions for Claude Code. Usage metrics are on by default and are turned off with shep telemetry off or the DO_NOT_TRACK=1 variable. Aider and Continue support is listed as upcoming. Data and the action log live in a local database in ~/.shep, so account for permissions on that folder on a shared machine.
How to disable. The shep stop command halts the daemon and npm uninstall -g @shepai/cli removes the package. Data sits in ~/.shep and is deleted by hand. Individual agents are stopped with shep agent stop <id>.
FAQ
How is Shep different from running Claude Code directly?
The agent writes the code, and Shep handles what surrounds it: worktrees, commits, push, pull requests, CI watching and retries. The difference shows most with three to five parallel tasks.
What happens if CI fails?
The agent reads the logs and pushes a fix, up to three attempts by default. After that the task enters the Blocked state and Shep notifies you. Shep does not merge code that fails CI.
Does Shep merge pull requests on its own?
Not unless you pass the --allow-merge flag. By default it opens a draft and the merge stays with you.
Which agents are supported?
Claude Code, Kimi Code, Codex CLI, Copilot CLI, Cursor CLI, Gemini CLI and Cline are built in, along with OpenRouter, Together AI, Ollama and any OpenAI-compatible proxy over HTTP.
Where does my code go and what does Shep collect?
Data is stored locally in ~/.shep, and only the agent you chose receives your code. Usage metrics are on by default and are turned off with shep telemetry off: prompts, code and repository names are not part of them.
Discussion
No questions or reviews yet.
Related
CLI toolsA coding agent for the terminal and desktop: it does not count "done" without tests or a diff and works with DeepSeek, GLM, Kimi, Claude, Codex and Gemini
A CLI that gives six coding agents project context, over 80 skills, verification and resumable tasks across sessions
A tool and skill that let Claude Code hand tasks to Claude, Codex or OpenCode subagents in separate Git worktrees
A Python terminal coding agent in the manner of Claude Code: reads the repository, edits files, runs commands, with memory, sub-agents and MCP
A CLI and 18 skills: the /wish command takes one task in its own worktree, runs the checks and opens a pull request
Codely team skills that run agent work in phases: a plan in a file or GitHub issues, review after each phase and a clean commit
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Shep (this entry) | no | 269 | |
| Claude Squad | no | 8,694 | a terminal app for parallel agent sessions, with no automatic push, pull request or CI watching |
| sudocode | no | 295 | keeps specs and tasks in git as memory for agents, while Shep carries a task through a worktree to a pull request |
README in short
The main page shows a three-command quickstart, a diagram from idea to pull request and a table of supported agents. Tables of flags and commands follow, then a safety section that notes the permission-bypass flags and describes metrics. For contributors there are links to the architecture and a list of good first issues.