# 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:

```json
"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:

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

- `permissionMode: "acceptEdits"` keeps the agent capable while leaving edit confirmations in the loop
- `permissionMode: "bypassPermissions"` is a high-trust option for unattended local execution and sets `allowDangerouslySkipPermissions: true`
- `allowedTools: []` (empty array) means all tools. To restrict: `["Read", "Edit", "Write", "Glob", "Grep", "Bash"]`
- `disallowedTools` blocks specific tools

Valdr always merges required internal tools into the allowlist, so the embedded Valdr MCP server remains accessible regardless of your `allowedTools` setting.

## Reasoning effort (Codex)

Codex supports reasoning effort configuration:

```json
"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:

```json
"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:

```json
// ✅ 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:

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

### Reviewers

Focused evaluation with consistent output:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

1. Configure providers and presets in the UI
2. **Export** both from Settings (produces `provider-defaults.json` and `agent-launcher-presets.json`)
3. 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](/valdr/docs/ui/settings/), then put them to work by [launching your first agent](/valdr/docs/ui/tasks/agent-launch/).