{"id":47629330,"url":"https://github.com/shep-ai/shep","last_synced_at":"2026-04-14T23:10:26.417Z","repository":{"id":337682855,"uuid":"1147536369","full_name":"shep-ai/shep","owner":"shep-ai","description":"Run Claude Code, Cursor, and Gemini CLI coding agents in parallel, each in its own isolated workspace","archived":false,"fork":false,"pushed_at":"2026-04-04T09:48:13.000Z","size":72542,"stargazers_count":99,"open_issues_count":36,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T11:40:04.780Z","etag":null,"topics":["agentic-ai","agentic-workflows","ai","ai-agents","ai-code-generation","ai-coding-tools","ai-native","ai-orchestration","autonomous-agents","claude-code","cli","cursor","developer-tools","devtools","llm","nextjs","productivity","sdlc-enforced","terminal","typescript"],"latest_commit_sha":null,"homepage":"https://shep-ai.github.io/shep/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shep-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING-AGENTS.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-01T22:23:54.000Z","updated_at":"2026-04-04T11:30:22.000Z","dependencies_parsed_at":"2026-03-12T13:04:19.231Z","dependency_job_id":null,"html_url":"https://github.com/shep-ai/shep","commit_stats":null,"previous_names":["shep-ai/cli","shep-ai/shep"],"tags_count":282,"template":false,"template_full_name":null,"purl":"pkg:github/shep-ai/shep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shep-ai%2Fshep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shep-ai%2Fshep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shep-ai%2Fshep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shep-ai%2Fshep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shep-ai","download_url":"https://codeload.github.com/shep-ai/shep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shep-ai%2Fshep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31434624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T08:13:15.228Z","status":"ssl_error","status_checked_at":"2026-04-05T08:13:11.839Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-workflows","ai","ai-agents","ai-code-generation","ai-coding-tools","ai-native","ai-orchestration","autonomous-agents","claude-code","cli","cursor","developer-tools","devtools","llm","nextjs","productivity","sdlc-enforced","terminal","typescript"],"created_at":"2026-04-01T23:06:47.899Z","updated_at":"2026-04-07T13:01:25.745Z","avatar_url":"https://github.com/shep-ai.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"src/presentation/web/public/favicon-light.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"src/presentation/web/public/favicon-dark.svg\"\u003e\n    \u003cimg src=\"src/presentation/web/public/favicon-light.svg\" alt=\"Shep logo\" width=\"28\" valign=\"middle\" /\u003e\n  \u003c/picture\u003e\n  Shep\n\u003c/h1\u003e\n\n### Run multiple AI agents in parallel. Each in its own worktree.\n\n_Manage 10 features at once — isolated branches, automatic commits, CI watching, and PRs — from a dashboard or the terminal._\n\n[![CI](https://github.com/shep-ai/shep/actions/workflows/ci.yml/badge.svg)](https://github.com/shep-ai/shep/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@shepai/cli.svg?color=cb3837\u0026logo=npm)](https://www.npmjs.com/package/@shepai/cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Features](#features) · [Trust \u0026 Safety](#trust--safety) · [FAQ](#faq)\n\n\u003cbr /\u003e\n\n\u003cimg src=\"docs/screenshots/cover.png\" alt=\"Shep — Parallel AI Agent Sessions\" width=\"900\" /\u003e\n\n\u003c/div\u003e\n\n---\n\n## Why Shep?\n\nYou're already using AI coding agents. The problem isn't the coding — it's everything around it.\n\nSwitching branches. Stashing changes. Watching CI. Assembling PRs. Losing context when you juggle three things at once. One agent session is fine. Five is chaos.\n\n**Shep gives each feature its own isolated world** — a git worktree, a branch, an agent session — and handles the boring parts: committing, pushing, opening PRs, watching CI, and fixing failures. You manage it all from one dashboard or the CLI.\n\n```bash\nshep feat new \"add stripe payments\" --push --pr\nshep feat new \"add dark mode toggle\" --push --pr\nshep feat new \"fix login redirect bug\" --push --pr\n# Three agents running in parallel. Zero branch conflicts. You monitor from one place.\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 22+** and **npm** (or install via `nvm`)\n- **Git** and **GitHub CLI** (`gh`) — [install guide](https://cli.github.com/)\n- **An AI coding agent**, authenticated and ready:\n  - **Claude Code**: `claude` · **Cursor CLI**: `cursor` · **Gemini CLI**: `gemini`\n  - If prompted to log in, complete auth first — Shep can't authenticate on your behalf.\n\n\u003e **Sandbox mode note:** Some agents restrict network access by default. If operations like `npm install` fail, configure allowed hosts in your agent's settings or disable sandbox for Shep features. See [Agent Permissions](#agent-permissions).\n\n### Install and run\n\n```bash\n# Try it instantly — no install needed\nnpx @shepai/cli\n\n# Or install globally\nnpm i -g @shepai/cli\n\n# Start Shep — opens the web dashboard at localhost:4050\nshep\n```\n\n### Your first feature\n\n```bash\ncd ~/projects/my-app        # Any git repo. Shep uses the repo you're in.\nshep feat new \"add a /health endpoint that returns uptime and version\" --push --pr\n\n# Shep creates a worktree, runs your agent, commits, pushes, and opens a PR.\n```\n\nNot in a git repo? Shep initializes one for you — `git init`, creates a branch, and starts working.\n\nOr use the dashboard — describe what you need, configure automation, and hit create:\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/screenshots/create-feature.png\" alt=\"Shep — Create Feature with configurable automation\" width=\"900\" /\u003e\n\u003c/div\u003e\n\n### Go parallel\n\n```bash\nshep feat new \"add stripe payments\" --push --pr\nshep feat new \"add dark mode toggle\" --push --pr\nshep feat new \"refactor auth middleware\" --push --pr\n# All three run simultaneously in the same repo. Each in its own worktree.\n```\n\nLaunch from CLI or dashboard — monitor everything in one place. Open any feature in your IDE, terminal, or file manager with one click:\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/screenshots/parallel-features.png\" alt=\"Shep — Three features running in parallel\" width=\"900\" /\u003e\n\u003c/div\u003e\n\nOr work across multiple repos:\n\n```bash\nshep feat new \"add payments\" --repo ~/projects/backend --push --pr\nshep feat new \"add checkout UI\" --repo ~/projects/frontend --push --pr\n```\n\nManage multiple repos from one dashboard. Start a local dev server per feature, chat with Shep for questions or HTML previews — all without leaving the UI:\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/screenshots/multi-repo.png\" alt=\"Shep — Multiple repos with global chat and HTML preview\" width=\"900\" /\u003e\n\u003c/div\u003e\n\n---\n\n## How It Works\n\nThe default flow is simple: **prompt → implement → commit → push → PR**.\n\n```\n You describe       Agent codes         Shep commits        Shep pushes         Shep opens\n a feature    →     in a worktree  →    the changes    →    to remote      →    a PR\n```\n\nShep creates an isolated git worktree, hands your prompt to the agent, and handles everything after: committing, pushing, and opening a PR. If CI fails, Shep reads the logs, fixes the issue, and retries (configurable).\n\n### Configure everything\n\nEvery step of the pipeline is configurable. Turn things on or off per feature or set defaults:\n\n| Flag | What it does | Default |\n|------|-------------|---------|\n| `--push` | Auto-push after implementation | off |\n| `--pr` | Auto-create PR after push | off |\n| `--fast` | Skip spec-driven phases, go straight to coding | on |\n| `--allow-merge` | Auto-merge the PR after CI passes | off |\n| `--allow-all` | Enable all automations | off |\n| `--model` | Choose which AI model to use | agent default |\n| `--attach` | Attach reference files for context | — |\n\nUse `shep settings workflow` to set your defaults so you don't repeat flags.\n\n### Optional: Spec-Driven Development\n\nFor complex features, enable the full structured pipeline with requirements, research, and planning phases:\n\n```bash\n# Disable --fast to get the full pipeline\nshep feat new \"redesign the payment system\" --no-fast --push --pr\n```\n\nThis adds **approval gates** where Shep pauses for your review:\n\n```\n Prompt  →  Requirements  →  Research  →  Plan  →  Implement  →  Commit  →  PR\n                 ▲                          ▲                                ▲\n             Gate 1: PRD              Gate 2: Plan                    Gate 3: Merge\n```\n\nEach gate produces a YAML artifact you can read, edit, and approve before the agent continues. Use `--allow-prd` and `--allow-plan` to auto-approve individual gates, or keep them manual for full control.\n\n\u003e **[Spec-Driven Development guide →](./docs/development/spec-driven-workflow.md)**\n\n---\n\n## Features\n\n### Parallel Sessions\n\nRun multiple features at once. Each gets its own git worktree — isolated branch, isolated files, zero conflicts. Monitor all of them from one dashboard.\n\n### Prompt to PR\n\nOne command: `shep feat new \"do X\" --push --pr`. Agent implements, Shep commits, pushes, opens a PR. Done.\n\n### Agent-Agnostic\n\nUse Claude Code, Cursor CLI, or Gemini CLI. Swap per feature, per repo, anytime. If it runs in a terminal, Shep can orchestrate it.\n\n### Web Dashboard + CLI\n\nTwo ways to manage everything. The dashboard at `localhost:4050` shows a visual graph of all repos and features with real-time status, diff review, and interactive chat. The CLI gives you the same control from the terminal.\n\n### CI Watch \u0026 Auto-Fix\n\nShep watches your CI pipeline after push. If it fails, the agent reads the logs, diagnoses the problem, and pushes a fix. Retries are configurable (default: 3). Works best when CI produces clear error messages.\n\n### Everything Configurable\n\nPush, PR, merge, CI watch, CI fix retries, timeouts, model selection, agent type — configure per feature with flags or set global defaults with `shep settings`. Nothing is hardcoded.\n\n### 100% Local\n\nAll data lives in `~/.shep/` as SQLite. No cloud, no account, no tracking. Your code is only sent to whichever AI agent you configure, under that agent's own terms.\n\n### Optional: Spec-Driven Development\n\nWhen you need more structure — requirements, technical research, implementation plans with approval gates. Produces versioned YAML artifacts you review before any code is written. Enable per feature with `--no-fast`.\n\n---\n\n## What Happens When Things Go Wrong\n\n- **CI fails.** Shep reads the logs, diagnoses the problem, and pushes a fix. Retries up to 3 times (configurable), then pauses and asks you.\n- **Agent gets stuck.** The feature enters a `Blocked` state. You get notified and can provide feedback or restart from a checkpoint.\n- **You need to stop immediately.** Run `shep agent stop \u003cid\u003e` or hit the stop button in the dashboard. The worktree is preserved — resume or take over manually.\n- **You want to take over.** The code lives in a standard git worktree on a named branch. Open it in your IDE at any point.\n- **Too many features in flight.** Each feature is independent. Stop, pause, or delete any of them without affecting the others.\n\n---\n\n## Trust \u0026 Safety\n\nShep runs entirely on your machine.\n\n| Concern | How Shep handles it |\n|---------|-------------------|\n| **Data stays local** | All data in `~/.shep/` as SQLite. Nothing sent to Shep servers — there are none. |\n| **Agent permissions** | Shep runs your agent with permission-bypass flags to avoid blocking the automated pipeline. See [Agent Permissions](#agent-permissions) below. |\n| **Git isolation** | Every feature runs in its own worktree branched from main. Your working directory is never modified. |\n| **No credential access** | Shep never reads, stores, or transmits your API keys. |\n| **Agent mistakes** | Shep creates a draft PR. Your CI, linters, and security scanners run before any merge. Shep does not merge code that fails CI. |\n| **Review before merge** | Unless you pass `--allow-merge`, no code is merged without your approval. |\n| **Full audit trail** | Every action and state transition is logged. View with `shep feat logs \u003cid\u003e`. |\n\n### Agent Permissions\n\nShep runs your agent non-interactively — it can't pause for \"allow this command?\" prompts mid-pipeline. By default, it passes permission-bypass flags (e.g., `--dangerously-skip-permissions` for Claude Code — each agent has an equivalent).\n\n**Your safety net is three layers deep:**\n1. **Worktree isolation** — the agent works on a copy, not your checkout\n2. **Draft PRs** — you review the diff before anything is merged\n3. **CI pipeline** — your tests, linters, and security scanners run before merge\n\nThe skip-permissions flag is a default, not a requirement. Configure your agent's permission model independently if you need tighter control.\n\n**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.\n\n---\n\n## Supported Agents \u0026 Tools\n\n| Category | Supported |\n|----------|-----------|\n| **AI Agents** | Claude Code, Cursor CLI, Gemini CLI |\n| **IDEs** | VS Code, Cursor, Zed, Windsurf, and more |\n| **Required** | Git, GitHub CLI (`gh`) |\n\n---\n\n## CLI Reference\n\n### Core Commands\n\n```\nshep                              Start daemon + onboarding (first run)\nshep feat new \u003cdescription\u003e       Create a new feature\n      [--push] [--pr] [--fast] [--model] [--attach]\n      [--allow-prd] [--allow-plan] [--allow-merge] [--allow-all]\nshep feat ls                      List features\nshep feat show \u003cid\u003e               Show feature details\nshep feat resume \u003cid\u003e             Resume a paused feature\nshep feat approve \u003cid\u003e            Approve current phase (spec-driven mode)\nshep feat reject \u003cid\u003e --feedback  Reject with feedback (spec-driven mode)\nshep feat logs \u003cid\u003e               View feature logs\n```\n\n### Stopping a Feature\n\n```\nshep agent stop \u003cid\u003e              Stop a running agent immediately\nshep agent ls                     Find the agent ID for a feature\n```\n\nThe web dashboard also has a stop button on every in-progress feature.\n\n### Daemon \u0026 Dashboard\n\n```\nshep start [--port]               Start web daemon (default: 4050)\nshep stop                         Stop the daemon\nshep status                       Show daemon status and metrics\nshep ui                           Start web UI in foreground\n```\n\n### Settings \u0026 Configuration\n\n```\nshep settings                     Launch setup wizard\nshep settings workflow            Configure default flags (push, pr, ci watch, etc.)\nshep settings agent               Configure AI coding agent\nshep settings ide                 Configure IDE\nshep settings model               Configure default model\n```\n\n### Agent \u0026 Repo Management\n\n```\nshep agent ls                     List agent runs\nshep agent stop \u003cid\u003e              Stop a running agent\nshep agent logs \u003cid\u003e              View agent logs\nshep repo ls                      List repositories\n```\n\n\u003e **[Full CLI reference →](./docs/cli/architecture.md)**\n\n---\n\n## FAQ\n\n**How is this different from just using an AI coding agent directly?**\n\nYour agent writes the code. Shep manages the session: creating the worktree, committing, pushing, opening PRs, watching CI, and retrying failures. The difference is most obvious when you're running 3-5 features in parallel — Shep keeps them organized and isolated while you focus on what matters.\n\n**How is this different from Superset?**\n\nSuperset is a terminal multiplexer for agents — it runs them in parallel tabs. Shep manages the development lifecycle: worktrees, commits, pushes, PRs, CI. They're complementary. Use Superset for the execution environment, Shep for the workflow.\n\n**What happens if the agent writes bad code?**\n\nShep creates a draft PR. Your CI runs. If tests fail, the agent reads the logs and attempts a fix (up to 3 retries, configurable). If that fails, the feature pauses and you're notified. The agent never merges code that fails CI.\n\n**What about agent sandbox / permission modes?**\n\nShep runs the agent with permission-bypass flags by default so the pipeline isn't blocked by interactive prompts. Your protection is worktree isolation, draft PRs, and your CI pipeline. See [Agent Permissions](#agent-permissions).\n\n**Does this work on large codebases?**\n\nYes. The practical limit is the underlying agent's context window, not Shep. If your agent handles your repo well directly, Shep will too. For monorepos, scope features to specific packages with `--repo`.\n\n**Can I use this on a team?**\n\nShep runs locally on your git repo. Multiple team members can run Shep independently. Features are just branches and PRs — your existing review process applies.\n\n**Is my code sent anywhere?**\n\nNot by Shep. Your code is sent to whichever AI agent you configure, under that agent's own privacy terms. Shep stores everything locally and makes no network calls.\n\n**What's the spec-driven mode?**\n\nAn optional structured pipeline that adds requirements, research, and planning phases with approval gates before any code is written. Useful for complex features where you want to review the approach first. Enable with `--no-fast`. [Learn more →](./docs/development/spec-driven-workflow.md)\n\n**How do I stop a feature that's running?**\n\nCLI: `shep agent stop \u003cid\u003e`. Dashboard: click the stop button. The worktree is preserved — resume with `shep feat resume \u003cid\u003e` or work on it manually.\n\n---\n\n## Architecture\n\nShep follows Clean Architecture with four layers. For contributors and the curious:\n\n| Layer | Responsibility |\n|-------|---------------|\n| **Domain** | Business logic, TypeSpec-generated types |\n| **Application** | Use cases, port interfaces |\n| **Infrastructure** | SQLite, LangGraph agents, DI |\n| **Presentation** | CLI, Web UI |\n\n\u003e **[Full architecture docs →](./docs/architecture/overview.md)**\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for humans and [CONTRIBUTING-AGENTS.md](./CONTRIBUTING-AGENTS.md) for AI agents.\n\n---\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=shep-ai%2Fshep\u0026type=timeline\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/image?repos=shep-ai/shep\u0026type=timeline\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/image?repos=shep-ai/shep\u0026type=timeline\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/image?repos=shep-ai/shep\u0026type=timeline\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshep-ai%2Fshep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshep-ai%2Fshep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshep-ai%2Fshep/lists"}