Configuration
Out of the box Shep works with no configuration beyond picking an agent. When you want different defaults, you have three places to change them:
- The web UI — Settings in the sidebar.
- The CLI — the
shep settingscommands. - Per feature — flags on
shep feat new, or the toggles in the New Feature drawer.
Where settings live
Shep keeps one global settings record in a local SQLite database at ~/.shep/data. It applies to every repo. There is no JSON or YAML config file to edit — and no .shep/config.json in your repo; read and change settings through the web UI or shep settings.
shep settings show # everything, as a table
shep settings show -o json # or yamlSet SHEP_HOME to move the whole Shep home folder — database, daemon log, worktrees, apps — somewhere else. The database is then $SHEP_HOME/data.
The shep settings commands
| Command | What it does |
|---|---|
shep settings | Interactive wizard: agent, IDE, and workflow defaults. |
shep settings show [-o table/json/yaml] | Print the current settings. |
shep settings agent | Choose the agent and how it authenticates: --agent <type> --auth session or --auth token --token <key>. See Agents. |
shep settings model | Pick the default model (interactive; lists the models your agent supports). |
shep settings effort [level] | Default reasoning effort: low, medium, high, xhigh, max. --clear goes back to the agent’s own default. Only Claude Code uses it. |
shep settings adaptive-models | Route each task to a model that matches its complexity: --enable / --disable, --high, --medium, --low <model>, --clear. |
shep settings workflow | Default gates, push/PR, and the parallel limit — see below. |
shep settings worktree | Custom worktree commands: --create-command, --post-create-command, --timeout <ms>, --clear. |
shep settings ide | Editor that shep ide and “Open in IDE” use: --editor with vscode, cursor, windsurf, zed or antigravity. |
shep settings language | Display language. |
shep settings flags | List feature flags; flags enable <flag> / flags disable <flag> to toggle one. |
shep settings messaging | Set up messaging remote control; messaging status, messaging disconnect. |
shep settings init | Reset all settings to defaults (asks first; -f skips the prompt). |
Model, effort and adaptive tiers are covered in depth in Models & effort; worktree commands in Worktree provisioning.
Workflow defaults
The most useful setting. Once your defaults are right, you stop typing --push --pr every time:
shep settings workflow # interactive checklist
shep settings workflow --push --pr # push and open a PR by default
shep settings workflow --allow-prd --allow-plan # auto-approve the spec gates
shep settings workflow --no-pr # stop opening PRs by default
shep settings workflow --max-parallel 3 # at most 3 features running at once| Flag | Default for new features |
|---|---|
--allow-prd | Auto-approve the requirements gate. |
--allow-plan | Auto-approve the plan gate. |
--allow-merge | Auto-approve the merge gate (Shep merges once CI is green). |
--allow-all | All three gates. |
--push / --no-push | Push the branch when implementation finishes. |
--pr / --no-pr | Open a draft PR when implementation finishes. |
--max-parallel <n> | Most features running an agent at once. 0 (the default) means unlimited; extra features queue as Pending. |
The interactive version is a checklist of the same five: Allow PRD, Allow Plan, Allow Merge, Push on finish, Create PR.
Settings that live only in the web UI
These have no shep settings command — change them in the web UI’s Settings page:
| Section | Setting | Default |
|---|---|---|
| Workflow | Default feature mode (Fast, Regular = spec-driven, Exploration) | Fast |
| Workflow | Question deadline — how long a background agent waits for your answer before taking its recommended option | 30 minutes |
| Workflow | Auto-archive delay after a feature completes (0 turns it off) | 10 minutes |
| Workflow | Evidence collection, and adding evidence to the PR | off |
| CI | Max fix attempts | 3 |
| CI | Watch timeout | 10 minutes |
| CI | Max log size sent to the agent | 50,000 characters |
| CI | Poll interval | 30 seconds |
| Timeouts | Time limit per agent stage (analyze, requirements, research, plan, implement, merge) | 30 minutes each |
| Notifications | Which agent and PR events notify you | — |
| Chat | Chat tab on/off, idle timeout, max concurrent sessions | — |
| Home page | Which page opens first | Control Center |
| Usage metrics | Anonymous usage metrics on or off (also shep telemetry on/off) | on |
The web Settings page
Settings in the sidebar is one page with a section menu: Language, Agent, Adaptive models, Environment, Workflow, Worktree, CI, Timeouts, Notifications, Messaging, MCP, Connect agents, Flags, Chat, Home page, Layout, Integrations, Usage metrics and Database. Security, Agent Harness and Self-learning appear when their feature flags are on. See Web Dashboard → Settings for what each holds.

