Skip to Content
Getting Started

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 --version should print v22 or higher.
  • Git — git --version.
  • GitHub CLI (gh) — install guide . Run gh auth login once.
  • An agent Shep can drive, already signed in. Any of:
AgentWhat you need
Claude Codeclaude on your PATH
Kimi Codekimi on your PATH
Codex CLIcodex on your PATH
Copilot CLIcopilot on your PATH (needs a Copilot subscription)
Cursor CLIcursor-agent on your PATH — not the cursor editor
Gemini CLIgemini on your PATH
Clinecline on your PATH
OpenRouterAn API key
Together AIAn API key
OllamaA local Ollama server (no key)
LLM ProxyA local OpenAI-compatible proxy (no key)
DemoNothing — 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/cli

Or install globally:

npm install -g @shepai/cli

Prefer 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 shep

Bare 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:

  1. Pick your agent from the list above.
  2. 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).
  3. Shep checks the agent is installed and signed in, and shows the install or login command if it isn’t.
  4. Add a project — choose a folder, or Start from a prompt to create a new app.

First-run setup, step 1: "Choose your agent", a grid of twelve agents: Claude Code, Kimi Code, Codex CLI, Copilot CLI, Cursor CLI, Gemini CLI, Cline, OpenRouter, Together AI, Ollama, LLM Proxy and Demo

First-run setup, step 2: "Pick a model" for Claude Code, a grid of models such as Sonnet 5, Opus 5.5, Haiku 4.5 and Fable 5.1, each with a one-line description

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 configured

Create your first feature

From the terminal:

shep feat new "add a /health endpoint that returns uptime and version" --push --pr

From 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 New Feature drawer: a description, the agent and model picker (Claude Code · Opus 5.5), the reasoning-effort menu open, the Fast/Spec switch, and the Approve, Evidence, Skills and Git toggles

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:

  1. Syncs main from the remote and creates a git worktree on a new branch (e.g. feat/add-health-endpoint).
  2. Runs your agent in that worktree with your description and any files you attached.
  3. Commits the work, pushes the branch, and opens a draft PR.
  4. 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.
  5. Waits at the merge gate. Approve it and Shep merges the PR; pass --allow-merge to 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 --pr

Three 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.

The Agent activity page listing features grouped by state: two need you, one is waiting, two failed with their error messages

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:

FlagEffectDefault
--pushPush the feature branch when implementation completesfrom shep settings workflow
--prOpen a draft pull request (implies --push)from shep settings workflow
--no-prSkip the PR even if your default workflow opens one—
--fastImplement straight from your prompt, no spec phaseson
--no-fastRun the spec-driven phases (see Spec-Driven Mode)—
--allow-prd / --allow-planAuto-approve the requirements or plan gateoff
--allow-mergeAuto-approve the merge gate, so Shep merges once CI is greenoff
--allow-allAuto-approve all three gates. Does not turn on push or PR.off
--model <id>Model for this featureyour 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 cdcurrent 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—
--pendingCreate the feature without starting the agent—
--exploreStart an exploration (prototype) session instead—
--no-rebaseSkip syncing main from the remote first—

Run shep feat new --help for the complete list, or see the CLI Reference.

Where to next