417 Ecomode F42e5d09

Ecomode - Smart Model Routing

Ecomode automatically routes tasks to the appropriate Claude model (haiku/sonnet/opus) based on task complexity analysis.

Overview

Instead of always using the most expensive model, Ecomode analyzes task characteristics and selects the optimal model for cost/performance balance.

Location: ecomode/

Complexity Scoring

The complexity scorer analyzes multiple factors to produce a normalized score.

Scoring Factors

Keyword Patterns

File Count Scoring

Agent Type Scoring

Model Routing

Default Thresholds

Modifier Keywords

BREAKING CHANGE (v2.8.0): Keywords now separate model selection from effort level.

Effort-level keywords (auto-select model):

Model-selection keywords (force model, effort from complexity):

API Reference

calculateComplexityScore

Analyzes task complexity and returns a normalized score.

import { calculateComplexityScore } from 'ecomode/complexity-scorer';

const score = calculateComplexityScore({
  title: 'Fix login authentication bug',
  description: 'Users cannot log in with valid credentials',
  fileCount: 2,
  agentId: 'qa'
});

// Result:
// {
//   score: 0.28,
//   level: 'low',
//   factors: { keywords: 0.25, fileCount: 0.35, agentType: 0.2 },
//   reasoning: 'Low complexity keywords detected (bug fix/small change/typo)'
// }

Input:

Output:

routeToModel

Routes a task to the appropriate model based on complexity and modifiers.

import { routeToModel } from 'ecomode/model-router';

const result = routeToModel({
  title: 'opus: Design authentication architecture',
  fileCount: 10,
  agentId: 'ta'
});

// Result:
// {
//   route: {
//     model: 'opus',
//     confidence: 1.0,
//     reason: 'User override: opus: → opus',
//     isOverride: true,
//     costTier: 'high'
//   },
//   complexityScore: { score: 0.73, level: 'high', ... },
//   modifier: { keyword: 'opus', targetModel: 'opus', ... }
// }

Input:

Output:

getRecommendedModel

Simple API to get just the recommended model name.

import { getRecommendedModel } from 'ecomode/model-router';

const model = getRecommendedModel('Fix typo in README', {
  fileCount: 1,
  agentId: 'doc'
});

// Result: 'haiku'

Examples

Low Complexity → Haiku

routeToModel({ title: 'Fix typo in README', fileCount: 1, agentId: 'doc' });
// → model: 'haiku', score: 0.18, level: 'trivial'

Medium Complexity → Sonnet

routeToModel({ title: 'Add user profile feature', fileCount: 5, agentId: 'me' });
// → model: 'sonnet', score: 0.52, level: 'medium'

High Complexity → Opus

routeToModel({ title: 'Architecture migration for microservices', fileCount: 15, agentId: 'ta' });
// → model: 'opus', score: 0.73, level: 'high'

Explicit Override

routeToModel({ title: 'opus: Simple bug fix' });
// → model: 'opus', isOverride: true (ignores low complexity)

Auto-Routing with eco: (Low Effort)

routeToModel({ title: 'eco: Implement new feature', fileCount: 3 });
// → model: 'sonnet' (from complexity)
// → effortLevel: 'low' (from eco: keyword)
// → reason: 'Auto-routing (eco:): Medium complexity... [effort: low]'

Auto-Routing with fast: (Medium Effort)

routeToModel({ title: 'fast: Refactor auth module', fileCount: 5 });
// → model: 'sonnet' (from complexity)
// → effortLevel: 'medium' (from fast: keyword)
// ⚠️ BREAKING: Previously forced haiku model

Auto-Routing with max: (Maximum Effort)

routeToModel({ title: 'max: Design microservices architecture', fileCount: 12 });
// → model: 'opus' (from complexity)
// → effortLevel: 'max' (from max: keyword)
// ✨ NEW in v2.8.0

Performance

The complexity scorer is optimized for speed:

• Target: < 50ms per scoring operation
• Warning logged if scoring exceeds 50ms
• Batch scoring available via calculateComplexityScores()

Configuration

Custom Thresholds

Override default routing thresholds:

routeToModel({
  title: 'My task',
  thresholds: {
    low: 0.25,   // Below this → haiku (default: 0.3)
    medium: 0.65 // Below this → sonnet, above → opus (default: 0.7)
  }
});

Environment Overrides

Set global thresholds via environment variables (used when no explicit thresholds are passed):

ECOMODE_THRESHOLD_LOW=0.25
ECOMODE_THRESHOLD_MEDIUM=0.65

Rules:

• Values must be between 0 and 1
• low must be less than medium
• Invalid values fall back to defaults

Related Documentation

• Magic Keywords - Modifier and action keywords
• Progress HUD - Real-time status display