PostHog Feature Flags¶

All feature flags are defined in app/feature_flags/flags.py and evaluated via app/feature_flags/posthog_client.py.

Quick Reference¶

from app.feature_flags import get_flag, get_config

# Boolean flag
if get_flag("free-tier-enabled", default=True):
    enforce_limits()

# Config value with clamping
max_tokens = get_config("llm-max-tokens-reflex", default=1500, min_value=100, max_value=4000)

Flag Classes¶

LLMTokenLimits¶

Flag Key	Type	Default	Description
`llm-max-tokens-reflex`	config	1500	Max tokens for reflex responses
`llm-max-tokens-deep-reasoning`	config	2000	Max tokens for deep reasoning
`llm-max-tokens-default`	config	1000	Max tokens for default conversations
`llm-max-tokens-vision`	config	1500	Max tokens for vision analysis

PipelineFlags¶

Flag Key	Type	Default	Description
`pipeline-classifier-v2-enabled`	bool	false	Enable combined classifier v2
`llm-force-basic-mode`	bool	false	Emergency kill-switch for expensive features

CacheFlags¶

Flag Key	Type	Default	Description
`cache-response-enabled`	bool	true	Enable Redis-backed response caching
`cache-memory-ttl-seconds`	config	300	Memory search cache TTL (seconds)
`cache-llm-response-ttl-seconds`	config	3600	LLM response cache TTL (seconds)

WorkflowFlags¶

Flag Key	Type	Default	Description
`workflow-calendar-v2`	bool	false	Enable calendar workflow v2
`workflow-email-urgency`	bool	true	Enable email urgency detection

ContextFlags¶

Flag Key	Type	Default	Description
`context-reduced-history-enabled`	bool	false	Enable reduced conversation history
`context-max-messages`	config	10	Max messages in conversation context

MediaFlags¶

Flag Key	Type	Default	Description
`media-photo-batching-enabled`	bool	false	Enable photo batching
`media-photo-batch-size`	config	3	Photos to batch together

ObservabilityFlags¶

Flag Key	Type	Default	Description
`metrics-token-monitoring-enabled`	bool	true	Token usage monitoring
`metrics-detailed-logging-enabled`	bool	false	Detailed request/response logging

PaymentFlags¶

Flag Key	Type	Default	Description
`payment-stripe-enabled`	bool	true	Enable Stripe payments
`payment-monthly-price-cents`	config	799	Monthly price ($7.99)
`payment-annual-price-cents`	config	5000	Annual price ($50)
`payment-paywall-enabled`	bool	false	Require payment before access
`payment-stripe-test-mode`	bool	false	Use Stripe test keys
`payment-topup-enabled`	bool	true	Enable credit top-ups
`payment-topup-min-amount-cents`	config	500	Min top-up ($5.00)
`payment-topup-max-amount-cents`	config	10000	Max top-up ($100.00)

FreeTierFlags¶

Flag Key	Type	Default	Description
`free-tier-enabled`	bool	true	Master switch for free tier
`free-tier-daily-message-limit`	config	50	Daily message limit (free)
`free-tier-superpowers-disabled`	bool	true	Disable superpowers for free users

CompanionProgressionFlags¶

Flag Key	Type	Default	Description
`progression-enabled`	bool	true	Master switch for progression
`progression-level-computation-enabled`	bool	true	Level recomputation after messages
`progression-slot-system-enabled`	bool	true	Enforce loadout slot limits
`progression-streak-tracking-enabled`	bool	false	Consecutive-day streak tracking
`progression-level-up-messages-enabled`	bool	true	In-persona level-up messages
`progression-derive-stage-from-level-enabled`	bool	true	Derive stage from level
`progression-persona-modifiers-enabled`	bool	true	Memory-driven persona modifiers

GroupChatFlags¶

Flag Key	Type	Default	Description
`group-first-contact-message-enabled`	bool	true	Send norms message on first join
`group-escalation-to-dm-enabled`	bool	true	Redirect personal requests to DM
`group-friction-cooldown-enabled`	bool	true	Detect "shut up" and go silent
`group-friction-cooldown-seconds`	config	7200	Friction cooldown duration (2h)

RateLimitFlags¶

Flag Key	Type	Default	Description
`rate-limit-enabled`	bool	true	Enable rate limiting
`rate-limit-message-budget-threshold`	config	5	Messages before unprompted AI
`rate-limit-commands-per-minute`	config	10	Max commands/min/user
`rate-limit-miniapp-actions-per-minute`	config	20	Max miniapp actions/min
`rate-limit-user-messages-per-minute`	config	20	Max messages/min
`rate-limit-photos-per-hour`	config	50	Max photos/hour
`rate-limit-strict-mode-enabled`	bool	false	Strict rate limiting
`rate-limit-strict-mode-multiplier`	config	0.5	Strict mode multiplier

SuperpowerFlags¶

Master switch plus individual superpower toggles. Dev defaults: all true. Prod defaults: all false.

Flag Key	Description
`superpower-enabled`	Master switch
`superpower-user-created-enabled`	User-created custom superpowers
`superpower-calendar-morning-enabled`	Morning calendar brief
`superpower-calendar-events-enabled`	Calendar change monitoring
`superpower-email-urgency-enabled`	Email urgency scanning
`superpower-trip-planner-enabled`	Trip planning
`superpower-bill-split-enabled`	Bill splitting
...	(27 total superpower flags)

CharacterCastFlags (PRD 13)¶

All default to false (not yet launched).

Flag Key	Type	Default	Description
`cast-enabled`	bool	false	Master switch for Cast System
`cast-top3-matching-enabled`	bool	false	Top-3 picker matching
`cast-max-companion-slots`	config	4	Max active companions
`cast-companion-switch-cooldown-days`	config	7	Primary slot swap cooldown
...			(19 total cast flags)

Architecture¶

Client: posthog_client.py - PostHog SDK with circuit breaker, thread-safe init
Flags: flags.py - All flag key constants with defaults
Init: Called in app/main.py lifespan via initialize_posthog_flags()
Evaluation: Uses service-level distinct_id = "orchestrator-backend" (flags aren't user-scoped)
Fallback: Circuit breaker opens after 3 failures, retries after 60s
Environment: POSTHOG_API_KEY and optionally POSTHOG_PERSONAL_API_KEY for local evaluation