Customization Guide

Providers and presets are designed to be customized. This page covers what you should tune, what to leave alone, and how to build configurations for different agent roles and providers.

Model and sampling parameters

Swap models freely

Update the model field in your preset and the models array on the provider setup as new versions ship:

"config": {
  "model": "opus"
}

Tune temperature and tokens per role

Role	Temperature	Max tokens	Reasoning
Coder	0.1–0.2	8192	Deterministic output, room for full implementation
Reviewer	0.1	4096	Consistent evaluation, shorter output
Orchestrator	0.1	4096	Precise tool calls, structured responses
Planner	0.2–0.3	8192	Slightly creative for plan generation

Keep-alive timeouts

Value	Use case
`120000` (2 min)	Good default for most cloud providers
`300000` (5 min)	Local models or long-running sessions where reconnection is expensive

Note: keepAliveMs behavior varies by provider — Codex uses it for session idle management, Ollama passes it as keep_alive, Claude and Gemini currently ignore it.

Worktree policy by role

Scenario	`shouldCreateWorktree`	`allowReuseExistingWorktree`
Coding tasks	`true`	`true` — allows multi-step work on the same branch
Code reviews	`true`	`true` — reviewer needs the executor’s worktree
Orchestration	`false`	`true` — orchestrators coordinate, they don’t write code
Experiments	`true`	`false` — fresh worktree every time for clean comparisons

Permission and tool access (Claude)

Claude presets control what tools the agent can use:

"config": {
  "permissionMode": "acceptEdits",
  "allowedTools": []
}

permissionMode: "default" uses standard permission checks for tools that are not already approved
permissionMode: "acceptEdits" automatically approves file edits and supported filesystem operations; other tools still follow permission rules
permissionMode: "plan" is for exploration and planning; file edits are not automatically approved
permissionMode: "bypassPermissions" is a high-trust option for unattended local execution and sets allowDangerouslySkipPermissions: true
allowedTools lists tools to approve without prompting. An empty array adds no tool approvals; unlisted tools remain subject to the permission mode and rules
disallowedTools blocks specific tools

When you provide a non-empty allowedTools list, Valdr adds the tools required to communicate with its MCP server. See Claude permission modes and rules for how tool approvals are evaluated.

Reasoning effort (Codex)

Codex supports reasoning effort configuration:

"config": {
  "model_preferences": {
    "reasoning_effort": "medium"
  }
}

Valid values: "low", "medium", "high". Use "medium" for general coding, "high" for complex architectural decisions.

MCP server attachment

Native providers (claude, codex, gemini) support attaching external MCP servers:

"config": {
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": { "API_KEY": "from-env" }
    }
  }
}

Important rules:

Claude: Always injects the internal Valdr MCP server. An explicit mcpServers.valdr entry is replaced by the embedded one.
Codex: Auto-injects Valdr MCP unless disableInternalValdrMcp: true. Translates Valdr MCP shape to native Codex config.
Gemini: Only registers explicitly supplied MCP servers. No automatic Valdr injection.
TanStack adapters: MCP servers are not supported. Tool execution is Valdr-managed.

What not to change

Never hard-code secrets

Always use env refs:

// ✅ Correct
"env": [{ "name": "CODEX_API_KEY", "valueRef": "CODEX_API_KEY" }]

// ❌ Wrong — never do this
"config": { "apiKey": "sk-abc123..." }

Import validation rejects packs with inline secrets.

Keep role semantics consistent

Name presets by role: coder-claude, reviewer-codex, orchestrator-ollama. Downstream policies, scoring, and review routing depend on consistent naming. Don’t reuse a coder preset for review tasks.

Don’t widen tool access without understanding the implications

Expanding allowedTools or changing permissionMode grants the agent more surface area. If you widen access, update your audit and observer configurations to match.

Building role-specific presets

Coders

Coding presets usually benefit from worktree isolation and an explicit permission mode:

{
  "key": "coder-claude",
  "providerType": "claude",
  "config": {
    "model": "opus",
    "permissionMode": "acceptEdits",
    "allowedTools": [],
    "keepAliveMs": 120000
  },
  "worktree": { "shouldCreateWorktree": true, "allowReuseExistingWorktree": true }
}

Reviewers

Focused evaluation with consistent output:

{
  "key": "reviewer-claude",
  "providerType": "claude",
  "config": {
    "model": "sonnet",
    "permissionMode": "default",
    "allowedTools": [],
    "keepAliveMs": 120000
  },
  "worktree": { "shouldCreateWorktree": true, "allowReuseExistingWorktree": true }
}

Orchestrators

Coordination presets — no worktree needed and usually no reason to skip confirmations:

{
  "key": "orchestrator-claude",
  "providerType": "claude",
  "config": {
    "model": "sonnet",
    "permissionMode": "plan",
    "allowedTools": [],
    "keepAliveMs": 120000
  },
  "worktree": { "shouldCreateWorktree": false, "allowReuseExistingWorktree": true }
}

Local development (Ollama)

Free, offline, and fast for iteration:

{
  "key": "coder-ollama",
  "providerType": "ollama",
  "config": {
    "model": "qwen3-coder-next",
    "baseUrl": "http://localhost:11434",
    "temperature": 0.1,
    "maxOutputTokens": 4096,
    "keepAliveMs": 300000
  },
  "worktree": { "shouldCreateWorktree": true, "allowReuseExistingWorktree": true }
}

Sharing configurations

Configure providers and presets in the UI
Export both from Settings (produces provider-defaults.json and agent-launcher-presets.json)
Share the JSON files — teammates Import them for identical configurations

When a model ships an update, change one preset, re-export, and everyone’s in sync.

Next steps

Configure your providers and presets in Settings, then put them to work by launching your first agent.

Preset Configuration