Ship features 10x faster. Built In Auto: Memory, K8S Agent & Security (SDD+SDLC) . ๐
$ npx -y skills add shep-ai/shep --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Repo: shep-ai/shep
What's inside
Shep is the open-source orchestrator for the autonomous development cycle. It runs parallel AI agents โ Claude Code, Cursor CLI, Gemini CLI, or any agent CLI โ each in its own isolated git worktree, and drives every feature from a one-line description through optional spec gates, implementation, commit, push, CI watching with auto-fix, and a draft pull request. Agent-agnostic, local-first, MIT-licensed.
npx @shepai/cli # try it instantly โ opens the dashboard at localhost:4050
npm i -g @shepai/cli # or install globally
Three commands from zero to an open pull request:
npm i -g @shepai/cli
cd ~/projects/my-app
shep feat new "add a /health endpoint that returns uptime and version" --push --pr
Shep creates a worktree, runs your agent, commits, pushes, and opens a PR. Requires Node.js 22+, Git, the GitHub CLI (gh), and an authenticated agent CLI (claude, cursor, or gemini). Prefer zero install? app.shep.bot runs Shep in your browser, free.
Then go parallel:
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
Three agents, three worktrees, zero branch conflicts โ monitored from one place. One agent session is fine; five is chaos. Shep is the part that keeps it from being chaos.
idea optional spec gates parallel agents shep automates you
"add payments" โ requirements ยท plan โ each in its own โ commit ยท push ยท PR โ review the diff,
(YAML you approve) git worktree CI watch + auto-fix hold the merge button
The default flow is prompt โ implement โ commit โ push โ PR. Your working directory is never touched: every feature lives in its own worktree on its own branch. If CI fails, the agent reads the logs and pushes a fix (3 retries by default, configurable). For complex features, add --no-fast to enable the full spec-driven pipeline โ requirements, research, and a plan as versioned YAML artifacts, with approval gates before any code is written. See the spec-driven development guide.
| Agent | Support |
|---|---|
| Claude Code | Built-in |
| Cursor CLI | Built-in |
| Gemini CLI | Built-in |
| Any terminal agent CLI | Via the generic executor โ if it runs in a terminal, Shep can orchestrate it |
Swap agents per feature, per repo, anytime. No lock-in at the tool layer or the model layer.
A live graph of every repo and feature at localhost:4050 โ real-time status, diff review, interactive chat, one-click open in your IDE. Everything the dashboard does, the CLI does too.
| Flag | What it does | Default |
|---|---|---|
--push | Auto-push after implementation | off |
--pr | Auto-create PR after push | off |
--fast | Skip spec-driven phases, go straight to coding | on |
--allow-merge | Auto-merge the PR after CI passes | off |
--allow-prd / --allow-plan | Auto-approve individual spec gates | off |
--allow-all | Enable all automations | off |
--model | Choose which AI model to use | agent default |
--repo | Target a specific repository | current repo |
--attach | Attach reference files for context | โ |
Set defaults once with shep settings workflow so you stop repeating flags. shep settings agent, shep settings model, and shep settings ide configure the rest.
shep Start daemon + onboarding (first run)
shep feat new <description> Create a new feature
shep feat ls List features
shep feat show <id> Show feature details
shep feat resume <id> Resume a paused feature
shep feat approve <id> Approve current phase (spec-driven mode)
shep feat reject <id> --feedback Reject with feedback (spec-driven mode)
shep feat logs <id> View feature logs
shep agent ls List agent runs
shep agent stop <id> Stop a running agent immediately
shep agent logs <id> View agent logs
shep repo ls List repositories
shep start [--port] Start web daemon (default: 4050)
shep stop Stop the daemon
shep status Show daemon status and metrics
shep settings Launch setup wizard
Full reference: docs/cli/architecture.md
Shep runs entirely on your machine. All data lives in ~/.shep/ as SQLite; your code is sent only to whichever agent you configure, under that agent's own terms. Nothing is sent to Shep servers โ there are none.
| Concern | How Shep handles it |
|---|---|
| Git isolation | Every feature runs in its own worktree branched from main. Your working directory is never modified. |
| Agent mistakes | Output lands as a draft PR. Your CI, linters, and security scanners run before any merge. |
| Review before merge | No code merges without your approval unless you explicitly pass --allow-merge. |
| Credentials | Shep never reads, stores, or transmits your API keys. |
| Audit trail | Every action and state transition is logged โ shep feat logs <id>. |
| Emergency stop | shep agent stop <id> or the dashboard stop button. The worktree is preserved. |
Agent permissions: Shep runs your agent non-interactively, so by default it passes permission-bypass flags (e.g. --dangerously-skip-permissions for Claude Code โ each agent has an equivalent). Your safety net is three layers deep: worktree isolation, draft PRs, and your CI pipeline. The bypass flag is a default, not a requirement โ configure your agent's permission model independently for tighter control. Note that some agents sandbox network access by default; if npm install fails inside a feature, allow the hosts in your agent's settings.
What Shep does not protect you from: if your CI doesn't catch a vulnerability, Shep won't either. Shep is an orchestration layer, not a security scanner.
How is this different from using an AI coding agent directly? Your agent writes the code. Shep manages everything around it: worktrees, commits, pushes, PRs, CI watching, retries. The difference is most obvious at 3-5 features in parallel.
What happens if the agent writes bad code? Shep opens a draft PR and your CI runs. If tests fail, the agent reads the logs and attempts a fix (up to 3 retries, configurable), then pauses and notifies you. Shep never merges code that fails CI.
What happens when an agent gets stuck?
The feature enters a Blocked state. You get notified and can provide feedback, restart from a checkpoint, or take over โ the code is a standard git worktree on a named branch, open it in your IDE at any point.
Does this work on large codebases?
Yes. The practical limit is your agent's context window, not Shep. For monorepos, scope features with --repo.
Can I use this on a team? Shep runs locally per developer. Features are just branches and PRs โ your existing review process applies.
Is my code sent anywhere? Not by Shep. It goes only to the agent you configure, under that agent's privacy terms. Shep stores everything locally.
Not in a git repo yet?
Shep initializes one for you โ git init, a branch, and off it goes.
Clean Architecture, four layers:
| Layer | Responsibility |
|---|---|
| Domain | Business logic, TypeSpec-generated types |
| Application | Use cases, port interfaces |
| Infrastructure | SQLite, LangGraph agents, DI |
| Presentation | CLI, Web UI |
10-minute architecture tour ยท Full architecture docs
Shep is open source and AI-native โ one of its native abilities is helping itself onboard contributors. Clone, run pnpm dev:cli doctor, pick a good first issue, and ship a PR in under 30 minutes.
MIT โ see LICENSE.
.all-contributorsrc
.claude/
agents/
shep-clean-arch-auditor.md
shep-cli-command-creator.md
shep-file-relocator.md
shep-migration-creator.md
shep-port-creator.md
shep-port-extractor.md
shep-storybook-story-creator.md
shep-tsp-field-adder.md
shep-use-case-creator.md
shep-web-route-creator.md
hooks/
format-tsp.sh
rules/
cicd.md
code-quality.md
commit-conventions.md
integrity.md
operational-discipline.md
settings.json
skills/
architecture-reviewer/
SKILL.md
cross-validate-artifacts/
SKILL.md
mermaid-diagrams/
references/
advanced-features.md
architecture-diagrams.md
c4-diagrams.md
class-diagrams.md
erd-diagrams.md
flowcharts.md
sequence-diagrams.md
SKILL.md
react-flow/
references/
custom-edges.md
custom-nodes.md
events.md
viewport.md
SKILL.md
shadcn-ui/
references/
learn.md
official-ui-reference.md
reference.md
ui-reference.md
SKILL.md
shep-kit-commit-pr/
SKILL.md
shep-kit-fast-loop/
SKILL.md
shep-kit-implement/
examples/
validation-report.md
SKILL.md
validation/
architecture.md
completeness.md
consistency.md
shep-kit-merged/
SKILL.md
shep-kit-new-feature/
shep-kit-new-feature-fast/
SKILL.md
examples/
001-sample-feature/
spec.md
scripts/
init-feature.sh
SKILL.md
templates/
data-model.md
feature.yaml
plan.yaml
research.yaml
spec.yaml
tasks.yaml
shep-kit-parallel-task/
scripts/
create-worktree.sh
SKILL.md
shep-kit-plan/
examples/
sample-plan.md
SKILL.md
shep-kit-research/
examples/
sample-research.md
SKILL.md
shep-kit-status/
SKILL.md
shep-ui-component/
SKILL.md
tsp-model/
SKILL.md
vercel-react-best-practices/
AGENTS.md
rules/
advanced-event-handler-refs.md
advanced-init-once.md
advanced-use-latest.md
async-api-routes.md
async-defer-await.md
async-dependencies.md
async-parallel.md
async-suspense-boundaries.md
bundle-barrel-imports.md
bundle-conditional.md
bundle-defer-third-party.md
bundle-dynamic-imports.md
bundle-preload.md
client-event-listeners.md
client-localstorage-schema.md
client-passive-event-listeners.md
client-swr-dedup.md
js-batch-dom-css.md
js-cache-function-results.md
js-cache-property-access.md
js-cache-storage.md
js-combine-iterations.md
js-early-exit.md
js-hoist-regexp.md
js-index-maps.md
js-length-check-first.md
js-min-max-loop.md
js-set-map-lookups.md
js-tosorted-immutable.md
rendering-activity.md
rendering-animate-svg-wrapper.md
rendering-conditional-render.md
rendering-content-visibility.md
rendering-hoist-jsx.md
rendering-hydration-no-flicker.md
rendering-hydration-suppress-warning.md
rendering-svg-precision.md
rendering-usetransition-loading.md
rerender-defer-reads.md
rerender-dependencies.md
rerender-derived-state-no-effect.md
rerender-derived-state.md
rerender-functional-setstate.md
rerender-lazy-state-init.md
rerender-memo-with-default-value.md
rerender-memo.md
rerender-move-effect-to-event.md
rerender-simple-expression-in-memo.md
rerender-transitions.md
rerender-use-ref-transient-values.md
server-after-nonblocking.md
server-auth-actions.md
server-cache-lru.md
server-cache-react.md
server-dedup-props.md
server-parallel-fetching.md
server-serialization.md
SKILL.md
.cursor
.dockerignore
.editorconfig
.github/
ISSUE_TEMPLATE/
bug-report.yml
config.yml
docs-improvement.yml
feature-request.yml
good-first-issue.yml
pr-assets/
product-decisions-no-rationale.png
tech-review-product-tab-no-rationale.png
PULL_REQUEST_TEMPLATE.md
workflows/
agent-request.yml
ci.yml
claude.yml
deploy.yml
docker-publish.yml
generate-good-first-issues.yml
label-by-lane.yml
pr-check.yml
shep-e2e.yml
welcome-first-time-contributor.yml
.gitignore
.gitleaks.toml
.gitleaksignore
.husky/
commit-msg
pre-commit
prepare-commit-msg
.lintstagedrc.mjs
.nvmrc
.prettierignore
.prettierrc
.shep/
evidence/
deployment-booting-story.png
deployment-ready-no-url-story.png
deployment-ready-story.png
feature-node-unit-tests.txt
.storybook/
main.ts
mocks/
app/
actions/
add-injected-skill.ts
add-project-member.ts
add-repository.ts
adopt-agent-session.ts
adopt-branch.ts
adopt-local-directory.ts
agent-graph.ts
agent-prompts.ts
agent-questions.ts
agent-setup-flag.ts
approve-feature.ts
archive-feature.ts
aspm-ingest.ts
aspm-scan.ts
bedrock.action.ts
bulk-update-work-items.ts
check-agent-auth.ts
check-agent-tool.ts
check-all-agents-status.ts
check-tool-status.ts
compose-user-input.ts
configure-supervisor.ts
create-application.ts
create-feature-from-remote.ts
create-feature.ts
create-pm-project.ts
create-project-and-feature.ts
create-project-folder.ts
create-work-item-relation.ts
create-work-item.ts
custom-agents.ts
delete-application.ts
delete-feature.ts
delete-pm-project.ts
delete-repository.ts
delete-work-item-relation.ts
deploy-application.ts
deploy-feature.ts
deploy-repository.ts
enable-bedrock.action.ts
get-all-agent-models.ts
get-application-debug-prompt.ts
get-available-terminals.ts
get-branch-sync-status.ts
get-cycle-burndown.ts
get-default-agent-and-model.ts
get-deployment-logs.ts
get-deployment-status.ts
get-feature-artifact.ts
get-feature-drawer-data.ts
get-feature-metadata.ts
get-feature-phase-timings.ts
get-feature-plan.ts
get-git-log.ts
get-graph-data.ts
get-merge-review-data.ts
get-module-progress.ts
get-project-breakdown.ts
get-research-artifact.ts
get-supported-models.ts
get-viewer-permission.ts
get-workflow-defaults.ts
get-workflow-history.ts
github-integration.ts
global-search.ts
import-github-repository.ts
import-local-repositories.ts
list-branches.ts
list-cycles.ts
list-deployments.ts
list-github-organizations.ts
list-github-repositories.ts
list-modules.ts
list-project-relations.ts
list-sdlc-board.ts
list-work-item-relations.ts
list-work-items.ts
list-workflows.ts
load-curated-issues.ts
load-settings.ts
manage-ai-analytics.ts
manage-attachments.ts
manage-cycles.ts
manage-epics.ts
manage-import-export.ts
manage-intake.ts
manage-labels.ts
manage-modules.ts
manage-notifications.ts
manage-pages.ts
manage-project-memory.ts
manage-time-entries.ts
manage-work-item-states.ts
messaging.ts
open-directory.ts
open-folder.ts
open-ide.ts
open-shell.ts
pick-folder.ts
rebase-feature.ts
reject-feature.ts
remove-injected-skill.ts
remove-project-member.ts
reorder-sdlc-task.ts
reparent-feature.ts
resume-feature.ts
run-doctor.ts
security.ts
session-tree.ts
start-feature.ts
stop-deployment.ts
stop-feature.ts
sync-repository.ts
toggle-workflow.ts
trigger-review.ts
trigger-workflow.ts
unarchive-feature.ts
update-agent-and-model.ts
update-feature-pinned-config.ts
update-model.ts
update-pm-project.ts
update-project-member-role.ts
update-sdlc-subtask-status.ts
update-sdlc-task-status.ts
update-settings.ts
update-work-item.ts
components/
features/
chat/
ChatTab.tsx
next-image-mock.tsx
next-link-mock.tsx
next-navigation-mock.ts
preview.tsx
AGENTS.md
apis/
json-schema/
AcceptanceCriteria.yaml
ActionDispositionEntry.yaml
ActionItem.yaml
ActivityEntry.yaml
AgentAuthMethod.yaml
AgentConfig.yaml
AgentDefinition.yaml
AgentFeature.yaml
AgentGraphOverride.yaml
AgentInstance.yaml
AgentMessage.yaml
AgentMessageKind.yaml
AgentPromptOverride.yaml
AgentQuestion.yaml
AgentQuestionAnswerer.yaml
AgentQuestionKind.yaml
AgentQuestionStatus.yaml
AgentRun.yaml
AgentRunEvent.yaml
AgentRunStatus.yaml
AgentSession.yaml
AgentSessionMessage.yaml
AgentStatus.yaml
AgentType.yaml
AiChangeRiskSignal.yaml
AiSignalState.yaml
AiSignalType.yaml
AnalyzeRepoTimeouts.yaml
ApiAsset.yaml
Application.yaml
ApplicationStatus.yaml
ApplicationUpdatePayload.yaml
ApprovalGateDefaults.yaml
ApprovalGates.yaml
Artifact.yaml
ArtifactCategory.yaml
ArtifactFormat.yaml
ArtifactState.yaml
AskRequest.yaml
AskResponse.yaml
AssetType.yaml
Attachment.yaml
AuditableEntity.yaml
AuditAction.yaml
BaseEntity.yaml
BedrockHealth.yaml
BedrockLifecycleAction.yaml
BedrockMemoryFile.yaml
BedrockMemorySnapshot.yaml
BedrockTargetKind.yaml
BedrockTargetRef.yaml
BedrockTierStatus.yaml
BuildMode.yaml
BusinessUnit.yaml
CampaignStatus.yaml
CanonicalSeverity.yaml
... 1600 moreShowing a partial view of a very large repo.
FAQ
shep is a Claude Code plugin with 18 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes architecture-reviewer, cross-validate-artifacts, mermaid-diagrams. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.