Feature Flags

Feature Flags

Feature flags gate experimental functionality behind user-configurable settings, enabling safe rollout (default off), user opt-in, and easy rollback.

Checking Feature State

goCopy code
import "github.com/marcus/sidecar/internal/features"

if features.IsEnabled("tmux_interactive_input") {
    // Feature-gated code
}

Adding a New Feature Flag

1. Define the feature in internal/features/features.go:

goCopy code
var MyNewFeature = Feature{
    Name:        "my_new_feature",
    Default:     false,
    Description: "Description of what this enables",
}

2. Add to the allFeatures slice:

goCopy code
var allFeatures = []Feature{
    TmuxInteractiveInput,
    MyNewFeature, // Add here
}

3. Use the feature check in your code:

goCopy code
if features.IsEnabled("my_new_feature") {
    // New functionality
}

That is all a flag needs to be reachable. Configuration → System → Feature Flags derives its list from features.ListAll(), so registering a feature puts a working switch on the page with the registry's own Name as the label and Description as the help text. There is no second list to remember.

Giving a flag better copy (optional)

previewCopy in internal/configui/page_flags.go overrides the registry's wording per flag. Only fill in what you want to change:

goCopy code
features.MyNewFeature.Name: {
    label:   "Human-readable name",
    help:    "One sentence on what turning this on does.",
    restart: true, // only if a consumer reads it once at startup
    note:    "An honest scope line for a flag that applies live but not retroactively.",
},

restart must be checked against what actually consumes the flag, never added as blanket caution — a flag read at the point of use applies immediately and must not claim otherwise. Both restart and note render when both are set.

A flag that another page already owns as a first-class setting sets owner and ownerControl instead. It is then listed read-only with a jump to the control that owns it, because two switches over one value is how surfaces start disagreeing. If the owning page's control means more than the raw flag — Panels' Conversations switch is the flag and the plugin's own enabled key — also set reads so the row reports the owner's answer rather than the flag's.

Keep the page shorter than a small terminal. The Configuration detail pane truncates rather than scrolling, and the row cursor still walks onto rows that were cut. Rows are one line each with the explanation shown only under the focused row for that reason; TestFlagsPageFitsAnOrdinaryTerminal guards it.

User Configuration

Config file (~/.config/sidecar/config.json)

jsonCopy code
{
  "features": {
    "flags": {
      "tmux_interactive_input": true
    }
  }
}

CLI override (takes precedence over config)

bashCopy code
sidecar --enable-feature=tmux_interactive_input
sidecar --disable-feature=tmux_interactive_input
sidecar --enable-feature=feature1,feature2   # Multiple features

Unknown feature names in CLI flags produce a warning but do not prevent startup.

Priority Order

Feature state resolves in this order (first match wins):

1. CLI override (--enable-feature, --disable-feature)
2. Config file (features.flags in config.json)
3. Default value (defined in code)

Available Features

API Reference

goCopy code
features.IsEnabled(name string) bool           // Check if enabled
features.List() map[string]bool                 // All features with current state
features.ListAll() []Feature                    // All features with metadata
features.SetEnabled(name string, enabled bool) error  // Persist to config
features.SetOverride(name string, enabled bool) // Runtime override (not persisted)
features.IsKnownFeature(name string) bool       // Check if registered

Best Practices

• Use snake_case for feature names (e.g., my_new_feature)
• New experimental features should default to false
• Provide clear descriptions for each feature
• Document features in docs/guides/deprecated/feature-flags.md when adding them
• Remove feature flags once features are stable