Feature Flags

Feature flags are a local developer tool for toggling work-in-progress features during development. They have no effect on end users unless Developer Mode is enabled in Settings.

How Feature Flags Work

Flags are defined in FEATURE_FLAG_REGISTRY inside src/lib/feature-flags.ts.
Each registered flag automatically appears as a toggle in Settings → Developer → Feature Flags when Developer Mode is active.
Flag state is stored in settings.featureFlags (a Record<string, boolean>) and persisted to disk alongside all other settings.
Flags are purely local — there is no remote configuration, no PostHog integration, and no effect on other users or installations.

Provider Flags

Provider flags are a separate concern from feature flags. They control which LLM providers are available in the app at compile time.

Provider	Key	Default	Notes
Claude	`claude`	`true`	Fully supported.
Gemini	`gemini`	`false`	Work in progress. Greyed out in Settings.
Codex	`codex`	`false`	Work in progress. Greyed out in Settings.

Provider flags are defined in PROVIDER_FLAGS in src/lib/feature-flags.ts. Disabled providers are hidden from dashboards and session data.

export const PROVIDER_FLAGS: Record<LlmProviderId, boolean> = {
  claude: true,
  gemini: false,
  codex: false,
};

Feature Flag Registry

The FEATURE_FLAG_REGISTRY array in src/lib/feature-flags.ts is the single source of truth for all feature flags. Each entry has three fields:

Field	Type	Description
`key`	`string`	Unique identifier stored in `settings.featureFlags`. Use `snake_case`.
`label`	`string`	Human-readable label shown in the Settings UI toggle.
`description`	`string`	Short description shown below the toggle.

The registry is currently empty in the open-source release. Add entries here when developing new features that need a gate.

Gating Code with Feature Flags

Frontend (TypeScript / React)

Use isFeatureEnabled from the settings store:

import { useSettingsStore } from "@/store/settings";

// In a component or hook:
const enabled = useSettingsStore.getState().isFeatureEnabled("your_flag_key");

// Or reactively in a component:
const enabled = useSettingsStore((s) => s.isFeatureEnabled("your_flag_key"));

isFeatureEnabled returns true only when both developerMode and the flag itself are true.

Backend (Rust)

Use is_feature_enabled on the settings struct:

if settings.is_feature_enabled("your_flag_key") {
    // experimental code path
}

Adding a New Feature Flag

Add an entry to FEATURE_FLAG_REGISTRY in src/lib/feature-flags.ts:

export const FEATURE_FLAG_REGISTRY: FeatureFlagEntry[] = [
  {
    key: "my_new_feature",
    label: "My New Feature",
    description: "Enables the experimental my-new-feature behaviour.",
  },
];

Gate your frontend code:

if (useSettingsStore.getState().isFeatureEnabled("my_new_feature")) {
  // ...
}

Gate your backend code (if needed):

if settings.is_feature_enabled("my_new_feature") {
  // ...
}

The toggle will appear automatically in Settings → Developer → Feature Flags. No additional UI wiring is required.