Frequently Asked Questions

General

How is Shep different from running an AI agent directly?

Your agent writes code. Shep manages the session: creating the worktree, committing, pushing, opening PRs, watching CI, and retrying failures. The difference is most obvious when you’re running 3-5 features in parallel — Shep keeps them organized and isolated while you focus on what matters.

How is this different from a terminal multiplexer like Superset?

Superset runs multiple agents in parallel tabs. Shep manages the development lifecycle: worktrees, commits, pushes, PRs, CI watch, auto-fix. They’re complementary — use Superset for the execution environment, Shep for the workflow.

Is my code sent anywhere?

Not by Shep. There are no Shep servers, no accounts, no telemetry. Everything Shep tracks lives locally in ~/.shep/ as SQLite. Your code only leaves your machine via the AI agent you configured, under that agent’s own privacy terms.

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 AI agent’s context window, not Shep. If your agent handles your repo well directly, Shep will too. For monorepos, scope features to specific packages with --repo.

Workflow

What happens if the agent writes bad code?

Shep opens a draft PR, not a merged one. Your CI runs. If checks fail, the agent reads the logs and tries to fix (up to 3 retries by default, configurable). If retries are exhausted, the feature pauses and you’re notified. Shep never merges code that fails CI.

What about agent permission / sandbox modes?

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

What’s the spec-driven mode?

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

How do I stop a feature that’s running?

CLI: shep agent stop <id> (find the agent ID with shep feat show <id>). Dashboard: click the Stop button. The worktree is preserved — resume with shep feat resume <id> or take over manually.

Can I run features against multiple repos at once?

Yes. Add the --repo <path> flag, or run shep from inside each repo. The dashboard shows all of them in one view. See Multi-Repo.

Setup

What are the prerequisites?

Node.js 22+
Git
GitHub CLI (gh) — authenticated
An AI agent on PATH (claude, cursor, or gemini)

See Getting Started for the full list.

Where is Shep installed?

If you used npm i -g @shepai/cli, the binary lives wherever your global npm prefix is (often /usr/local/lib/node_modules/). Run which shep to find it.

Where does Shep store its data?

~/.shep/. SQLite database, repo metadata, worktree directory, and logs. It’s all local — no servers, no cloud.

How do I update Shep?


shep upgrade

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

How do I uninstall Shep?


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

That removes the binary and all state. Worktrees not under ~/.shep/ (e.g., feature branches you adopted) are not affected.

Costs

Does Shep cost money?

Shep itself is free and open source (MIT). The AI agent it orchestrates may cost money — that’s between you and your agent provider. Shep doesn’t take a cut, doesn’t proxy requests, and doesn’t see your API keys.

Limitations

Are there things Shep can’t do?

A few:

Cross-repo coordinated changes. Each feature targets one repo. You can run features in parallel across repos, but Shep won’t coordinate them.
Per-feature agent override. You set one agent globally; switching mid-stream is a settings change.
Replacing your CI. Shep watches CI and tries to auto-fix failures, but it doesn’t run tests itself. Your CI is still the source of truth.
Replacing code review. Shep produces draft PRs. Humans review and merge.

What if CI is slow?

Each retry is a CI run. If CI takes 15 minutes and you’re allowing 3 retries, that’s potentially 45 minutes per feature on auto-fix. Tune your CI for speed and Shep gets faster too.

What if the agent loops without fixing?

Shep stops after the configured retry count (default 3). The feature enters Blocked state and waits for you. Provide feedback with shep feat reject <id> --feedback "..." and shep feat resume <id>.