Feature Lifecycle

Gemini CLI uses a Feature Lifecycle management system to handle the introduction, maturation, and deprecation of new and optional features.

Feature Lifecycle

Feature Stages

Features progress through the following stages:

Stage	Default	UI Badge	Description
ALPHA	Disabled	`[ALPHA]`	Early-access features. May be unstable, change significantly, or be removed without notice.
BETA	Enabled	`[BETA]`	Features that are well-tested and considered stable. Can be disabled if issues arise.
GA	Enabled	-	Stable features that are part of the core product. Cannot be disabled.
DEPRECATED	Disabled	`[DEPRECATED]`	Features scheduled for removal. Using them triggers a warning.

Configuration

The feature lifecycle can be configured in several ways:

settings.json: Use the features object to toggle specific features or entire stages.
- features.allAlpha: Enable/disable all Alpha features.
- features.allBeta: Enable/disable all Beta features.
- features.<featureName>: Toggle an individual feature.
CLI Flag: Use --feature-gates="feat1=true,feat2=false" for runtime overrides.
Environment Variable: Set GEMINI_FEATURE_GATES="feat1=true,feat2=false".

The stability of each feature is visually indicated in the /settings UI with colored badges. GA features are considerd stable and look identical to standard settings.

Precedence and Reconciliation

When determining if a feature is enabled, the system follows this order of precedence (highest priority first):

Global Lock: Features in the GA stage are locked to true and cannot be disabled.
CLI Flags & Environment Variables: Runtime overrides (--feature-gates or GEMINI_FEATURE_GATES) override persistent settings.
Individual Toggle: Specific feature toggles in settings.json (e.g., "features": { "plan": true }).
Meta Toggles: Stage-wide toggles in settings.json (allAlpha or allBeta). For example, if allAlpha is true, all Alpha features are enabled unless specifically disabled by an individual toggle.
Stage Default: The inherent default for the feature's current stage (Alpha: Disabled, Beta/GA: Enabled).

For more details on persistent configuration, see the Configuration guide.

Available Features

Feature	Stage	Default	Since	Description
`enableAgents`	ALPHA	Disabled	0.30.0	Enable local and remote subagents.
`extensionConfig`	BETA	Enabled	0.30.0	Enable requesting and fetching of extension settings.
`extensionManagement`	BETA	Enabled	0.30.0	Enable extension management features.
`extensionRegistry`	ALPHA	Disabled	0.30.0	Enable extension registry explore UI.
`extensionReloading`	ALPHA	Disabled	0.30.0	Enables extension loading/unloading within the CLI session.
`jitContext`	ALPHA	Disabled	0.30.0	Enable Just-In-Time (JIT) context loading.
`plan`	ALPHA	Disabled	0.30.0	Enable planning features (Plan Mode and tools).
`toolOutputMasking`	BETA	Enabled	0.30.0	Enables tool output masking to save tokens.
`useOSC52Paste`	ALPHA	Disabled	0.30.0	Use OSC 52 sequence for pasting.
`zedIntegration`	ALPHA	Disabled	0.30.0	Enable Zed integration.

Managing Feature Lifecycle

Maintaining a feature involves promoting it through stages or eventually deprecating and removing it.

Adding a Feature

To add a new feature under lifecycle management:

Define the Feature: Add a new entry to FeatureDefinitions in features.ts.

export const FeatureDefinitions: Record<string, FeatureSpec[]> = {
  // ... existing features
  myNewFeature: [
    {
      lockToDefault: false,
      preRelease: FeatureStage.Alpha,
      since: '0.31.0',
      description: 'Description of my new feature.',
    },
  ],
};

Note: The default field is optional. If omitted, it defaults to false for Alpha/Deprecated and true for Beta/GA.

Expose in Settings: Add the feature to the features object in settingsSchema.ts. This ensures it appears in the /settings UI and is validated.

features: {
  // ...
  properties: {
    // ...
    myNewFeature: {
      type: 'boolean',
      label: 'My New Feature',
      category: 'Features',
      requiresRestart: true, // or false
      description: 'Description of my new feature.',
      showInDialog: true,
    },
  },
},

Use the Feature: In your code, check if the feature is enabled using the Config object.
```
if (this.config.isFeatureEnabled('myNewFeature')) {
  // Feature logic
}
```

Promoting a Feature

When a feature is ready for the next stage:

Update features.ts: Add a new FeatureSpec to the feature's array.
- To BETA: Set preRelease: FeatureStage.Beta (Defaults to true).
- To GA: Set preRelease: FeatureStage.GA (Defaults to true and locked).
- Update the since version.
Update settingsSchema.ts: Update the label and description if necessary.
GA Cleanup: Once a feature is GA and no longer optional, remove the feature gate check from the code and make it a core part of the logic.

Deprecating a Feature

This stage is for Beta and GA features scheduled for removal.

Update features.ts: Add a new FeatureSpec with preRelease: FeatureStage.Deprecated.
- Optionally set default: true if it should remain enabled during deprecation (it defaults to false).
- Optionally set an until version to indicate when it will be removed.
Update settingsSchema.ts: Update the description to notify users of the deprecation and suggest alternatives.

Removing a Feature

Alpha features can be removed without formal deprecation. Beta and GA features should typically go through a deprecation period first.

To completely remove a feature:

Cleanup Code: Remove all logic and tests associated with the feature.
Update features.ts: Remove the feature from FeatureDefinitions.
Update settingsSchema.ts: Remove the feature from the features object.
Legacy Settings: If the feature had a legacy experimental flag, ensure its migration logic is cleaned up in config.ts.

8.3 KiB Raw Blame History