Feature Flags
Shep has 28 feature flags in three groups:
- Platform — established areas you can switch off if you don’t use them. Most are on.
- Software factory — spaces, trackers, opportunities, incidents and the rest of the software factory. All on.
- Experimental — work in progress. All off. They may change or be removed in a future release; turn them on at your own risk.
When a flag is off, its pages, sidebar links and buttons are hidden, and its CLI commands are hidden or refuse to run.
Toggle a flag
In the web UI
Open Settings → Flags and click Open the feature flags view (or go straight to /settings/feature-flags). Flags are grouped as above, each with a Default: on/off badge, and the header shows how many are on. Changes apply right away.
From the CLI
shep settings flags # every flag: state, name, description, default
shep settings flags enable aspm # turn a flag on
shep settings flags disable factory # turn a flag offUse the flag names in the tables below (for example selfLearning, not “Self-learning harness”).
Defaults and upgrades
The defaults below are what a new install gets. Your choices are stored in your settings and kept across upgrades. Some upgrades have switched flags on for existing installs (for example projects, codeReview, collaboration and aspm) unless you had turned them off. shep settings flags always shows your actual state.
Platform
| Flag | Settings label | Default | What it turns on |
|---|---|---|---|
envDeploy | Deployments | on | Dev-server controls on repository nodes and in the repository and feature drawers. See Dev servers. shep dev works either way |
projects | Projects | on | The Projects sidebar link and /projects pages. shep project, shep item, shep cycle and shep intake work either way |
codeReview | AI Code Review | on | Trigger Review on a feature’s Overview tab when it has a pull request: the agent reviews the diff and posts inline comments to GitHub. shep review works either way |
collaboration | Agent Collaboration & Supervision | on | The Collaboration sidebar group (Agent questions, Supervisor, Agents), the ask_decision tool for background runs, and the supervisor. When off, shep supervisor and shep agent questions are hidden from help |
githubImport | GitHub Import | on | Cloning or forking a GitHub repository when you add one |
bedrockIntegration | Project Bedrock Memory | on | Project Bedrock markdown memory: toggles, drawers and tabs on apps, repositories and features. Needs Python 3.9+ and pipx. shep bedrock works either way |
aspm | Application Security Posture Management | off | The /aspm pages (findings, inventory, owners, AI-change review, compliance) and shep aspm. While off, shep security enforce does nothing and exits 0; set SHEP_SUPPLY_CHAIN_SECURITY=true (or false) to override that in CI |
sdlcBoard | SDLC board | off | /sdlc: a live board of agent tasks across active features |
Software factory
All on by default. Each gates its pages and CLI commands; a gated command prints how to turn it back on.
| Flag | Settings label | What it turns on |
|---|---|---|
spaces | Spaces | /spaces and shep space: spaces and product lines with their own knowledge and agent logins |
trackers | Trackers | Linear and Jira sync: /connections, shep connection, shep sync, and background sync |
knowledge | Knowledge | Notion pages synced into a space’s knowledge: shep knowledge (and shep connection) |
signals | Signals | Customer and incident signals as evidence: shep signal |
opportunities | Opportunities | Ranked opportunities: /opportunities, shep opportunity |
feedback | Feedback | Feedback intake and themes: POST /api/feedback, shep feedback |
discovery | Discovery | An agent proposing opportunities from a space’s evidence: shep discovery |
incidents | Incidents | Incident triage: /incidents, POST /api/alerts, shep incident |
outcomes | Outcomes | Checking whether shipped work fixed what it was built for: shep outcome |
docsFirst | Docs First | Docs-first spaces: docs written while planning, and a merge gate that waits when docs are missing |
autopilot | Autopilot | A space investigating, fixing and building on its own within its policy: shep autopilot |
factory | Factory | Each space’s factory status: /factory, shep factory |
See the software factory section for how these fit together.
Experimental
All off by default.
| Flag | Settings label | What it turns on |
|---|---|---|
clusters | Clusters | Clusters in the sidebar and Kubernetes cluster management at /clusters. shep cluster works either way |
scheduledWorkflows | Scheduled Workflows | /workflows and the scheduler that runs workflows on a cron schedule. shep workflow works either way, but scheduled runs need the flag |
selfLearning | Self-learning harness | /learning, Settings → Self-learning, shep learn, shep feat new --explore-harness, and d in shep tui. See Agent harness |
agentCoordination | Agent coordination | When two active features change the same files, an agent decides whether one should wait for the other |
queryAwareHarness | Query-aware agent harness | The Shep Harness agent, /harness, the feature Context tab, Settings → Agent Harness, and shep harness in help. See Agent harness |
whatsappDispatch | WhatsApp Task Dispatch | Creating features, getting updates and approving gates from a WhatsApp chat. shep whatsapp status shows whether it’s set up |
reactFileManager | React File Manager | A built-in folder picker instead of your system’s native dialog when adding a repository. Useful on remote desktops or Linux without a file-manager backend |
debug | Debug | Debug panels and verbose client-side logging. Also enables the developer-only shep agent message send command |
How gated CLI commands behave
There are two behaviours:
-
Refuses to run.
shep space,connection,sync,knowledge,signal,opportunity,feedback,discovery,incident,outcome,autopilot,factory,learnandaspmare hidden fromshep --helpwhile their flag is off. Running one prints a message and exits with status 1:`shep factory` is turned off. Turn it on with `shep settings flags enable factory`.shep connectionruns when eithertrackersorknowledgeis on. -
Hidden from help only.
shep harness(queryAwareHarness),shep supervisorandshep agent questions(collaboration) disappear fromshep --helpwhile their flag is off. Turn the flag on before using them.
Web actions behind an off flag fail with a clear “Feature flag … is disabled” message rather than a server error.
Environment variable fallbacks
The web UI reads flags from your settings. Only if it can’t read them does it fall back to these variables (true or 1 turns a flag on):
| Variable | Flag |
|---|---|
NEXT_PUBLIC_FLAG_ENV_DEPLOY | envDeploy |
NEXT_PUBLIC_FLAG_REACT_FILE_MANAGER | reactFileManager |
NEXT_PUBLIC_FLAG_PROJECTS | projects |
NEXT_PUBLIC_FLAG_CODE_REVIEW | codeReview |
NEXT_PUBLIC_FLAG_COLLABORATION | collaboration |
NEXT_PUBLIC_FLAG_ASPM | aspm |
NEXT_PUBLIC_FLAG_BEDROCK_INTEGRATION | bedrockIntegration |
NEXT_PUBLIC_FLAG_WHATSAPP_DISPATCH | whatsappDispatch |
NEXT_PUBLIC_FLAG_QUERY_AWARE_HARNESS | queryAwareHarness |
These are a fallback, not a way to override your settings. To change a flag, use Settings or shep settings flags.
The daily usage heartbeat includes the names of the flags you have on, so the Shep team can see which areas are used. Nothing else about your settings is sent. See Usage metrics & privacy.
When something doesn’t appear
- Check the flag’s actual state with
shep settings flags. Your stored value may differ from the default. - Reload the page. Open pages pick up a change on their next load.
- Restart the daemon for background services. The workflow scheduler (
scheduledWorkflows) and the WhatsApp connection (whatsappDispatch) start with the daemon: runshep restartafter turning them on. - Check your version with
shep version, andshep upgradeif you’re behind. Some flags only exist in newer releases.
See also
- Configuration — all other settings.
- CLI reference — every command.
- Agent harness — the two experimental harness features.