Droid Reasoning Runtime
Relevant source files
The following files were used as context for generating this wiki page:
The Droid Reasoning Runtime is a specialized module within the CCS (Claude Code Switch) architecture responsible for managing "thinking" or "reasoning" configurations for Factory Droid targets. It facilitates the extraction, normalization, and application of reasoning effort levels across both CLI and Dashboard interfaces, ensuring that Droid models operate within specific cognitive budgets.
Sources: src/dispatcher/profile-resolver.ts:15, src/targets/droid-reasoning-runtime.ts
Core Logic and Argument Normalization
The runtime acts as a middleware during the profile resolution phase. When the droid target is identified, the system invokes reasoning runtime logic to process specific flags that are not native to the Droid CLI but are used by CCS to control model behavior.
Flag Extraction and Stripping
The runtime identifies reasoning-related flags such as --thinking or --effort. These flags are extracted to determine the desired reasoning level, and then "stripped" from the arguments passed to the underlying Droid binary to avoid command-line errors in the target CLI.
The diagram shows the flow of argument processing where CCS-specific reasoning flags are intercepted before reaching the Droid binary.
Sources: src/targets/droid-reasoning-runtime.ts, src/dispatcher/profile-resolver.ts:315-345, tests/unit/targets/droid-reasoning-runtime.test.ts:7-25
Reasoning Levels and Aliases
The runtime supports several effort levels, which are often mapped to specific token budgets or provider-specific behaviors (particularly for Anthropic-based models used via Droid).
| Level | Description | Target Support |
|---|---|---|
minimal | Lowest reasoning budget | Codex, Droid, Anthropic |
low | Reduced reasoning depth | Codex, Droid, Anthropic |
medium | Balanced performance | Codex, Droid, Anthropic |
high | Increased cognitive depth | Codex, Droid, Anthropic |
xhigh | Maximum reasoning effort | Codex, Droid, Anthropic |
Sources: src/dispatcher/profile-resolver.ts:347-355, ui/src/pages/droid.tsx:210-230
Dashboard Integration
The Droid Reasoning Runtime is exposed via the CCS Dashboard, allowing users to persist reasoning settings in the settings.json file used by the Factory Droid runtime.
Configuration Management
The dashboard utilizes the DroidByokReasoningControlsCard to manage:
- Reasoning Effort: Applying
reasoningEffortvalues directly to the model configuration. - Anthropic Budget Tokens: A specific control for Anthropic-based BYOK (Bring Your Own Key) models to define max reasoning tokens.
The sequence diagram illustrates how UI interactions trigger updates to the underlying Droid configuration files.
Sources: ui/src/pages/droid.tsx:215-255, src/web-server/services/droid-dashboard-service.ts
Diagnostics and Visibility
The runtime provides diagnostic data about the current state of Droid reasoning through the DroidByokDiagnostics interface. This includes counts of custom models, active model selectors, and provider breakdowns.
Key Diagnostic Fields:
activeModelSelector: The current model selected for reasoning tasks.customModelCount: Total number of user-defined models.invalidModelEntryCount: Tracks malformed entries in the reasoning configuration.
Sources: src/web-server/services/compatible-cli-types.ts:47-56, ui/src/pages/droid.tsx:260-280
Implementation Details
Error Handling
The runtime implements DroidReasoningFlagError to handle scenarios where reasoning flags are provided without values or with invalid levels. During CLI dispatch, this triggers an exit with an actionable error message explaining supported levels.
Sources: src/targets/droid-reasoning-runtime.ts, src/dispatcher/profile-resolver.ts:340-345
Environment Fallbacks
If no CLI flags are present, the runtime respects the CCS_THINKING environment variable as a fallback source for the reasoning level.
Sources: src/targets/droid-reasoning-runtime.test.ts:27-33, src/dispatcher/profile-resolver.ts:322
The Droid Reasoning Runtime ensures that Factory Droid remains compatible with the unified CCS "thinking" interface while maintaining the integrity of the underlying Droid CLI's configuration.