Skip to Content
FAQ

Frequently Asked Questions

General

How is Shep different from running an AI agent directly?

Your agent writes code. Shep manages everything around it: creating the worktree, committing, pushing, opening PRs, watching CI and retrying failures, and showing you which agents need you. The difference is most obvious when you’re running 3–5 features in parallel — Shep keeps them organized and isolated while you focus on the ones that need you.

How is this different from a terminal multiplexer like Superset?

Superset runs multiple agents in parallel tabs. Shep manages the work around each agent: worktrees, commits, pushes, PRs, CI watch, auto-fix and approval gates. They’re complementary. Shep’s own terminal console also works inside tmux, Zellij, WezTerm and kitty.

Is my code sent anywhere?

Not by Shep. Your code only leaves your machine through the agent you configured (under that agent’s own terms) and when Shep pushes to your git remote. Everything Shep tracks lives locally in ~/.shep/.

Does Shep collect anything?

Yes — anonymous, content-free usage metrics, on by default and announced on first run. Events like “a feature was created” or “a gate was approved” go to Shep’s PostHog project in the EU, tagged with a random install ID. Shep never sends prompts, code, file paths, repo or branch names, feature titles or error text.

Turn it off with any of:

shep telemetry off # or Settings → Usage metrics in the web UI export DO_NOT_TRACK=1 export SHEP_TELEMETRY_DISABLED=1

It’s always off when the CI environment variable is set. shep telemetry status shows the current state and shep telemetry show shows what would be sent. See Usage metrics & privacy.

Is there a hosted version?

Prefer zero install? app.shep.bot  runs Shep in your browser.

Does this work on a team?

Yes. Shep runs locally for each developer. Features are just branches and PRs — your existing review process applies. Multiple team members can use Shep against the same repo independently.

Does it work on large codebases?

Yes. The bottleneck is your agent’s context window, not Shep. If your agent handles your repo well directly, it will under Shep too. For monorepos, use worktree provisioning to symlink node_modules or warm caches in each new worktree.

Agents and models

Which agents does Shep support?

Twelve: the CLI agents Claude Code (claude), Kimi Code (kimi), Codex CLI (codex), Copilot CLI (copilot), Cursor CLI (cursor-agent), Gemini CLI (gemini) and Cline (cline); the model providers OpenRouter, Together AI, Ollama and LLM Proxy; and a Demo agent that needs nothing. See Agents.

Can I use a different agent for one feature?

Yes. In the web UI’s New Feature drawer, pick the agent and model for that feature. From the CLI, shep feat new uses your default agent, but takes --model and --effort per feature.

Which model does Shep use, and what is reasoning effort?

New installs default to Claude Opus 5.5 (claude-opus-5-5). Change the default with shep settings model or in Settings → Agent, or per feature with --model. Reasoning effort (low, medium, high, xhigh, max) controls how hard the model thinks per turn: set a default with shep settings effort high, or per feature with --effort. Only Claude Code uses it; other agents ignore it. Left unset, the agent uses its own default. See Models & effort.

What about agent permission / sandbox modes?

Shep runs the agent with its permission-bypass flag by default so the run isn’t blocked by interactive prompts. Your protection comes from worktree isolation, draft PRs, the merge gate and your CI pipeline — see Agents.

Workflow

What happens if the agent writes bad code?

Shep opens a draft PR, not a merged one, and waits at the merge gate for you. Your CI runs; if checks fail, the agent reads the logs and tries to fix them (3 attempts by default). If CI is still red after that, the run fails and you can resume or retry it. Shep never auto-merges a PR whose CI failed.

What’s spec-driven mode?

An optional mode that adds requirements, research and planning phases with approval gates before any code is written. Useful for complex features. Enable it per feature with --no-fast. See Spec-Driven Mode.

How many features can run at once?

