Understanding the Thinking-Levels Configuration for Extended Reasoning Models in Craft Agents

The thinking-levels configuration defines a six-tier hierarchy that controls how much extended reasoning a model applies to a request, enabling developers to trade off speed versus depth of reasoning in a predictable, provider-agnostic way.

The Craft Agents OSS repository implements a sophisticated reasoning control system through its thinking-levels module. This thinking-levels configuration for extended reasoning models provides a standardized interface for managing computational depth across different AI providers, ensuring consistent behavior whether you are using Anthropic's Claude or other model families. The architecture centralizes all reasoning-related constants and mappings in a single source file to maintain consistency across the UI, validation logic, and runtime execution.

The Six-Tier Reasoning Hierarchy

The configuration establishes a graduated scale from zero reasoning to maximum computational effort. Each tier maps to specific use cases and latency requirements.

• off: Disables extended reasoning entirely. Use this for simple pass-through calls or benchmarking baseline performance.
• low: Applies light reasoning for fast responses. Ideal for quick answers and low-latency UI interactions.
• medium: Provides balanced speed and reasoning depth. This is the default tier for general-purpose interactions.
• high: Enables deep reasoning for complex tasks. Suitable for multi-step problem solving workflows.
• xhigh: Offers extra-high reasoning, specifically designed for Anthropic's recommended level for Opus-style coding agents handling heavy-weight code generation.
• max: Activates maximum effort reasoning for exhaustive analysis and research-grade output.

These definitions are documented in the header of packages/shared/src/agent/thinking-levels.ts (lines 4-10).

Core Implementation in thinking-levels.ts

The packages/shared/src/agent/thinking-levels.ts file serves as the single source of truth for all reasoning-related configuration.

Canonical identifiers are stored in THINKING_LEVEL_IDS, an ordered array that defines the valid options for the entire system (lines 28-35). UI components and validation logic derive their options from this array to ensure consistency.

Metadata for internationalization is provided by the THINKING_LEVELS constant, which supplies translation keys for each tier (lines 53-60). This enables localized dropdown menus and tooltips in the Electron interface.

Default behavior is controlled by DEFAULT_THINKING_LEVEL, which is set to 'medium' (lines 62-63). New sessions automatically inherit this value when no explicit override exists in the workspace configuration.

Provider-Specific Mapping and Token Allocation

The abstraction layer handles provider differences through two primary mechanisms.

Anthropic adaptive thinking uses the THINKING_TO_EFFORT map (lines 70-77). This converts Craft's tier names into Anthropic's SDK effort parameter:

• 'high' maps to 'high'
• 'medium' maps to 'medium'
• 'low' maps to 'low'
• 'off' returns null, which disables adaptive thinking entirely

Token budget fallback applies to models that do not support adaptive thinking. The getThinkingTokens function (lines 88-104) returns a token budget based on the selected tier and model family. For example, Haiku models receive different budget calculations than the default model family, ensuring appropriate resource allocation across hardware constraints.

Validation and Backward Compatibility

The system includes robust utilities for handling user input and legacy data.

isValidThinkingLevel validates incoming values against the canonical THINKING_LEVEL_IDS list (lines 33-35). This prevents invalid configurations from propagating through the system.

normalizeThinkingLevel rewrites legacy "think" values to the current 'medium' tier (lines 46-49). This ensures backward compatibility when loading older workspace configurations or session data.

These validators are integrated into the Zod schema defined in packages/shared/src/config/validators.ts, which uses THINKING_LEVEL_IDS to validate session and workspace configurations at runtime.

Integration Across the Codebase

The thinking-levels configuration propagates through several key components:

• packages/shared/src/config/validators.ts: Validates persisted configuration using the canonical list.
• packages/shared/src/agent/base-agent.ts: Applies DEFAULT_THINKING_LEVEL and normalizes persisted values during agent initialization.
• apps/electron/src/renderer/pages/settings/AiSettingsPage.tsx: Renders the UI dropdown for user selection (line 26).
• apps/electron/src/renderer/components/app-shell/input/CompactModelSelector.tsx: Displays model-selection badges including thinking-level overrides.
• packages/server-core/src/sessions/SessionManager.ts: Consumes the configuration when creating new sessions.

