Skip to Content
GuidesConfiguration

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 settings commands.
  • 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 yaml

Set 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

CommandWhat it does
shep settingsInteractive wizard: agent, IDE, and workflow defaults.
shep settings show [-o table/json/yaml]Print the current settings.
shep settings agentChoose the agent and how it authenticates: --agent <type> --auth session or --auth token --token <key>. See Agents.
shep settings modelPick 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-modelsRoute each task to a model that matches its complexity: --enable / --disable, --high, --medium, --low <model>, --clear.
shep settings workflowDefault gates, push/PR, and the parallel limit — see below.
shep settings worktreeCustom worktree commands: --create-command, --post-create-command, --timeout <ms>, --clear.
shep settings ideEditor that shep ide and “Open in IDE” use: --editor with vscode, cursor, windsurf, zed or antigravity.
shep settings languageDisplay language.
shep settings flagsList feature flags; flags enable <flag> / flags disable <flag> to toggle one.
shep settings messagingSet up messaging remote control; messaging status, messaging disconnect.
shep settings initReset 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
FlagDefault for new features
--allow-prdAuto-approve the requirements gate.
--allow-planAuto-approve the plan gate.
--allow-mergeAuto-approve the merge gate (Shep merges once CI is green).
--allow-allAll three gates.
--push / --no-pushPush the branch when implementation finishes.
--pr / --no-prOpen 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:

SectionSettingDefault
WorkflowDefault feature mode (Fast, Regular = spec-driven, Exploration)Fast
WorkflowQuestion deadline — how long a background agent waits for your answer before taking its recommended option30 minutes
WorkflowAuto-archive delay after a feature completes (0 turns it off)10 minutes
WorkflowEvidence collection, and adding evidence to the PRoff
CIMax fix attempts3
CIWatch timeout10 minutes
CIMax log size sent to the agent50,000 characters
CIPoll interval30 seconds
TimeoutsTime limit per agent stage (analyze, requirements, research, plan, implement, merge)30 minutes each
NotificationsWhich agent and PR events notify you—
ChatChat tab on/off, idle timeout, max concurrent sessions—
Home pageWhich page opens firstControl Center
Usage metricsAnonymous 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.

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

How a feature’s settings are resolved

CLI flag → value stored on the feature → global default in Settings

A 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.json

See 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

VariableEffect
SHEP_HOMEMove Shep’s home folder (default ~/.shep).
SHEP_LOG_LEVELLog level: debug, info, warn, error or silent. Same as the global --log-level flag.
DEBUGAny non-empty value turns on verbose CLI logging (DEBUG=1).
DEBUG_SQLAny non-empty value logs SQLite statements and migrations.
SHEP_BIND_HOSTInterface the web UI binds to. Default localhost.
SHEP_ALLOW_PUBLIC_BINDSet to 1 to allow SHEP_BIND_HOST beyond the loopback interface.
SHEP_ALLOWED_HOSTSExtra Host header values to accept, for reverse-proxy setups.
SHEP_WEB_REQUIRE_TOKENSet to 1 to require the access token for web pages, not just API routes.
SHEP_MULTIPLEXERForce the terminal multiplexer shep tui uses: tmux, zellij, wezterm, kitty or none.
DO_NOT_TRACK, SHEP_TELEMETRY_DISABLEDSet either to 1 to force usage metrics off.
OPENROUTER_API_KEY, TOGETHER_API_KEY, OLLAMA_BASE_URL, LLMPROXY_BASE_URLFallback 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:

FlagEffect
--verboseMore output.
--debugDebug output.
--log-level <level>debug, info, warn, error or silent.
-v, --versionPrint 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 spaces

Or 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 --pr

Spec-driven with light oversight — auto-approve requirements, review the plan and the merge:

shep settings workflow --allow-prd # then Settings → Workflow → Default feature mode → Regular

A busy machine — cap concurrency and think harder on each run:

shep settings workflow --max-parallel 3 shep settings effort high

A 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 --enable

What’s next