Skip to Content
GuidesCustom Agents

Custom Agents

Shep is agent-agnostic. It coordinates AI coding tools rather than being tied to one. You pick which agent it launches, and you can switch any time.

Available agents

AgentStatusBinary on PATHNotes
Claude CodeRecommendedclaudeBest support for the full Shep feature set.
Cursor CLIAvailablecursorGood fit for teams already on Cursor.
Gemini CLIAvailablegeminiGoogle’s coding agent. Newer in Shep.

You authenticate the agent yourself, before running Shep. The check is simple: if claude (or cursor / gemini) works in your terminal, Shep can use it.

Switching agents

shep settings agent

The wizard lists detected agents on your PATH and asks which to use. Your selection persists globally.

You can also set it directly:

shep settings agent --agent claude-code
shep settings agent --agent cursor
shep settings agent --agent gemini

How agents work with Shep

When you create a feature, Shep:

  1. Creates a worktree and base branch.
  2. Builds a prompt for the agent: your description + the codebase analysis + any attached reference files.
  3. Launches your configured agent with the prompt.
  4. Streams the agent’s output to the dashboard.
  5. Commits the agent’s changes, pushes, and opens the PR.
  6. Watches CI; if it fails, sends the logs back to the agent for a fix.

You interact with Shep. Shep interacts with the agent.

Permissions and sandboxing

Agents run non-interactively under Shep — they can’t pause and ask “should I run this command?” mid-pipeline. By default Shep passes permission-bypass flags so the pipeline doesn’t get blocked.

Your safety net is three layers deep:

  1. Worktree isolation. The agent works on a copy, not your checkout.
  2. Draft PRs. Nothing is merged without your review.
  3. Your CI pipeline. Tests, linters, and security scanners run before merge.

The skip-permissions default isn’t a requirement — configure your agent’s permission model independently if you want tighter control. See shep settings workflow for related toggles.

Tips per agent

Claude Code

  • An active Claude session is enough — Shep doesn’t need API keys.
  • Claude handles complex multi-step work well. Use spec-driven mode (--no-fast) for large features.
  • Use --inject-skills to make Claude Code skills available during the run.

Cursor CLI

  • The cursor binary is installed with Cursor. Make sure it’s on your PATH.
  • Cursor reads your .cursorrules file when working — keep that current.
  • Token-based auth: ensure you’ve signed into Cursor and the CLI knows your account.

Gemini CLI

  • The gemini binary on PATH. Authenticate via gcloud or whatever your Gemini CLI uses.
  • Newer in Shep — for first runs, prefer fast mode and small features to validate setup.

Capability matrix

Not every agent supports every Shep capability equally well:

CapabilityClaude CodeCursor CLIGemini CLI
Feature implementation✓✓✓
Spec-driven pipeline✓✓Partial
Multi-file edits✓✓✓
Approval gates per task✓✓Partial
Streaming output✓PartialPartial
Session auth (no API key)✓PartialDepends

For new projects, start with Claude Code unless you have a specific reason to use another. Switch later — shep settings agent is one command.

Per-feature agent override

There’s no per-feature --agent flag. To run a single feature with a different agent, change the global setting, run the feature, then change it back. Most users pick one agent and stick with it.

Multi-RepoExperimental Features