Skip to Content
Core ConceptsHow Shep Works

How Shep Works

You describe a feature. Your agent writes the code in its own git worktree. Shep handles the branch, the commits, the push, the pull request and CI around it. You stay on main the entire time, and you choose how much of that runs without asking you.

The default flow

You describe Agent codes Shep commits Shep pushes Shep opens a feature → in a worktree → the changes → to remote → a draft PR

Then Shep watches CI. If checks fail, the agent reads the logs and pushes a fix (up to 3 attempts by default). Finally the feature waits at the merge gate for you to approve — unless you passed --allow-merge.

What happens when you run shep

  1. A daemon starts in the background. It runs your features, coordinates agents and watches CI. Running shep again just prints its URL.
  2. The web UI opens at localhost:4050  (or the next free port). On first run it walks you through picking an agent and a model.
  3. Your terminal stays yours. Keep coding, run tests, ship hotfixes — Shep doesn’t touch your working directory.

What happens when you create a feature

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

Shep:

  1. Creates a worktree. It syncs main from the remote, then creates a fresh checkout on a new branch under ~/.shep/repos/<repo-hash>/wt/<branch-slug>. Your main checkout is untouched.
  2. Runs your agent. Whichever of the 12 supported agents you configured — Claude Code, Kimi Code, Codex CLI, Copilot CLI, Cursor CLI, Gemini CLI, Cline, or a model provider such as OpenRouter or Ollama. In the web UI you can pick a different agent and model per feature.
  3. The agent codes. Shep streams its output to the web UI, the terminal console and shep feat logs.
  4. Shep snapshots each step. After every step that changes files, Shep takes a git checkpoint you can diff or restore later.
  5. Shep commits, pushes and opens a draft PR — if push and PR are on for this feature.
  6. Shep watches CI. If a check fails, the agent gets the logs and pushes a fix.
  7. Shep waits at the merge gate. Approve it and Shep merges the PR. With --allow-merge it merges on its own once CI is green.

What context the agent gets

The agent starts from your description and any files you attached. On top of that:

  • In spec-driven mode, the Analyze, Requirements, Research and Planning phases write YAML spec files in the worktree (requirements, technical decisions, a plan and a task list) that the implementation follows. See The AI-Native SDLC.
  • Project Memory is durable knowledge agents read at the start of every feature — conventions, architecture decisions, preferred libraries, past CI fixes. Shep updates it after each merged PR, and you can edit it on the Project Memory page. A space can also pull in knowledge such as Notion pages.
  • The agent reads your repo itself, the same way it would if you ran it by hand.

Worktree isolation: the key idea

Each feature gets its own git worktree — a separate checkout of your repo with its own branch.

  • No branch switching. You never leave the branch you’re on.
  • No stashing. Your uncommitted work is never touched.
  • No conflicts. Each feature works in its own directory.
  • True parallelism. Many features run at the same time without seeing each other.

Worktrees share the same .git object store as your main repo, so they take little extra disk space. See Parallel Execution & Worktrees.

Shep doesn’t write code — your agent does

Shep coordinates the agents you already use. It launches the agent, gives it the work, captures its output, and handles the git and CI around it. The code is written by the agent.

That makes Shep agent-agnostic: switch agents whenever you want, use a different agent or model per feature, or move to a new model without changing your workflow. (The one exception is the experimental Shep Harness, a Shep-owned agent loop behind the queryAwareHarness feature flag — see Agent harness.)

Five ways to drive Shep

They all work on the same features and the same database:

SurfaceUse it for
CLI — shep feat new, shep feat approve, …Scripts, quick one-offs. See the CLI Reference.
Web UI — the Control Center, Chat, Agent activityA visual view of every feature, reviews and diffs. See Web Dashboard.
Terminal console — shep tuiWatching and approving everything from the keyboard. See Terminal console.
Programmatic — shep mcp, A2A on the daemonLetting another agent or tool create and steer features. See MCP and A2A.
Messaging — WhatsApp (experimental, off by default)Sending tasks from your phone. See Feature flags.

Local-first, with opt-out usage metrics

Everything Shep tracks — features, settings, history — lives on your machine in ~/.shep/. There are no Shep accounts. Your code only leaves your machine through the agent you configured (under that agent’s own terms) and through git push to your remote.

Shep does send anonymous usage metrics by default: content-free events such as “a feature was created”, with a random install id. It never sends prompts, code, file paths, repo or branch names. Turn it off with shep telemetry off or DO_NOT_TRACK=1. See Usage metrics & privacy.

What’s next