Feature Flags

Feature flags control the visibility and behavior of in-development functionality. They are toggled per-installation via Settings > Developer > Feature Flags.

Overview

Feature flags live in a single source of truth: DEFAULT_FEATURE_FLAGS in libs/types/src/global-settings.ts. All fields default to false — new features are opt-in per environment.

// libs/types/src/global-settings.ts
export interface FeatureFlags {
  specEditor: boolean;
  userPresenceDetection: boolean;
  reactorEnabled: boolean;
  hitlForms: boolean;
  gatewayAutoRemediate: boolean;
}

export const DEFAULT_FEATURE_FLAGS: FeatureFlags = {
  specEditor: false,
  userPresenceDetection: false,
  reactorEnabled: false,
  hitlForms: false,
  gatewayAutoRemediate: false,
};

GlobalSettings.featureFlags is persisted to data/settings.json. The UI merges server settings into DEFAULT_FEATURE_FLAGS on load — existing installs automatically pick up new flag fields without requiring a migration.

Current Flags

Flag	Default	What it gates
specEditor	off	Spec editor in the sidebar Tools section
userPresenceDetection	off	Sensor-driven presence awareness (tab visibility, idle/afk)
reactorEnabled	off	Ava Channel Reactor — reactive orchestrator that monitors the CRDT-backed Ava Channel and auto-responds to incoming messages (requires hivemind)
hitlForms	off	HITL interrupt forms from PM Agent, Signal Intake, and Lead Engineer. When disabled, HITL-gated actions are auto-approved or escalated to Ava instead
gatewayAutoRemediate	off	Gateway Action Executor auto-acts on structured recommendations from heartbeat cycles (unblock_feature, retry_agent, merge_ready_pr; max 3 per cycle)

Graduated Flags (GA -- always enabled)

These flags were removed from FeatureFlags after reaching general availability:

Former Flag	Graduated	Notes
calendar	v0.17	Calendar view in project sidebar
notes	v0.17	Notes tabs in project sidebar
avaChat	v0.84	Ava Anywhere chat overlay

How to Add a New Flag

Follow these 5 steps in order. TypeScript will fail to compile after step 1 until step 2 is complete — this is intentional.

Step 1 — Define the field in libs/types/src/global-settings.ts:

// Add to FeatureFlags interface
myFeature: boolean;

// Add to DEFAULT_FEATURE_FLAGS
export const DEFAULT_FEATURE_FLAGS: FeatureFlags = {
  // ...existing flags
  myFeature: false,
};

Step 2 — Add a UI label in apps/ui/src/components/views/settings-view/developer/developer-section.tsx:

// FEATURE_FLAG_LABELS is typed as Record<keyof FeatureFlags, ...>
// TypeScript will error here if you forget this step
const FEATURE_FLAG_LABELS: Record<keyof FeatureFlags, { label: string; description: string }> = {
  // ...existing entries
  myFeature: {
    label: 'My Feature',
    description: 'What this flag enables and any caveats.',
  },
};

Step 3 — Do NOT add hardcoded defaults elsewhere. DEFAULT_FEATURE_FLAGS is the single source of truth. The spread pattern in use-settings-sync.ts ensures new flags propagate automatically:

featureFlags: { ...DEFAULT_FEATURE_FLAGS, ...(serverSettings.featureFlags ?? {}) }

Step 4 — Add a server-side guard wherever your new feature creates side effects:

const featureFlags = this.serviceContext.settingsService
  ? (await this.serviceContext.settingsService.getGlobalSettings()).featureFlags
  : null;
const myFeatureEnabled = featureFlags?.myFeature ?? false;

if (myFeatureEnabled) {
  // do the guarded work
}

Step 5 — Add unit tests covering both flag states:

it('does nothing when myFeature flag is false (default)', async () => { ... });
it('runs when myFeature flag is true', async () => { ... });

Graduating a Flag

When a feature is stable and ready for GA:

1. Remove the field from FeatureFlags interface and DEFAULT_FEATURE_FLAGS
2. Remove the entry from FEATURE_FLAG_LABELS in developer-section.tsx
3. Remove any server-side guards that check the flag — the feature is now always on
4. Add the flag to the "Graduated Flags" table in this document

Server-Side Consumption Pattern

Access feature flags via settingsService.getGlobalSettings():

// In a StateProcessor or service method (async context)
const featureFlags = this.serviceContext.settingsService
  ? (await this.serviceContext.settingsService.getGlobalSettings()).featureFlags
  : null;

const enabled = featureFlags?.myFlag ?? false;

Always treat settingsService as optional and default to false when absent — it may not be wired in all test contexts.

FeatureFlags vs WorkflowSettings

These are frequently confused:

	FeatureFlags	WorkflowSettings
Scope	Global, per installation	Per project
Purpose	UI/feature on/off toggles	Agent pipeline tuning (model tier, retry counts, etc.)
Location	data/settings.json	.automaker/settings.json
Interface	libs/types/src/global-settings.ts	libs/types/src/global-settings.ts
Default	DEFAULT_FEATURE_FLAGS	DEFAULT_WORKFLOW_SETTINGS

Use FeatureFlags to gate entire product features. Use WorkflowSettings to tune pipeline parameters like max retries and model tier.

UI Rendering

The Developer settings section auto-renders all FeatureFlags keys as toggle rows. No manual wiring is required — the component loops over Object.keys(featureFlags) and looks up each key in FEATURE_FLAG_LABELS. If a key is missing from FEATURE_FLAG_LABELS, it is silently skipped (guarded by the if (!meta) return null check in the loop).

Because FEATURE_FLAG_LABELS is typed as Record<keyof FeatureFlags, ...>, TypeScript will produce a compile error if any key is missing from the labels map, catching the omission before it reaches production.