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. The contributor-onboarding agent grooms your issue, drafts acceptance criteria, and welcomes you on first merge.
You're already using AI coding agents. The problem isn't the coding — it's everything around it.
Switching branches. Stashing changes. Watching CI. Assembling PRs. Losing context when you juggle three things at once. One agent session is fine. Five is chaos.
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
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.
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 running in parallel. Zero branch conflicts. You monitor from one place.
Claude Code: claude · Cursor CLI: cursor · Gemini CLI: gemini
If prompted to log in, complete auth first — Shep can't authenticate on your behalf.
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.
Install and run
# Try it instantly — no install needed
npx @shepai/cli
# Or install globally
npm i -g @shepai/cli
# Start Shep — opens the web dashboard at localhost:4050
shep
Your first feature
cd ~/projects/my-app # Any git repo. Shep uses the repo you're in.
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.
Not in a git repo? Shep initializes one for you — git init, creates a branch, and starts working.
Or use the dashboard — describe what you need, configure automation, and hit create:
Go parallel
shep feat new "add stripe payments" --push --pr
shep feat new "add dark mode toggle" --push --pr
shep feat new "refactor auth middleware" --push --pr
# All three run simultaneously in the same repo. Each in its own worktree.
Launch from CLI or dashboard — monitor everything in one place. Open any feature in your IDE, terminal, or file manager with one click:
Or work across multiple repos:
shep feat new "add payments" --repo ~/projects/backend --push --pr
shep feat new "add checkout UI" --repo ~/projects/frontend --push --pr
Manage 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:
How It Works
The default flow is simple: prompt → implement → commit → push → PR.
You describe Agent codes Shep commits Shep pushes Shep opens
a feature → in a worktree → the changes → to remote → a PR
Shep 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).
Configure everything
Every step of the pipeline is configurable. Turn things on or off per feature or set defaults:
| 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-all | Enable all automations | off |
| --model | Choose which AI model to use | agent default |
| --attach | Attach reference files for context | — |
Use shep settings workflow to set your defaults so you don't repeat flags.
Optional: Spec-Driven Development
For complex features, enable the full structured pipeline with requirements, research, and planning phases:
# Disable --fast to get the full pipeline
shep feat new "redesign the payment system" --no-fast --push --pr
This adds approval gates where Shep pauses for your review:
Prompt → Requirements → Research → Plan → Implement → Commit → PR
▲ ▲ ▲
Gate 1: PRD Gate 2: Plan Gate 3: Merge
Each 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.
Run multiple features at once. Each gets its own git worktree — isolated branch, isolated files, zero conflicts. Monitor all of them from one dashboard.
Prompt to PR
One command: shep feat new "do X" --push --pr. Agent implements, Shep commits, pushes, opens a PR. Done.
Agent-Agnostic
Use Claude Code, Cursor CLI, or Gemini CLI. Swap per feature, per repo, anytime. If it runs in a terminal, Shep can orchestrate it.
Web Dashboard + CLI
Two 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.
CI Watch & Auto-Fix
Shep 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.
Everything Configurable
Push, 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.
100% Local
All 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.
Optional: Spec-Driven Development
When 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.
What Happens When Things Go Wrong
CI fails. Shep reads the logs, diagnoses the problem, and pushes a fix. Retries up to 3 times (configurable), then pauses and asks you.
Agent gets stuck. The feature enters a Blocked state. You get notified and can provide feedback or restart from a checkpoint.
You need to stop immediately. Run shep agent stop <id> or hit the stop button in the dashboard. The worktree is preserved — resume or take over manually.
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.
Too many features in flight. Each feature is independent. Stop, pause, or delete any of them without affecting the others.
Trust & Safety
Shep runs entirely on your machine.
| Concern | How Shep handles it |
|---------|-------------------|
| Data stays local | All data in ~/.shep/ as SQLite. Nothing sent to Shep servers — there are none. |
| Agent permissions | Shep runs your agent with permission-bypass flags to avoid blocking the automated pipeline. See Agent Permissions below. |
| Git isolation
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
