Config

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

.mutagent/config.yaml

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:

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`).

`global.sources`

Where your 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 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 binary, print the resolved config with:

mutagent-helix doctor --strict

Overview

Install

Lifecycle

Reference

Location

Full example

`config_version`

`global.providers`

`global.workspace`

`global.models`

`global.sources`

`global.targets`

`lifecycle`

`triggers`

Secrets

Inspecting your config

​Location

​Full example

​config_version

​global.providers

​global.workspace

​global.models

​global.sources

​global.targets

​lifecycle

​triggers

​Secrets

​Inspecting your config

Location

Full example

`config_version`

`global.providers`

`global.workspace`

`global.models`

`global.sources`

`global.targets`

`lifecycle`

`triggers`

Secrets

Inspecting your config