Getting Started
After this guide you’ll have Shep installed, your agent configured, your first feature implemented, and a draft PR open — typically in under five minutes.
Prerequisites
- Node.js 22+ —
node --versionshould printv22or higher. - Git —
git --version. - GitHub CLI (
gh) — install guide . Rungh auth loginonce. - An agent Shep can drive, already signed in. Any of:
| Agent | What you need |
|---|---|
| Claude Code | claude on your PATH |
| Kimi Code | kimi on your PATH |
| Codex CLI | codex on your PATH |
| Copilot CLI | copilot on your PATH (needs a Copilot subscription) |
| Cursor CLI | cursor-agent on your PATH — not the cursor editor |
| Gemini CLI | gemini on your PATH |
| Cline | cline on your PATH |
| OpenRouter | An API key |
| Together AI | An API key |
| Ollama | A local Ollama server (no key) |
| LLM Proxy | A local OpenAI-compatible proxy (no key) |
| Demo | Nothing — scripted responses for trying Shep out |
If your agent’s CLI asks you to log in, do that yourself first. Shep reuses the session you already have. See Agents for details on each one.
Install Shep
The fastest way is npx:
npx @shepai/cliOr install globally:
npm install -g @shepai/cliPrefer zero install? app.shep.bot runs Shep in your browser.
Start Shep
From any folder — Shep will git init it if needed:
cd your-project
shepBare shep is the same as shep start. It starts the Shep daemon in the background, prints the URL and opens it in your browser — localhost:4050 by default. If 4050 is busy, Shep picks the next free port. If Shep is already running, shep just prints the existing URL.
First-run setup happens in the browser
The first time you open Shep, the Control Center walks you through setup:
- Pick your agent from the list above.
- Pick its default model. Only models that agent supports are offered. On a new install the default model is Claude Opus 5.5 (
claude-opus-5-5). - Shep checks the agent is installed and signed in, and shows the install or login command if it isn’t.
- Add a project — choose a folder, or Start from a prompt to create a new app.


The first run also shows a short notice that Shep collects anonymous usage metrics, with a Turn off button. See Usage metrics & privacy.
Your choices are saved in Shep’s settings database at ~/.shep/data and apply to every repo until you change them.
Prefer the terminal? The same setup is available as commands:
shep settings # interactive wizard: agent, IDE, workflow
shep settings agent --agent claude-code --auth session
shep settings model # pick the default model
shep settings show # check what is configuredCreate your first feature
From the terminal:
shep feat new "add a /health endpoint that returns uptime and version" --push --prFrom the web UI: on the Control Center, click + New on your repository (or the round + button), describe what you want, and click Create Feature. You can also ask for it in Chat.

The drawer lets you pick the agent and model for this feature, the reasoning effort, Fast or Spec mode, a parent feature, attachments, and which gates and git steps to automate. Cmd/Ctrl + Enter submits.
Either way, Shep:
- Syncs
mainfrom the remote and creates a git worktree on a new branch (e.g.feat/add-health-endpoint). - Runs your agent in that worktree with your description and any files you attached.
- Commits the work, pushes the branch, and opens a draft PR.
- Watches CI. If a check fails, the agent reads the logs and pushes a fix — up to 3 attempts by default. If they all fail, the run is marked failed and you can resume it.
- Waits at the merge gate. Approve it and Shep merges the PR; pass
--allow-mergeto skip the wait once CI is green.
You stay on main the whole time.
Go parallel
Each feature runs in its own worktree, so they can’t conflict:
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 --prThree agents, three worktrees, three draft PRs. Follow them with:
shep feat ls # every feature and its phase
shep feat status <id> # what one agent is doing, and why
shep tui # a live console of every feature, in your terminal…or on the Agent activity page in the browser.

By default there is no limit on how many features run at once. Set one with shep settings workflow --max-parallel 3; extra features then wait in a queue as Pending and start as slots free up. See Fleet management.
Useful flags
The most-used shep feat new flags:
| Flag | Effect | Default |
|---|---|---|
--push | Push the feature branch when implementation completes | from shep settings workflow |
--pr | Open a draft pull request (implies --push) | from shep settings workflow |
--no-pr | Skip the PR even if your default workflow opens one | — |
--fast | Implement straight from your prompt, no spec phases | on |
--no-fast | Run the spec-driven phases (see Spec-Driven Mode) | — |
--allow-prd / --allow-plan | Auto-approve the requirements or plan gate | off |
--allow-merge | Auto-approve the merge gate, so Shep merges once CI is green | off |
--allow-all | Auto-approve all three gates. Does not turn on push or PR. | off |
--model <id> | Model for this feature | your default model (claude-opus-5-5 on new installs) |
--effort <level> | Reasoning effort: low, medium, high, xhigh, max. Only Claude Code uses it. | your default |
--attach <path> | Attach a file (design, example, spec). Repeatable. | — |
--repo <path> | Run against another local repo without cd | current folder |
--remote <url> | Clone (or fork) a GitHub repo, then create the feature there | — |
--parent <id> | Make this a child feature that starts when its parent lands | — |
--pending | Create the feature without starting the agent | — |
--explore | Start an exploration (prototype) session instead | — |
--no-rebase | Skip syncing main from the remote first | — |
Run shep feat new --help for the complete list, or see the CLI Reference.
Where to next
- Tutorials — step-by-step tasks, starting with from zero to a merged PR.
- Your First Feature — a slower walkthrough, from repo to merged PR.
- How Shep Works — the worktree model in plain English.
- Web Dashboard — the pages and panels of the web UI.
- Terminal console —
shep tuifor keyboard-driven work. - Configuration — set defaults so you stop typing the same flags.
- Troubleshooting — common setup hiccups.