Configuration Schema

This document provides a complete reference for all configuration options.

Configuration Files

Precedence

Settings are resolved in order (highest priority first):

1. CLI flags
2. Project configuration
3. Global configuration
4. Built-in defaults

Global Configuration

File: ~/.config/codeloops/config.toml

Complete Schema

# Default settings applied to all sessions
[defaults]
# Default agent for both actor and critic roles
# Values: "claude", "opencode", "cursor"
# Default: "claude"
agent = "claude"

# Default model for both roles (optional)
# Value depends on agent (e.g., "sonnet", "opus", "gpt-4o")
# Default: none (uses agent default)
model = "sonnet"

# Actor-specific overrides (optional section)
[defaults.actor]
# Agent for actor role (overrides defaults.agent for actor)
agent = "opencode"

# Model for actor role (overrides defaults.model for actor)
model = "gpt-4o"

# Critic-specific overrides (optional section)
[defaults.critic]
# Agent for critic role (overrides defaults.agent for critic)
agent = "claude"

# Model for critic role (overrides defaults.model for critic)
model = "opus"

Section Reference

[defaults]

Base defaults for all sessions.

[defaults.actor]

Override defaults for the actor role.

[defaults.critic]

Override defaults for the critic role.

Example Configurations

Minimal (use defaults):

[defaults]
agent = "claude"

With model:

[defaults]
agent = "claude"
model = "sonnet"

Different agents per role:

[defaults]
agent = "claude"

[defaults.actor]
agent = "opencode"
model = "gpt-4o"

[defaults.critic]
model = "opus"

Project Configuration

File: <working-dir>/codeloops.toml

Complete Schema

# Default agent for this project
# Values: "claude", "opencode", "cursor"
agent = "claude"

# Default model for this project (optional)
model = "sonnet"

# Actor-specific settings (optional section)
[actor]
agent = "opencode"
model = "gpt-4o"

# Critic-specific settings (optional section)
[critic]
agent = "claude"
model = "opus"

Field Reference

Root Level

[actor]

[critic]

Example Configurations

Simple project config:

agent = "claude"

Mixed agents:

[actor]
agent = "opencode"
model = "gpt-4o-mini"

[critic]
agent = "claude"
model = "sonnet"

Valid Values

Agent Values

Model Values

Model values depend on the agent:

Claude Code:

• "sonnet" - Claude Sonnet
• "opus" - Claude Opus
• "haiku" - Claude Haiku

OpenCode:

• "gpt-4o" - GPT-4o
• "gpt-4o-mini" - GPT-4o Mini
• Other OpenAI models

Cursor:

• Uses Cursor's configured model

Resolution Examples

Example 1: No config files

Running codeloops with no config:

Example 2: Global config only

~/.config/codeloops/config.toml:

[defaults]
agent = "opencode"
model = "gpt-4o"

Running codeloops:

Example 3: Global + Project config

~/.config/codeloops/config.toml:

[defaults]
agent = "opencode"

codeloops.toml:

agent = "claude"

Running codeloops:

Example 4: CLI overrides all

~/.config/codeloops/config.toml:

[defaults]
agent = "opencode"

codeloops.toml:

agent = "claude"

Running codeloops --agent cursor:

Example 5: Per-role settings

~/.config/codeloops/config.toml:

[defaults]
agent = "claude"
model = "sonnet"

[defaults.actor]
agent = "opencode"
model = "gpt-4o"

Running codeloops:

Environment Variables

Creating Configuration

Using init

codeloops init

Interactive prompts create ~/.config/codeloops/config.toml.

Manual creation

mkdir -p ~/.config/codeloops
cat > ~/.config/codeloops/config.toml << 'EOF'
[defaults]
agent = "claude"
EOF

Validating Configuration

Use --dry-run to see resolved configuration:

codeloops --dry-run

Output shows the effective settings without executing.