> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Config
> The complete Helix configuration reference — file location, every block, and every key.
Helix reads a single YAML file. `init` writes it with sensible defaults; this page documents every
block, so you can tune providers, models, trace sources, apply targets, and per-stage behaviour.
## Location
Config is **project-local** by default. Install with `--global` and it lives in your home directory
(`~/.mutagent/config.yaml`) instead, shared across projects.
```
your-project/
.mutagent/
config.yaml
```
## Full example
```yaml .mutagent/config.yaml theme={null}
config_version: "0.3.0"
global:
# Providers Helix may call. The secret is
# read from the named env var, not stored.
providers:
- name: anthropic
credentials_ref: ANTHROPIC_API_KEY
# Repo + subdirectory Helix operates on.
workspace:
repo: your-org/your-repo
path: .
models:
default: claude-sonnet-4-6
judge_model: claude-opus-4-6
# Trace sources. One entry auto-binds to
# evaluate + diagnose.
sources:
- name: sessions
platform: claude-code
- name: prod
platform: langfuse
credential_ref: LANGFUSE_SECRET_KEY
# Where approved fixes land — as pull requests on
# your repo. Each target declares how it applies
# (apply.kind).
targets:
- name: claude-code-agents
platform: local-claude # Claude Code
mode: local
root: .claude/agents
apply:
kind: markdown # markdown agent files, via PR
- name: mastra-agents
platform: local-mastra # Mastra
mode: local
root: src/agents
apply:
kind: code-pr # code change, via PR
# Per-skill overrides, keyed by skill name.
lifecycle:
evaluator:
# Judge on your coding agent's own model —
# no separate provider key, no extra bill.
judge_runtime: agent-dispatch
diagnostics:
apply: report-only # propose only; don't write
# Auto-triggers — shipped disabled.
# Helix is on-demand by default.
triggers:
diagnose:
enabled: false
rules: []
```
## `config_version`
The schema version of the file — currently `0.3.0`. `mutagent install helix` writes it; leave it
unless you're migrating an older config (earlier `0.1.0` / `0.2.0` files are rejected until upgraded).
## `global.providers`
The LLM providers Helix is allowed to call. Each entry names a provider and points at an environment
variable for its credential. Add one from the CLI instead of editing by hand:
```bash theme={null}
mutagent providers add --provider openai --name "My OpenAI" --api-key $OPENAI_API_KEY
```
| Key | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------------------------- |
| `name` | string | Provider id — e.g. `google`, `openai`, `anthropic`, `bedrock`. |
| `credentials_ref` | string | The **name** of the env var holding the key (`GOOGLE_API_KEY`). Never the key itself. |
## `global.workspace`
The repository and subdirectory Helix operates on.
| Key | Type | Description |
| ------ | ------ | ---------------------------------------------------------- |
| `repo` | string | `org/repo`. |
| `path` | string | Subdirectory to scope to. Defaults to the repo root (`.`). |
## `global.models`
| Key | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | string | Model used for generation across the loop. |
| `judge_model` | string | Provider model used for evaluation (e.g. `claude-opus-4-6`). To judge on your coding agent's own model instead — no separate provider call, no extra inference bill — leave this and set `lifecycle.evaluator.judge_runtime: agent-dispatch` (see [`lifecycle`](#lifecycle)). |
## `global.sources`
Where your [traces](/helix/traces) come from. A single entry **auto-binds by role** to Evaluate and
Diagnose; with several sources you can bind them explicitly.
| Key | Type | Description |
| ---------------- | ------ | --------------------------------------------------------------------------------------- |
| `name` | string | A label you choose, referenced elsewhere in the config. |
| `platform` | string | `claude-code` · `codex` · `langfuse` · `otel` · `local-jsonl`. |
| `project` | string | Project/workspace to read from, for a hosted source (e.g. Langfuse). |
| `credential_ref` | string | Env-var **name** for the source's key — Langfuse (`LANGFUSE_SECRET_KEY`), OTel headers. |
| `paths` | list | File paths to read, for `local-jsonl`. |
| `endpoint` | string | Host URL, for `langfuse` / `otel`. |
See [Traces](/helix/traces) for what each source provides.
## `global.targets`
Where **approved** fixes are written — **a list**; add several and bind them per stage. Omit the
block entirely and every stage stays **report-only** (Helix proposes changes but never writes
them). When you do add a target, it must declare how it applies via **`apply.kind`**.
Targets come in two kinds:
* **Harness markdown agents** — agents defined as markdown in a coding-agent harness: Claude Code,
Codex, OpenCode, Pi, Oh My Pi, Hermes. A fix edits the agent's markdown files.
* **Code-based agents** — agents defined in code: Mastra, Claude Agent SDK, DeepAgents,
Pydantic AI. A fix is a code change.
Either way, a fix lands **via GitHub** — Helix opens a pull request on the target repo; nothing is
written in place.
| Key | Type | Description |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | A label you choose, referenced elsewhere in the config. |
| `platform` | string | Where fixes land: `local-claude` (Claude Code) · `local-codex` (Codex) · `local-opencode` (OpenCode) · `local-mastra` (Mastra) · `local-cloud-agent-sdk` (Claude Agent SDK) · `local-skill` (a skill directory) · `report-only` (propose, never write). |
| `subject` | string | What the target writes to — `agent` (default) or `skill` (a skill directory). |
| `artifact_format` | string | How the subject is realized — `markdown` (default) or `code`. Code targets apply via `code-pr`. |
| `mode` | string | **Required.** `local` (the repo is checked out locally) or `remote` (cloned from `repo_url`). |
| `root` | string | For a local target, the directory fixes are written under (e.g. `.claude/agents`). |
| `repo_url` | string | Remote git URL to clone, for `mode: remote`. |
| `default` | bool | When several targets exist, exactly one may be marked `default: true` to auto-select it; otherwise you pick at run time. |
| `credential_ref` | string | Env-var **name** for the credential a remote target needs. Never the secret itself. |
| `apply` | object | **Required.** How fixes are applied — `apply.kind` ∈ `markdown` (markdown agent/skill files, via PR) · `code-pr` (a code change, via PR) · `report-only` (never write). |
Pi, Oh My Pi, and Hermes (harnesses) and DeepAgents and Pydantic AI (frameworks) are part of the
target model but don't have a dedicated `platform` value in config v0.3.0 yet.
## `lifecycle`
Per-skill overrides, keyed by skill name (`diagnostics`, `evaluator`, …).
| Key | Type | Description |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apply` | string | Apply mode for this skill: `report-only` (propose only) · `markdown` · `code-pr`. With no target configured, this stays `report-only` regardless. |
| `judge_runtime` | string | (evaluator) Where judging runs — `agent-dispatch` uses your coding agent's own model; a provider model runs it on that provider. |
## `triggers`
Automatic runs, keyed by stage. **Shipped disabled** — Helix is on-demand; nothing fires on its own
unless you enable it here.
| Key | Type | Description |
| --------- | ---- | -------------------------------------------------------- |
| `enabled` | bool | Default `false`. |
| `rules` | list | Conditions that fire the stage when `enabled` is `true`. |
## Secrets
Secrets never go in `config.yaml`. `credentials_ref` / `credential_ref` are the **names** of
environment variables; Helix reads the values from your environment at runtime. The file is safe
to commit.
## Inspecting your config
Helix validates the config when it boots and reports the resolved providers, sources, and targets in
the dashboard. On the [Standalone](/helix/install/standalone) binary, print the resolved config with:
```bash theme={null}
mutagent-helix doctor --strict
```