As many as you start — there’s no limit by default. To cap it, run shep settings workflow --max-parallel 3 (or Settings → Workflow → Max parallel features). Extra features wait as Pending and start automatically as slots free up. See Fleet management.

How do I stop a feature that’s running?

  • CLI: shep ps stop <id> — takes a feature ID or prefix (or an agent run ID).
  • Terminal console: select it in shep tui and press s.
  • Web UI: the Stop button in the feature drawer.

The worktree is preserved. Resume with shep feat resume <id>, or take over manually.

Can I undo what the agent did in one step?

Yes. Shep takes a git checkpoint after every step that changes files. List them with shep feat checkpoints <id>, see what a step changed with shep feat diff <id> --to implement, and roll the worktree back with shep feat restore <id> <step>. The feature drawer’s Checkpoints tab does the same. See Git checkpoints.

Can I work from the terminal instead of the browser?

Yes. shep tui opens a live console of every feature: see what needs you, approve with a, reject with r, stop with s, follow logs, open a shell in a worktree. shep ps lists the daemon and every agent process. See Terminal console.

Can Shep start a brand-new app?

Yes. shep app new "a habit tracker with streaks" creates a new project under ~/.shep/projects/ and runs its first feature — spec-driven by default, or a quick Vite + React + shadcn prototype with --starter vite-shadcn. In the web UI, use Start from a prompt. See Start an app.

Can I run features against multiple repos at once?

Yes. Add the --repo <path> flag, or run shep feat new from inside each repo. The web UI and shep tui show all of them together. See Multi-Repo.

Setup

What are the prerequisites?

  • Node.js 22+
  • Git
  • GitHub CLI (gh) — authenticated
  • An agent: a signed-in CLI (claude, kimi, codex, copilot, cursor-agent, gemini or cline), an OpenRouter or Together AI API key, or a local Ollama / LLM proxy

See Getting Started.

Where is Shep installed?

If you used npm i -g @shepai/cli, the binary lives wherever your global npm prefix is. Run which shep to find it.

Where does Shep store its data?

In ~/.shep/ (or wherever SHEP_HOME points): the settings and features database (~/.shep/data), worktrees under ~/.shep/repos/, apps under ~/.shep/projects/, the daemon log, and agent logs under ~/.shep/logs/.

How do I update Shep?

shep upgrade

Or npm i -g @shepai/cli@latest.

How do I uninstall Shep?

shep stop npm uninstall -g @shepai/cli rm -rf ~/.shep

That removes the binary and all state — including every worktree under ~/.shep/repos/ and every app under ~/.shep/projects/. Push or copy anything you want to keep first. Branches and PRs already on your remote are not affected.

Costs

Does Shep cost money?

Shep itself is free and open source (MIT). The agent it runs may cost money — that’s between you and your agent provider. Shep doesn’t take a cut or proxy your requests. shep usage shows what your features have used: duration, tokens, cost and failures, by phase, agent, feature or model.

Limitations

Are there things Shep can’t do?

A few:

  • Coordinated cross-repo changes. Each feature targets one repo. You can run features in parallel across repos, but Shep won’t sequence them for you.
  • Replacing your CI. Shep watches GitHub Actions and tries to fix failures, but it doesn’t run your tests itself. Your CI is still the source of truth.
  • Replacing code review. Shep opens draft PRs and waits at the merge gate unless you tell it not to.

What if CI is slow?

Each fix attempt is a CI run. If CI takes 15 minutes and you allow 3 attempts, that’s up to 45 minutes per feature. Tune your CI for speed and Shep gets faster too.

What if the agent loops without fixing?

Shep stops after the configured number of fix attempts (3 by default, Settings → CI). The run is marked failed. Look at the logs (shep feat logs <id>), then:

shep feat resume <id> # try that feature again shep fleet retry --failed # retry every failed feature

If the agent is heading the wrong way at an approval gate, reject it with guidance instead: shep feat reject <id> --reason "the failing test is about X — look at file Z".