Configuration

Shep stores settings at two levels:

• Global — applies to all repos. Lives in SQLite at ~/.shep/.
• Per-repo — overrides for a specific project. Lives in .shep/config.json in the repo root.

Both are optional. Out of the box, sensible defaults work for most projects.

Global settings

The fastest way is the interactive wizard:

shep settings           # full wizard
shep settings show      # print current settings
shep settings init      # re-run first-time setup

Or jump to a section:

shep settings agent       # AI agent (Claude / Cursor / Gemini) and model
shep settings ide         # default IDE for "Open in IDE" buttons
shep settings workflow    # default flags (push, PR, allow-merge, fast / spec-driven)
shep settings model       # default model per agent
shep settings language    # dashboard language

Workflow defaults

This is the most useful setting. Once configured, you stop having to remember --push --pr every time:

shep settings workflow

The wizard asks:

• Push by default?
• Open PR by default?
• Auto-merge after CI passes?
• Use fast or spec-driven mode by default?
• How many CI fix retries before pausing?
• Should Shep wait for review before pushing?

Override on a per-feature basis with flags. CLI flags always win.

Per-repo settings

Create .shep/config.json in the repo root. Anything you set here overrides global settings for that repo only:

{
  "analysis": {
    "additionalExcludes": ["**/generated/**"],
    "reanalyzeOnChange": true
  },
  "agents": {
    "implementation": {
      "requireApproval": true
    }
  }
}

Commit this file so your team gets the same defaults.

Agent settings

Pick which agent Shep launches when it runs your features:

shep settings agent

You authenticate the agent yourself before running Shep — Shep does not store or transmit API keys. If your claude / cursor / gemini command works in the terminal, Shep can use it.

Analysis settings

Shep analyzes your codebase on first run so the agent has architectural context. Configure scope in .shep/config.json:

{
  "analysis": {
    "excludePatterns": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
    "additionalExcludes": ["**/vendor/**", "**/generated/**"],
    "maxFileSize": 1048576,
    "maxFiles": 10000,
    "perspectives": [
      "architecture",
      "dependencies",
      "patterns",
      "conventions",
      "tech-stack",
      "documentation"
    ]
  }
}

Agent runtime settings

Tune how many agents run at once and how long they’re allowed:

{
  "agents": {
    "maxConcurrentAgents": 4,
    "timeoutMs": 300000,
    "retryAttempts": 3,
    "implementation": {
      "requireApproval": false,
      "maxParallelTasks": 2,
      "autoCommit": true
    }
  }
}

Environment variables

SHEP_PORT=8080 SHEP_LOG_LEVEL=debug shep

Precedence

Settings resolve from highest to lowest priority:

1. CLI flags on the command itself.
2. Environment variables.
3. Repo config (.shep/config.json).
4. Global settings (~/.shep/).
5. Built-in defaults.

Feature flags

The dashboard’s Settings → Feature Flags section lets you toggle in-development surfaces — Projects, AI Code Review, the supervisor agent, and more. See Experimental Features for the full list and what each one unlocks.

Example configurations

Minimal

No config file. Run shep settings init, accept the defaults, ship.

Team project (require human review)

Push and open PRs automatically, but never auto-merge:

{
  "agents": {
    "implementation": {
      "requireApproval": false,
      "autoCommit": true
    }
  }
}

Set workflow defaults via shep settings workflow: push yes, PR yes, allow-merge no.

Strict review (approve every task)

For sensitive areas — security, payments, infra. The agent pauses before each task:

{
  "agents": {
    "implementation": {
      "requireApproval": true,
      "autoCommit": false
    }
  }
}

Large monorepo

Limit analysis scope and reduce concurrency:

{
  "analysis": {
    "additionalExcludes": ["**/vendor/**", "**/*.generated.*"],
    "maxFileSize": 524288,
    "maxFiles": 5000,
    "perspectives": ["architecture", "dependencies", "tech-stack"]
  },
  "agents": {
    "maxConcurrentAgents": 2
  }
}