CodeMachine uses a hierarchical configuration system for engine and model selection. Each layer can override the previous, giving you fine-grained control.
Agent Config
Override in main.agents.js
Workflow Step
Override in workflow.js
Available Engines
| Engine ID | Name | Default Model | Reasoning Effort |
|---|
claude | Claude Code | opus | No |
ccr | Claude Code Router | sonnet | No |
codex | Codex | gpt-5.2-codex | Yes (medium) |
opencode | OpenCode | opencode/big-pickle | No |
cursor | Cursor | auto | No |
mistral | Mistral Vibe | devstral-2 | No |
auggie | Auggie CLI | auto | No |
Engines other than claude, codex, and opencode are experimental and might not be stable.
Agent Configuration
Configure engine and model in config/main.agents.js for individual agents.
Agent Schema
{
id: string, // Unique agent identifier (required)
name: string, // Display name shown in UI (required)
description: string, // Brief description (required)
promptPath: string | string[], // Path to prompt file(s) (required)
promptPath: string[], // Chained prompt paths (optional)
engine: string, // Engine to use (optional)
model: string, // Model to use (optional)
modelReasoningEffort: string, // 'low' | 'medium' | 'high' (optional)
}
Examples
Engine + Model:
// config/main.agents.js
export const mainAgents = {
'my-code-generator': {
id: 'my-code-generator',
promptPath: 'agents/code-generator/main.prompt.md',
engine: 'claude',
model: 'opus',
},
};
'my-analyzer': {
id: 'my-analyzer',
promptPath: 'agents/analyzer/main.prompt.md',
engine: 'codex',
model: 'gpt-5.2-codex',
modelReasoningEffort: 'high',
},
'my-agent': {
id: 'my-agent',
promptPath: 'agents/my-agent/main.prompt.md',
engine: 'claude', // Uses 'opus' (Claude's default)
}
Workflow Step Overrides
Override engine and model per step in your workflow.js files.
Override Schema
{
engine: string, // Override engine
model: string, // Override model
modelReasoningEffort: string, // 'low' | 'medium' | 'high'
}
Using resolveStep()
// templates/workflows/my.workflow.js
import { resolveStep } from '#src/workflows/utils/resolvers/index.js';
export default {
id: 'my-workflow',
name: 'My Custom Workflow',
steps: [
// No overrides - uses agent's config
resolveStep('my-agent'),
// Engine override
resolveStep('code-generator', {
engine: 'claude',
}),
// Engine + model + reasoning
resolveStep('complex-analysis', {
engine: 'codex',
model: 'gpt-5.2-codex',
modelReasoningEffort: 'high',
}),
],
};
Using resolveFolder()
Apply overrides to all steps from a folder:
import { resolveFolder } from '#src/workflows/utils/resolvers/index.js';
export default {
id: 'spec-workflow',
steps: [
// All steps in 'spec-kit' folder use these settings
...resolveFolder('spec-kit', {
engine: 'codex',
model: 'gpt-5',
modelReasoningEffort: 'medium',
}),
],
};
Using resolveModule()
import { resolveModule } from '#src/workflows/utils/resolvers/index.js';
export default {
id: 'module-workflow',
steps: [
resolveModule('spec-module', {
engine: 'claude',
model: 'opus',
}),
],
};
Model Reasoning Effort
Only supported by certain engines (currently Codex).
| Value | Description |
|---|
low | Minimal reasoning, fastest response |
medium | Balanced reasoning (default for Codex) |
high | Maximum reasoning, best for complex tasks |
resolveStep('complex-analysis', {
engine: 'codex',
modelReasoningEffort: 'high',
});
Practical Examples
Fast Prototyping
Use faster, cheaper models:
export default {
id: 'prototype',
name: 'Fast Prototyping',
steps: [
resolveStep('scaffold-generator', {
engine: 'ccr',
model: 'sonnet',
}),
resolveStep('quick-test', {
engine: 'ccr',
model: 'haiku',
}),
],
};
Production Quality
Use powerful models:
export default {
id: 'production',
name: 'Production Quality',
steps: [
resolveStep('architecture-design', {
engine: 'claude',
model: 'opus',
}),
resolveStep('code-generation', {
engine: 'codex',
model: 'gpt-5.2-codex',
modelReasoningEffort: 'high',
}),
resolveStep('security-review', {
engine: 'claude',
model: 'opus',
}),
],
};
Mixed Engine Workflow
Leverage different engines for their strengths:
export default {
id: 'mixed',
name: 'Mixed Engine Workflow',
steps: [
// Claude for creative tasks
resolveStep('brainstorm', {
engine: 'claude',
model: 'opus',
}),
// Codex for complex reasoning
resolveStep('algorithm-design', {
engine: 'codex',
modelReasoningEffort: 'high',
}),
// Fast model for simple tasks
resolveStep('format-code', {
engine: 'ccr',
model: 'haiku',
}),
],
};
Engine Fallback System
When running a workflow, CodeMachine resolves the engine and model through a fallback system.
How It Works
Pick Engine
- Use step/CLI override if specified
- Else use agent config (
engine field)
- Else find first authenticated engine by order
Check Authentication
- If selected engine is not authenticated → try next authenticated engine
- If none authenticated → use registry default (first by order)
Select Model
- If engine fell back, agent’s model is ignored (uses engine’s default)
- Otherwise: step override → agent config → engine default
Default Engine & Model
Default engine: opencode (order: 1)
Default model: opencode/big-pickle
Engine Fallback Order
Engines are tried in this order when falling back:
| Order | Engine | Default Model |
|---|
| 1 | opencode | opencode/big-pickle |
| 2 | claude | opus |
| 3 | codex | gpt-5.2-codex |
| 4 | cursor | auto |
| 7 | ccr | sonnet |
If no engine is specified and opencode is authenticated, it’s used. If opencode isn’t authenticated, it tries claude, then codex, and so on.
Validation
The workflow validator checks:
model must be a string (if provided)modelReasoningEffort must be 'low', 'medium', or 'high'engine must be a valid engine ID from the registry
Invalid configurations produce descriptive error messages during workflow loading. 