How a feature’s settings are resolved
CLI flag → value stored on the feature → global default in SettingsA flag passed to shep feat new wins for that feature. Shep stores the result on the feature (agent, model, effort, gates, push/PR), so changing your defaults later doesn’t change features that already exist. Otherwise the global default applies.
Repos in a space can add their own layer: per-space agent logins (--claude-config-dir, --gh-config-dir), git identity, allowed agents and PR-comment behavior, set with shep space config.
Per-repo files
Shep reads a few optional files from <repo>/.shep/. Commit them so everyone using Shep on the repo gets the same behavior.
.shep/dev.json — how to run the dev server
Tells Shep how to start this repo’s dev server, instead of detecting it:
{
"command": "make dev",
"cwd": "services/api",
"expectedPort": 8080,
"language": "Go",
"framework": "Echo",
"setupCommands": ["go mod download"]
}Only command is required. cwd must stay inside the repo. Because the file runs commands on your machine, Shep asks you to approve it first — and again whenever the commands change:
shep dev plan show # see what Shep will run
shep dev approve # approve the current .shep/dev.jsonSee Dev servers.
.shep/ownership.yaml — code owners for security findings
Maps path globs to owners for the security posture (ASPM) feature, which is off by default:
entries:
- pathGlob: 'services/api/**'
ownerId: alice
teamId: platform
- pathGlob: 'web/**'
ownerId: bob.shep/harness/ — experimental harness setup
Written by shep harness init for the experimental query-aware harness (queryAwareHarness flag): instructions, policies and eval suites. See Agent harness.
Environment variables
| Variable | Effect |
|---|---|
SHEP_HOME | Move Shep’s home folder (default ~/.shep). |
SHEP_LOG_LEVEL | Log level: debug, info, warn, error or silent. Same as the global --log-level flag. |
DEBUG | Any non-empty value turns on verbose CLI logging (DEBUG=1). |
DEBUG_SQL | Any non-empty value logs SQLite statements and migrations. |
SHEP_BIND_HOST | Interface the web UI binds to. Default localhost. |
SHEP_ALLOW_PUBLIC_BIND | Set to 1 to allow SHEP_BIND_HOST beyond the loopback interface. |
SHEP_ALLOWED_HOSTS | Extra Host header values to accept, for reverse-proxy setups. |
SHEP_WEB_REQUIRE_TOKEN | Set to 1 to require the access token for web pages, not just API routes. |
SHEP_MULTIPLEXER | Force the terminal multiplexer shep tui uses: tmux, zellij, wezterm, kitty or none. |
DO_NOT_TRACK, SHEP_TELEMETRY_DISABLED | Set either to 1 to force usage metrics off. |
OPENROUTER_API_KEY, TOGETHER_API_KEY, OLLAMA_BASE_URL, LLMPROXY_BASE_URL | Fallback credentials for the experimental Shep Harness when no token is set. |
There is no environment variable for the port. Use shep start --port <n> (or shep ui --port <n>); by default Shep uses 4050, or the next free port.
Global flags
Every command accepts:
| Flag | Effect |
|---|---|
--verbose | More output. |
--debug | Debug output. |
--log-level <level> | debug, info, warn, error or silent. |
-v, --version | Print the version. |
Feature flags
Feature flags turn whole areas of Shep on or off — the software factory pages, Projects, the SDLC board, experimental harnesses and more. Many are on by default.
shep settings flags # every flag, grouped, with its state and default
shep settings flags enable sdlcBoard
shep settings flags disable spacesOr use Settings → Flags in the web UI. See Feature flags for the full list.
Example setups
Push and open PRs, merge by hand (a good team default):
shep settings workflow --push --prSpec-driven with light oversight — auto-approve requirements, review the plan and the merge:
shep settings workflow --allow-prd
# then Settings → Workflow → Default feature mode → RegularA busy machine — cap concurrency and think harder on each run:
shep settings workflow --max-parallel 3
shep settings effort highA monorepo — share node_modules into every new worktree:
shep settings worktree --post-create-command 'ln -s "$SHEP_REPO_PATH/node_modules" node_modules'Save on cost — let simple tasks run on a cheaper model in the same family:
shep settings adaptive-models --enableWhat’s next
- Models & effort — default model, effort, adaptive tiers and
shep usage. - Feature flags — what each flag turns on.
- Worktree provisioning — custom create and post-create commands.
- Usage metrics & privacy — what Shep sends and how to turn it off.