Skip to Content
GuidesFeature Flags

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 off

Use 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

FlagSettings labelDefaultWhat it turns on
envDeployDeploymentsonDev-server controls on repository nodes and in the repository and feature drawers. See Dev servers. shep dev works either way
projectsProjectsonThe Projects sidebar link and /projects pages. shep project, shep item, shep cycle and shep intake work either way
codeReviewAI Code ReviewonTrigger 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
collaborationAgent Collaboration & SupervisiononThe 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
githubImportGitHub ImportonCloning or forking a GitHub repository when you add one
bedrockIntegrationProject Bedrock MemoryonProject Bedrock markdown memory: toggles, drawers and tabs on apps, repositories and features. Needs Python 3.9+ and pipx. shep bedrock works either way
aspmApplication Security Posture ManagementoffThe /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
sdlcBoardSDLC boardoff/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.

FlagSettings labelWhat it turns on
spacesSpaces/spaces and shep space: spaces and product lines with their own knowledge and agent logins
trackersTrackersLinear and Jira sync: /connections, shep connection, shep sync, and background sync
knowledgeKnowledgeNotion pages synced into a space’s knowledge: shep knowledge (and shep connection)
signalsSignalsCustomer and incident signals as evidence: shep signal
opportunitiesOpportunitiesRanked opportunities: /opportunities, shep opportunity
feedbackFeedbackFeedback intake and themes: POST /api/feedback, shep feedback
discoveryDiscoveryAn agent proposing opportunities from a space’s evidence: shep discovery
incidentsIncidentsIncident triage: /incidents, POST /api/alerts, shep incident
outcomesOutcomesChecking whether shipped work fixed what it was built for: shep outcome
docsFirstDocs FirstDocs-first spaces: docs written while planning, and a merge gate that waits when docs are missing
autopilotAutopilotA space investigating, fixing and building on its own within its policy: shep autopilot
factoryFactoryEach space’s factory status: /factory, shep factory

See the software factory section for how these fit together.

Experimental

All off by default.

FlagSettings labelWhat it turns on
clustersClustersClusters in the sidebar and Kubernetes cluster management at /clusters. shep cluster works either way
scheduledWorkflowsScheduled Workflows/workflows and the scheduler that runs workflows on a cron schedule. shep workflow works either way, but scheduled runs need the flag
selfLearningSelf-learning harness/learning, Settings → Self-learning, shep learn, shep feat new --explore-harness, and d in shep tui. See Agent harness
agentCoordinationAgent coordinationWhen two active features change the same files, an agent decides whether one should wait for the other
queryAwareHarnessQuery-aware agent harnessThe Shep Harness agent, /harness, the feature Context tab, Settings → Agent Harness, and shep harness in help. See Agent harness
whatsappDispatchWhatsApp Task DispatchCreating features, getting updates and approving gates from a WhatsApp chat. shep whatsapp status shows whether it’s set up
reactFileManagerReact File ManagerA 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
debugDebugDebug 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, learn and aspm are hidden from shep --help while 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 connection runs when either trackers or knowledge is on.

  • Hidden from help only. shep harness (queryAwareHarness), shep supervisor and shep agent questions (collaboration) disappear from shep --help while 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):

VariableFlag
NEXT_PUBLIC_FLAG_ENV_DEPLOYenvDeploy
NEXT_PUBLIC_FLAG_REACT_FILE_MANAGERreactFileManager
NEXT_PUBLIC_FLAG_PROJECTSprojects
NEXT_PUBLIC_FLAG_CODE_REVIEWcodeReview
NEXT_PUBLIC_FLAG_COLLABORATIONcollaboration
NEXT_PUBLIC_FLAG_ASPMaspm
NEXT_PUBLIC_FLAG_BEDROCK_INTEGRATIONbedrockIntegration
NEXT_PUBLIC_FLAG_WHATSAPP_DISPATCHwhatsappDispatch
NEXT_PUBLIC_FLAG_QUERY_AWARE_HARNESSqueryAwareHarness

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

  1. Check the flag’s actual state with shep settings flags. Your stored value may differ from the default.
  2. Reload the page. Open pages pick up a change on their next load.
  3. Restart the daemon for background services. The workflow scheduler (scheduledWorkflows) and the WhatsApp connection (whatsappDispatch) start with the daemon: run shep restart after turning them on.
  4. Check your version with shep version, and shep upgrade if you’re behind. Some flags only exist in newer releases.

See also