Skip to Content
GuidesAgents

Agents

Shep is agent-agnostic. It drives the coding agents you already use instead of shipping its own. Pick a default agent, override it per feature, and switch any time.

Supported agents

CLI agents — Shep runs the agent’s own command-line tool. Install it and sign in first.

AgentBinary on PATH--agent valueNotes
Claude Codeclaudeclaude-codeThe only agent that receives reasoning effort.
Kimi Codekimikimi-codeMoonshot AI’s CLI. --model selects a model key from ~/.kimi/config.toml.
Codex CLIcodexcodex-cliOpenAI’s Codex CLI.
Copilot CLIcopilotcopilot-cliNeeds a GitHub Copilot subscription. Session auth only.
Cursor CLIcursor-agentcursorThe binary is cursor-agent, not the cursor editor. See cursor.com/cli .
Gemini CLIgeminigemini-cliGoogle’s Gemini CLI.
ClineclineclineMulti-provider agent with full tool use.

Model providers — no binary. Shep calls the provider’s API directly.

Provider--agent valueWhat you need
OpenRouteropenrouterAn OpenRouter API key (token auth).
Together AItogether-aiA Together AI API key (token auth).
OllamaollamaA local Ollama server. Defaults to http://localhost:11434/v1; put a different base URL in the token field. No key.
LLM ProxyllmproxyA local OpenAI-compatible proxy. Defaults to http://localhost:4000/v1; put a different base URL in the token field. No key.

Demo (dev) needs nothing: it returns scripted responses so you can try Shep without an agent or an API key.

An experimental Shep Harness agent also exists. It only appears when the queryAwareHarness feature flag is on — see Agent harness.

Authentication

Each agent uses one of two methods:

  • Session — Shep reuses the login you already have in the agent’s CLI. If claude (or kimi, codex, cursor-agent, …) works in your terminal, Shep can use it. Shep stores nothing but the choice.
  • Token — you give Shep an API key. It’s stored in Shep’s local settings database (~/.shep/data) as plain text and passed only to the provider you picked. OpenRouter and Together AI require a token; Copilot CLI supports session only. For Ollama and LLM Proxy the “token” field holds the server’s base URL instead.

Choosing your default agent

The first time you open Shep, the browser asks you to pick an agent and a model, then checks that the agent is installed and signed in — and shows the install or login command if not. You can change it later in Settings → Agent.

Settings → Agent in the web UI: Agent & Model set to Claude Code · Opus 5.5, Reasoning effort set to Agent default, and Auth Method set to Session

From the terminal:

shep settings agent # interactive picker shep settings agent --agent claude-code --auth session shep settings agent --agent cursor --auth session shep settings agent --agent gemini-cli --auth session shep settings agent --agent openrouter --auth token --token sk-or-… shep settings agent --agent ollama --auth token --token http://gpu-box:11434/v1 shep settings agent --agent dev # Demo agent

--auth is required whenever you pass --agent (except for dev). Then pick the default model with shep settings model — it offers only the models the selected agent supports. See Models & effort.

Missing a binary? shep tools list shows which tools are installed, and shep install <tool> installs one (--how just prints the instructions).

Picking an agent per feature

  • Web UI: the New Feature drawer has an agent and model picker. Whatever you pick is pinned to that feature. Until its next start, approval or retry, you can still change the pinned agent and model on the feature’s Overview tab.
  • CLI: shep feat new has no --agent flag — it uses your default agent, with --model and --effort per feature. Other commands do take --agent <type>: shep app new, shep item investigate, shep item fix, shep discovery run, shep incident triage.
  • Spaces: a space can restrict which agents its repos may use, and give them their own logins: shep space config <space> --agents claude-code,codex-cli --claude-config-dir ~/.claude-work.

How agents work with Shep

When you create a feature, Shep:

  1. Creates a worktree and branch.
  2. Builds the agent’s input: your description, any attached files, and the context Shep keeps (for example Project Memory).
  3. Launches the agent non-interactively in the worktree.
  4. Streams its output to the web UI, shep tui and shep feat logs.
  5. Commits the agent’s changes, pushes and opens the PR (if those are on).
  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.

Interactive chat

The Chat page and each feature’s Chat tab hold a live conversation with an agent. Interactive chat is available on Claude Code and Cursor CLI (via cursor-agent acp); with another default agent, pick one of those two in the chat composer. Settings → Chat sets the idle timeout and how many chat sessions may run at once.

Model lists

Model pickers are filled live where the agent exposes a list — Claude Code (Anthropic Models API or the claude CLI), Cursor CLI (cursor-agent --list-models), Codex CLI, OpenRouter and Together AI. The others use a built-in list.

Permissions and sandboxing

Agents run non-interactively under Shep — they can’t stop and ask “should I run this command?” mid-run. So by default Shep passes each agent’s permission-bypass flag (for example --dangerously-skip-permissions for Claude Code, --yolo for Cursor CLI).

Your safety net is three layers deep:

  1. Worktree isolation. The agent works on a copy, not your checkout.
  2. Draft PRs and the merge gate. Nothing is merged until you approve it, unless you chose --allow-merge.
  3. Your CI pipeline. Tests, linters and security scanners run before merge.

The bypass flag is a default, not a requirement — configure your agent’s own permission model if you want tighter control.

Some agents sandbox network access by default. If npm install (or similar) fails inside a feature, allow the hosts it needs in your agent’s settings.

If an agent needs to ask you something mid-run, it uses a decision instead of an interactive prompt.

What’s next