gemini-cli/docs/cli/feature-lifecycle.md

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
  • Configuration
    • Precedence and Reconciliation
  • Available Features
  • Managing Feature Lifecycle
    • Adding a Feature
    • Promoting a Feature
    • Deprecating a Feature
    • Removing a Feature
  • Relevant Documentation

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:

1. /features Command: Use the /features (or /feature) command directly in the CLI to list all Alpha, Beta, and Deprecated features. This view shows the maturity stage, enablement status, and metadata like the version it was introduced (since) and when it is scheduled for removal (until).
2. 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.
3. CLI Flag: Use --feature-gates="feat1=true,feat2=false" for runtime overrides.
4. 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.

Lifecycle tracking issues

Every feature managed under this system must have a corresponding Lifecycle Tracking Issue on GitHub. These issues act as a living roadmap and a public feedback loop for the feature's progression through Alpha, Beta, and GA stages.

You can find the link to a feature's tracking issue in the following ways:

1. /features Command: The tracker URL is displayed alongside the metadata for each feature.
2. FeatureDefinitions: The issueUrl is defined in packages/core/src/config/features.ts.

Maintainers use these issues to document promotion criteria, link related bug reports, and collect user feedback before moving a feature to the next stage.

Precedence and reconciliation

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

1. Global Lock: Features in the GA stage are locked to true and cannot be disabled.
2. CLI Flags & Environment Variables: Runtime overrides (--feature-gates or GEMINI_FEATURE_GATES) override persistent settings.
3. Individual Toggle: Specific feature toggles in settings.json (e.g., "features": { "plan": true }).
4. 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.
5. 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.

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:

1. Create a Tracker Issue: Use the Feature Lifecycle Tracker template on GitHub to create a new issue. This issue will track the feature from Alpha through GA.

2. 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.',
         issueUrl: 'https://github.com/google-gemini/gemini-cli/issues/123',
       },
     ],
   };
   

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

3. 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,
       },
     },
   },
   

4. 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:

1. Update the Tracker: Review the requirements in the lifecycle tracker issue. Once met, update the roadmap table in the issue description and post a comment announcing the promotion.
2. 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.
3. Update settingsSchema.ts: Update the label and description if necessary.
4. 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.

1. 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.
2. 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:

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

Relevant Documentation

• Settings Reference
• Configuration Layers