This architecture ensures that any change to the tier definitions automatically propagates to validation logic, UI components, and runtime behavior.

Practical Implementation Examples

Importing the Configuration

import {
  THINKING_LEVELS,
  DEFAULT_THINKING_LEVEL,
  getThinkingTokens,
  isValidThinkingLevel,
  normalizeThinkingLevel,
} from '@craft-agent/shared/agent/thinking-levels';

Validating User Input

function setSessionThinkingLevel(raw: unknown) {
  const level = normalizeThinkingLevel(raw);
  if (!isValidThinkingLevel(level)) {
    throw new Error('Invalid thinking level');
  }
  // Store `level` in the session config
  return level;
}

Retrieving Token Budgets

const modelId = 'claude-sonnet-3.5-20241015';
const level = 'high';
const tokenBudget = getThinkingTokens(level, modelId);
console.log(`Allocate ${tokenBudget} thinking tokens for ${level} on ${modelId}`);

Mapping to Anthropic API Calls

import { THINKING_TO_EFFORT } from '@craft-agent/shared/agent/thinking-levels';

function makeAnthropicCall(level: ThinkingLevel) {
  const effort = THINKING_TO_EFFORT[level];
  return anthropicClient.complete({
    model: 'claude-3-opus-20240229',
    // If `effort` is null, adaptive thinking is disabled
    ...(effort ? { thinking: { type: 'adaptive', effort } } : {}),
  });
}

Populating a UI Dropdown

<Select
  label="Thinking Level"
  value={currentLevel}
  onChange={(e) => setSessionThinkingLevel(e.target.value)}
>
  {THINKING_LEVELS.map((lvl) => (
    <option key={lvl.id} value={lvl.id}>
      {t(lvl.nameKey)}
    </option>
  ))}
</Select>

Summary

• The thinking-levels configuration provides a six-tier hierarchy (off, low, medium, high, xhigh, max) for controlling extended reasoning depth.
• All definitions reside in packages/shared/src/agent/thinking-levels.ts, serving as a single source of truth for the entire application.
• Anthropic models use the THINKING_TO_EFFORT map to convert tiers to SDK parameters, while other models rely on getThinkingTokens for budget allocation.
• The default level is 'medium', validated through isValidThinkingLevel and normalized via normalizeThinkingLevel for backward compatibility.
• The configuration propagates through validation schemas, session managers, and React components to ensure consistent behavior across the stack.

Frequently Asked Questions

What is the default thinking level in Craft Agents?

The default thinking level is 'medium', defined as DEFAULT_THINKING_LEVEL in packages/shared/src/agent/thinking-levels.ts (lines 62-63). New sessions automatically inherit this value unless explicitly overridden in the workspace configuration or user settings.

How does the configuration map to Anthropic's API parameters?

The THINKING_TO_EFFORT map converts Craft's tier names directly to Anthropic's effort parameter values. For example, selecting 'high' passes effort: 'high' to the Anthropic SDK. The 'off' tier returns null, which disables adaptive thinking entirely rather than passing an effort value.

Can I use thinking levels with models that do not support adaptive thinking?

Yes. For models lacking native adaptive thinking support, the system falls back to token budget allocation via getThinkingTokens. This function calculates appropriate thinking token limits based on the selected tier and model family (such as Haiku versus standard models), ensuring consistent behavior across different providers.

How does the system handle invalid or legacy thinking level values?

The normalizeThinkingLevel function rewrites legacy "think" values to the current 'medium' tier, ensuring backward compatibility. Subsequently, isValidThinkingLevel validates the normalized value against the canonical THINKING_LEVEL_IDS list. Invalid values are rejected during configuration validation in packages/shared/src/config/validators.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}