diff --git a/FEATURES.md b/FEATURES.md index 8fd99b2..8ac0e47 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -1,197 +1,316 @@ -# Feature Flags +# Feature Flags Audit -This repository has two different "experimental" mechanisms: +Audit date: 2026-03-31 -1. `bun run build:dev` - Builds a dev-stamped binary (`cli-dev`) and marks it as an experimental build. - It does not automatically enable every compile-time feature flag in the source. +This repository currently references 88 `feature('FLAG')` compile-time flags. +I re-checked them by bundling the CLI once per flag on top of the current +external-build defines and externals. Result: -2. `feature('FLAG_NAME')` - Bun compile-time flags that include or strip code paths at build time. +- 54 flags bundle cleanly in this snapshot +- 34 flags still fail to bundle + +Important: "bundle cleanly" does not always mean "runtime-safe". Some flags +still depend on optional native modules, claude.ai OAuth, GrowthBook gates, or +externalized `@ant/*` packages. ## Build Variants - `bun run build` Builds the regular external binary at `./cli`. +- `bun run compile` + Builds the regular external binary at `./dist/cli`. - `bun run build:dev` - Builds `./cli-dev` with a `-dev.YYYYMMDD.tHHMMSS.sha...` version and the experimental GrowthBook client key. + Builds `./cli-dev` with a dev-stamped version and experimental GrowthBook key. - `bun run build:dev:full` - Builds `./cli-dev` with the snapshot-safe experimental bundle listed below. + Builds `./cli-dev` with the current compile-safe experimental bundle: + `QUICK_SEARCH`, `HISTORY_PICKER`, `TOKEN_BUDGET`, `ULTRAPLAN`, + `CACHED_MICROCOMPACT`, and `PROMPT_CACHE_BREAK_DETECTION`. -## Snapshot-Safe Experimental Bundle +## Default Build Flags -The following flags were smoke-tested against this leaked source snapshot and compile successfully together: - -- `QUICK_SEARCH` - Enables prompt quick-search UI paths. -- `HISTORY_PICKER` - Enables interactive prompt history picker UI. -- `TOKEN_BUDGET` - Enables token budget tracking and related UI warnings. - `VOICE_MODE` - Enables voice-mode UI and command paths. - Runtime still depends on optional native audio support. + This is now included in the default build pipeline, not just the dev build. + It enables `/voice`, push-to-talk UI, voice notices, and dictation plumbing. + Runtime still depends on claude.ai OAuth plus either the native audio module + or a fallback recorder such as SoX. + +## Working Experimental Features + +These are the user-facing or behavior-changing flags that currently bundle +cleanly and should still be treated as experimental in this snapshot unless +explicitly called out as default-on. + +### Interaction and UI Experiments + +- `AWAY_SUMMARY` + Adds away-from-keyboard summary behavior in the REPL. +- `HISTORY_PICKER` + Enables the interactive prompt history picker. +- `HOOK_PROMPTS` + Passes the prompt/request text into hook execution flows. +- `KAIROS_BRIEF` + Enables brief-only transcript layout and BriefTool-oriented UX without the + full assistant stack. +- `KAIROS_CHANNELS` + Enables channel notices and channel callback plumbing around MCP/channel + messaging. +- `LODESTONE` + Enables deep-link / protocol-registration related flows and settings wiring. +- `MESSAGE_ACTIONS` + Enables message action entrypoints in the interactive UI. +- `NEW_INIT` + Enables the newer `/init` decision path. +- `QUICK_SEARCH` + Enables prompt quick-search behavior. +- `SHOT_STATS` + Enables additional shot-distribution stats views. +- `TOKEN_BUDGET` + Enables token budget tracking, prompt triggers, and token warning UI. - `ULTRAPLAN` - Enables ultraplan command and prompt-input triggers. + Enables `/ultraplan`, prompt triggers, and exit-plan affordances. +- `ULTRATHINK` + Enables the extra thinking-depth mode switch. +- `VOICE_MODE` + Enables voice toggling, dictation keybindings, voice notices, and voice UI. + +### Agent, Memory, and Planning Experiments + +- `AGENT_MEMORY_SNAPSHOT` + Stores extra custom-agent memory snapshot state in the app. +- `AGENT_TRIGGERS` + Enables local cron/trigger tools and bundled trigger-related skills. +- `AGENT_TRIGGERS_REMOTE` + Enables the remote trigger tool path. +- `BUILTIN_EXPLORE_PLAN_AGENTS` + Enables built-in explore/plan agent presets. - `CACHED_MICROCOMPACT` - Enables cached microcompact plumbing. + Enables cached microcompact state through query and API flows. +- `COMPACTION_REMINDERS` + Enables reminder copy around compaction and attachment flows. +- `EXTRACT_MEMORIES` + Enables post-query memory extraction hooks. - `PROMPT_CACHE_BREAK_DETECTION` - Enables cache-break detection around compact/query flow. + Enables cache-break detection around compaction/query/API flow. +- `TEAMMEM` + Enables team-memory files, watcher hooks, and related UI messages. +- `VERIFICATION_AGENT` + Enables verification-agent guidance in prompts and task/todo tooling. -These are the flags used by `build:dev:full`. +### Tools, Permissions, and Remote Experiments -`CHICAGO_MCP` compiles from this snapshot, but the resulting binary is not -runtime-safe because it reaches unresolved `@ant/*` computer-use modules. -It is intentionally excluded from `build:dev:full`. +- `BASH_CLASSIFIER` + Enables classifier-assisted bash permission decisions. +- `BRIDGE_MODE` + Enables Remote Control / REPL bridge command and entitlement paths. +- `CCR_AUTO_CONNECT` + Enables the CCR auto-connect default path. +- `CCR_MIRROR` + Enables outbound-only CCR mirror sessions. +- `CCR_REMOTE_SETUP` + Enables the remote setup command path. +- `CHICAGO_MCP` + Enables computer-use MCP integration paths and wrapper loading. +- `CONNECTOR_TEXT` + Enables connector-text block handling in API/logging/UI paths. +- `MCP_RICH_OUTPUT` + Enables richer MCP UI rendering. +- `NATIVE_CLIPBOARD_IMAGE` + Enables the native macOS clipboard image fast path. +- `POWERSHELL_AUTO_MODE` + Enables PowerShell-specific auto-mode permission handling. +- `TREE_SITTER_BASH` + Enables the tree-sitter bash parser backend. +- `TREE_SITTER_BASH_SHADOW` + Enables the tree-sitter bash shadow rollout path. +- `UNATTENDED_RETRY` + Enables unattended retry behavior in API retry flows. -## Flags Present In Source +## Bundle-Clean Support Flags -The codebase references these compile-time flags: +These also bundle cleanly, but they are mostly rollout, platform, telemetry, +or plumbing toggles rather than user-facing experimental features. - `ABLATION_BASELINE` -- `AGENT_MEMORY_SNAPSHOT` -- `AGENT_TRIGGERS` -- `AGENT_TRIGGERS_REMOTE` + CLI ablation/baseline entrypoint toggle. - `ALLOW_TEST_VERSIONS` + Allows test versions in native installer flows. - `ANTI_DISTILLATION_CC` -- `AUTO_THEME` -- `AWAY_SUMMARY` -- `BASH_CLASSIFIER` -- `BG_SESSIONS` + Adds anti-distillation request metadata. - `BREAK_CACHE_COMMAND` -- `BRIDGE_MODE` -- `BUDDY` -- `BUILDING_CLAUDE_APPS` -- `BUILTIN_EXPLORE_PLAN_AGENTS` -- `BYOC_ENVIRONMENT_RUNNER` -- `CACHED_MICROCOMPACT` -- `CCR_AUTO_CONNECT` -- `CCR_MIRROR` -- `CCR_REMOTE_SETUP` -- `CHICAGO_MCP` -- `COMMIT_ATTRIBUTION` -- `COMPACTION_REMINDERS` -- `CONNECTOR_TEXT` -- `CONTEXT_COLLAPSE` -- `COORDINATOR_MODE` + Injects the break-cache command path. - `COWORKER_TYPE_TELEMETRY` -- `DAEMON` -- `DIRECT_CONNECT` + Adds coworker-type telemetry fields. - `DOWNLOAD_USER_SETTINGS` + Enables settings-sync pull paths. - `DUMP_SYSTEM_PROMPT` -- `ENHANCED_TELEMETRY_BETA` -- `EXPERIMENTAL_SKILL_SEARCH` -- `EXTRACT_MEMORIES` + Enables the system-prompt dump path. - `FILE_PERSISTENCE` -- `FORK_SUBAGENT` + Enables file persistence plumbing. - `HARD_FAIL` -- `HISTORY_PICKER` -- `HISTORY_SNIP` -- `HOOK_PROMPTS` + Enables stricter failure/logging behavior. - `IS_LIBC_GLIBC` + Forces glibc environment detection. - `IS_LIBC_MUSL` -- `KAIROS` -- `KAIROS_BRIEF` -- `KAIROS_CHANNELS` -- `KAIROS_DREAM` -- `KAIROS_GITHUB_WEBHOOKS` -- `KAIROS_PUSH_NOTIFICATION` -- `LODESTONE` -- `MCP_RICH_OUTPUT` -- `MCP_SKILLS` -- `MEMORY_SHAPE_TELEMETRY` -- `MESSAGE_ACTIONS` -- `MONITOR_TOOL` + Forces musl environment detection. - `NATIVE_CLIENT_ATTESTATION` -- `NATIVE_CLIPBOARD_IMAGE` -- `NEW_INIT` -- `OVERFLOW_TEST_TOOL` + Adds native attestation marker text in the system header. - `PERFETTO_TRACING` -- `POWERSHELL_AUTO_MODE` -- `PROACTIVE` -- `PROMPT_CACHE_BREAK_DETECTION` -- `QUICK_SEARCH` -- `REACTIVE_COMPACT` -- `REVIEW_ARTIFACT` -- `RUN_SKILL_GENERATOR` -- `SELF_HOSTED_RUNNER` -- `SHOT_STATS` + Enables perfetto tracing hooks. - `SKILL_IMPROVEMENT` + Enables skill-improvement hooks. +- `SKIP_DETECTION_WHEN_AUTOUPDATES_DISABLED` + Skips updater detection when auto-updates are disabled. - `SLOW_OPERATION_LOGGING` -- `SSH_REMOTE` -- `TEAMMEM` -- `TEMPLATES` -- `TERMINAL_PANEL` -- `TOKEN_BUDGET` -- `TORCH` -- `TRANSCRIPT_CLASSIFIER` -- `TREE_SITTER_BASH` -- `TREE_SITTER_BASH_SHADOW` -- `UDS_INBOX` -- `ULTRAPLAN` -- `ULTRATHINK` -- `UNATTENDED_RETRY` + Enables slow-operation logging. - `UPLOAD_USER_SETTINGS` -- `VERIFICATION_AGENT` + Enables settings-sync push paths. + +## Compile-Safe But Runtime-Caveated + +These bundle today, but I would still treat them as experimental because they +have meaningful runtime caveats: + - `VOICE_MODE` + Bundles cleanly, but requires claude.ai OAuth and a local recording backend. + The native audio module is optional now; on this machine the fallback path + asks for `brew install sox`. +- `NATIVE_CLIPBOARD_IMAGE` + Bundles cleanly, but only accelerates macOS clipboard reads when + `image-processor-napi` is present. +- `BRIDGE_MODE`, `CCR_AUTO_CONNECT`, `CCR_MIRROR`, `CCR_REMOTE_SETUP` + Bundle cleanly, but are gated at runtime on claude.ai OAuth plus GrowthBook + entitlement checks. +- `KAIROS_BRIEF`, `KAIROS_CHANNELS` + Bundle cleanly, but they do not restore the full missing assistant stack. + They only expose the brief/channel-specific surfaces that still exist. +- `CHICAGO_MCP` + Bundles cleanly, but the runtime path still reaches externalized + `@ant/computer-use-*` packages. This is compile-safe, not fully + runtime-safe, in the external snapshot. +- `TEAMMEM` + Bundles cleanly, but only does useful work when team-memory config/files are + actually enabled in the environment. + +## Broken Flags With Easy Reconstruction Paths + +These are the failed flags where the current blocker looks small enough that a +focused reconstruction pass could probably restore them without rebuilding an +entire subsystem. + +- `AUTO_THEME` + Fails on missing `src/utils/systemThemeWatcher.js`. `systemTheme.ts` and the + theme provider already contain the cache/parsing logic, so the missing piece + looks like the OSC 11 watcher only. +- `BG_SESSIONS` + Fails on missing `src/cli/bg.js`. The CLI fast-path dispatch in + `src/entrypoints/cli.tsx` is already wired. +- `BUDDY` + Fails on missing `src/commands/buddy/index.js`. The buddy UI components and + prompt-input hooks already exist. +- `BUILDING_CLAUDE_APPS` + Fails on missing `src/claude-api/csharp/claude-api.md`. This looks like an + asset/document gap, not a missing runtime subsystem. +- `COMMIT_ATTRIBUTION` + Fails on missing `src/utils/attributionHooks.js`. Setup and cache-clear code + already call into that hook module. +- `FORK_SUBAGENT` + Fails on missing `src/commands/fork/index.js`. Command slot and message + rendering support are already present. +- `HISTORY_SNIP` + Fails on missing `src/commands/force-snip.js`. The surrounding SnipTool and + query/message comments are already there. +- `KAIROS_GITHUB_WEBHOOKS` + Fails on missing `src/tools/SubscribePRTool/SubscribePRTool.js`. The command + slot and some message handling already exist. +- `KAIROS_PUSH_NOTIFICATION` + Fails on missing `src/tools/PushNotificationTool/PushNotificationTool.js`. + The tool slot already exists in `src/tools.ts`. +- `MCP_SKILLS` + Fails on missing `src/skills/mcpSkills.js`. `mcpSkillBuilders.ts` already + exists specifically to support that missing registry layer. +- `MEMORY_SHAPE_TELEMETRY` + Fails on missing `src/memdir/memoryShapeTelemetry.js`. The hook call sites + are already in place in `sessionFileAccessHooks.ts`. +- `OVERFLOW_TEST_TOOL` + Fails on missing `src/tools/OverflowTestTool/OverflowTestTool.js`. This + appears isolated and test-only. +- `RUN_SKILL_GENERATOR` + Fails on missing `src/runSkillGenerator.js`. The bundled skill registration + path already expects it. +- `TEMPLATES` + Fails on missing `src/cli/handlers/templateJobs.js`. The CLI fast-path is + already wired in `src/entrypoints/cli.tsx`. +- `TORCH` + Fails on missing `src/commands/torch.js`. This looks like a single command + entry gap. +- `TRANSCRIPT_CLASSIFIER` + The first hard failure is missing + `src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt`. + The classifier engine, parser, and settings plumbing already exist, so the + missing prompt/assets are likely the first reconstruction target. + +## Broken Flags With Partial Wiring But Medium-Sized Gaps + +These do have meaningful surrounding code, but the missing piece is larger +than a single wrapper or asset. + +- `BYOC_ENVIRONMENT_RUNNER` + Missing `src/environment-runner/main.js`. +- `CONTEXT_COLLAPSE` + Missing `src/tools/CtxInspectTool/CtxInspectTool.js`. +- `COORDINATOR_MODE` + Missing `src/coordinator/workerAgent.js`. +- `DAEMON` + Missing `src/daemon/workerRegistry.js`. +- `DIRECT_CONNECT` + Missing `src/server/parseConnectUrl.js`. +- `EXPERIMENTAL_SKILL_SEARCH` + Missing `src/services/skillSearch/localSearch.js`. +- `MONITOR_TOOL` + Missing `src/tools/MonitorTool/MonitorTool.js`. +- `REACTIVE_COMPACT` + Missing `src/services/compact/reactiveCompact.js`. +- `REVIEW_ARTIFACT` + Missing `src/hunter.js`. +- `SELF_HOSTED_RUNNER` + Missing `src/self-hosted-runner/main.js`. +- `SSH_REMOTE` + Missing `src/ssh/createSSHSession.js`. +- `TERMINAL_PANEL` + Missing `src/tools/TerminalCaptureTool/TerminalCaptureTool.js`. +- `UDS_INBOX` + Missing `src/utils/udsMessaging.js`. - `WEB_BROWSER_TOOL` + Missing `src/tools/WebBrowserTool/WebBrowserTool.js`. - `WORKFLOW_SCRIPTS` + Fails first on `src/commands/workflows/index.js`, but there are more gaps: + `tasks.ts` already expects `LocalWorkflowTask`, and `tools.ts` expects a + real `WorkflowTool` implementation while only `WorkflowTool/constants.ts` + exists in this snapshot. -## High-Traffic Feature Families +## Broken Flags With Large Missing Subsystems -These are the most prominent feature families in the snapshot: - -- Assistant / brief / channels - `KAIROS`, `KAIROS_BRIEF`, `KAIROS_CHANNELS`, `KAIROS_GITHUB_WEBHOOKS`, `KAIROS_PUSH_NOTIFICATION`, `KAIROS_DREAM` -- Classifiers / auto mode - `TRANSCRIPT_CLASSIFIER`, `BASH_CLASSIFIER`, `TREE_SITTER_BASH`, `TREE_SITTER_BASH_SHADOW` -- Remote / bridge / computer-use - `BRIDGE_MODE`, `DAEMON`, `DIRECT_CONNECT`, `SSH_REMOTE`, `CHICAGO_MCP`, `WEB_BROWSER_TOOL` -- Planning / agents / automation - `ULTRAPLAN`, `COORDINATOR_MODE`, `FORK_SUBAGENT`, `AGENT_TRIGGERS`, `AGENT_TRIGGERS_REMOTE`, `VERIFICATION_AGENT` -- Context / compact / memory - `CONTEXT_COLLAPSE`, `REACTIVE_COMPACT`, `CACHED_MICROCOMPACT`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`, `HISTORY_SNIP`, `BG_SESSIONS`, `TEAMMEM`, `EXTRACT_MEMORIES` -- UI extras - `QUICK_SEARCH`, `HISTORY_PICKER`, `VOICE_MODE`, `MESSAGE_ACTIONS`, `AUTO_THEME`, `SHOT_STATS` - -## Known Broken In This Snapshot - -These flags do appear in source, but turning them on currently fails to build because referenced modules are missing from the leaked snapshot: +These are the ones that still look expensive to restore because the first +missing import is only the visible edge of a broader absent subsystem. - `KAIROS` -- `KAIROS_BRIEF` + Missing `src/assistant/index.js` and much of the assistant stack with it. +- `KAIROS_DREAM` + Missing `src/dream.js` and related dream-task behavior. - `PROACTIVE` -- `BRIDGE_MODE` -- `DAEMON` -- `DIRECT_CONNECT` -- `SSH_REMOTE` -- `COORDINATOR_MODE` -- `CHICAGO_MCP` -- `BUDDY` -- `UDS_INBOX` -- `CONTEXT_COLLAPSE` -- `REACTIVE_COMPACT` -- `EXPERIMENTAL_SKILL_SEARCH` -- `MCP_SKILLS` -- `WORKFLOW_SCRIPTS` -- `MONITOR_TOOL` -- `REVIEW_ARTIFACT` -- `TEAMMEM` -- `TRANSCRIPT_CLASSIFIER` - -The failures are mostly missing files such as assistant-mode modules, remote/server modules, workflow/monitor tools, skill-search modules, classifier prompt files, and team-memory helpers. + Missing `src/proactive/index.js` and the proactive task/tool stack. ## Useful Entry Points - Feature-aware build logic: [scripts/build.ts](/Users/paolo/Repos/claude-code/scripts/build.ts) -- Experimental GrowthBook key selection: - [src/constants/keys.ts](/Users/paolo/Repos/claude-code/src/constants/keys.ts) - Feature-gated command imports: [src/commands.ts](/Users/paolo/Repos/claude-code/src/commands.ts) - Feature-gated tool imports: [src/tools.ts](/Users/paolo/Repos/claude-code/src/tools.ts) +- Feature-gated task imports: + [src/tasks.ts](/Users/paolo/Repos/claude-code/src/tasks.ts) - Feature-gated query behavior: [src/query.ts](/Users/paolo/Repos/claude-code/src/query.ts) -- Feature-gated CLI options and startup flow: - [src/main.tsx](/Users/paolo/Repos/claude-code/src/main.tsx) +- Feature-gated CLI entry paths: + [src/entrypoints/cli.tsx](/Users/paolo/Repos/claude-code/src/entrypoints/cli.tsx)