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.
| Agent | Binary on PATH | --agent value | Notes |
|---|---|---|---|
| Claude Code | claude | claude-code | The only agent that receives reasoning effort. |
| Kimi Code | kimi | kimi-code | Moonshot AI’s CLI. --model selects a model key from ~/.kimi/config.toml. |
| Codex CLI | codex | codex-cli | OpenAI’s Codex CLI. |
| Copilot CLI | copilot | copilot-cli | Needs a GitHub Copilot subscription. Session auth only. |
| Cursor CLI | cursor-agent | cursor | The binary is cursor-agent, not the cursor editor. See cursor.com/cli . |
| Gemini CLI | gemini | gemini-cli | Google’s Gemini CLI. |
| Cline | cline | cline | Multi-provider agent with full tool use. |
Model providers — no binary. Shep calls the provider’s API directly.
| Provider | --agent value | What you need |
|---|---|---|
| OpenRouter | openrouter | An OpenRouter API key (token auth). |
| Together AI | together-ai | A Together AI API key (token auth). |
| Ollama | ollama | A local Ollama server. Defaults to http://localhost:11434/v1; put a different base URL in the token field. No key. |
| LLM Proxy | llmproxy | A 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(orkimi,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.

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 newhas no--agentflag — it uses your default agent, with--modeland--effortper 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:
- Creates a worktree and branch.
- Builds the agent’s input: your description, any attached files, and the context Shep keeps (for example Project Memory).
- Launches the agent non-interactively in the worktree.
- Streams its output to the web UI,
shep tuiandshep feat logs. - Commits the agent’s changes, pushes and opens the PR (if those are on).
- 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:
- Worktree isolation. The agent works on a copy, not your checkout.
- Draft PRs and the merge gate. Nothing is merged until you approve it, unless you chose
--allow-merge. - 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
- Models & effort — default model, reasoning effort, adaptive tiers and
shep usage. - Configuration — everything else in
shep settings. - Troubleshooting — when an agent isn’t found or isn’t signed in.