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

> Discover how the thinking-levels configuration in Craft Agents controls extended reasoning depth for predictable speed vs. depth trade-offs in your models.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: deep-dive
- Published: 2026-07-06

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/agent/thinking-levels.ts) (lines 4-10).

## Core Implementation in [`thinking-levels.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/thinking-levels.ts)

The [`packages/shared/src/agent/thinking-levels.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/config/validators.ts)**: Validates persisted configuration using the canonical list.
- **[`packages/shared/src/agent/base-agent.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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

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

```

### Validating User Input

```typescript
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

```typescript
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

```typescript
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

```tsx
<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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/config/validators.ts).