Config

Helix reads a single YAML file. /onboard writes it; this page documents every block, so you can tune LLM providers, models, trace sources, apply targets, and per-stage behaviour.

Location

Config is project-local: Helix reads .mutagent/config.yaml from your project root.

your-project/
  .mutagent/
    config.yaml

Full example

.mutagent/config.yaml

config_version: "0.4.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-5
    judge_model: claude-opus-5

  # Trace sources. One entry auto-binds to
  # evaluate + diagnose.
  sources:
    - name: sessions
      platform: claude-code
    - name: prod
      platform: langfuse   # reads LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST from the environment

  # 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 the Helix session's own model
    # instead of a separate judge model.
    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.4.0. /onboard writes it; leave it as is. A 0.2.0 or 0.3.0 file is upgraded automatically the next time Helix reads it, with nothing lost. A 0.1.0 file is too different to upgrade automatically: Helix stops and asks you to migrate it, and /onboard can walk you through it.

`global.providers`

The LLM providers Helix is allowed to call. Each entry names a provider and points at an environment variable for its credential. /onboard adds entries for you, or edit the file by hand.

mutagent providers add adds a provider to your Mutagent workspace (used by Helix in the cloud). It doesn’t change this file.

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.

Mind the spelling: global.providers uses credentials_ref (plural); sources and targets use credential_ref (singular). Using the wrong one makes the file invalid.

`global.workspace`

The repository and subdirectory Helix operates on. This is not your Mutagent workspace (mutagent workspaces); it only scopes Helix to a repository path.

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-5`). To judge on the Helix session’s own model instead, 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`.
`default`	bool	With several sources, mark exactly one `default: true` to use it automatically; otherwise Helix asks which one to use.
`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. Not used by `langfuse`: export `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` (fixed names) instead.
`paths`	list	File paths to read, for `local-jsonl`, and the OTLP/JSON files to read, for `otel`.
`format`	string	How to parse the records: `langfuse-export` · `claude-code` · `codex` · `raw` · `unitf` (records that are already in the unified trace format, read as they are).
`endpoint`	string	Not used by the `langfuse` or `otel` readers today. For Langfuse, set `LANGFUSE_HOST`. `otel` reads OTLP/JSON files from `paths` (or `root`) and calls no endpoint.

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:

Markdown agents — agents defined as markdown files for a coding agent: Claude Code, Codex, Cursor, OpenCode. 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, and nothing is written in place. The exception is an agent hosted on a cloud agent platform (cloud-rest), where an approved fix is sent to the platform’s API.

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-cursor` (Cursor) · `local-opencode` (OpenCode) · `local-mastra` (Mastra) · `local-cloud-agent-sdk` (Claude Agent SDK) · `local-skill` (a skill directory) · `cloud-rest` (a cloud agent platform, over REST) · `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), `code`, or `platform-config` (an agent configured on a cloud agent platform). Code targets apply via `code-pr`; `platform-config` targets via `cloud-deploy`.
`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`).
`rest_base_url`	string	For `cloud-rest`, the base URL of the platform’s API.
`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) · `cloud-deploy` (push to a cloud agent platform) · `report-only` (never write).

DeepAgents and Pydantic AI (frameworks) are part of the target model but don’t have a dedicated platform value yet.

`lifecycle`

Per-skill overrides. Exactly four keys are accepted: agentspec, builder, evaluator, diagnostics.

Key	Type	Description
`spec_dir`	string	(agentspec) Where `/spec` writes specs. Default `.mutagent/specs`.
`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 the Helix session’s own model; a provider model runs it on that provider.

`triggers`

Automatic runs, keyed by stage: build, evaluate, diagnose, optimize, ship. Shipped disabled: Helix is on-demand. These keys are reserved for a future release; today nothing reads them, so nothing fires on its own even when enabled is true. They are local automatic runs, unrelated to gateway triggers (mutagent gateway triggers, see Triggers and routines).

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. The dashboard’s SETUP panel shows whether the config is complete, how many providers are ready, and which stages are ready to run; /help repaints it. /status and /onboard tell you what is missing and help you fill it in. helix doctor checks the installation itself — the binary, the agent directory and your provider credentials — not this file. Check spelling when you edit by hand: an unknown key, such as plaform, makes the file invalid. Only the sections inside lifecycle accept extra keys. Values listed as a set (platform, mode, apply.kind) accept only the values shown. After editing the file by hand, start Helix and check the SETUP panel, or run /status. From a script or coding agent, run helix -p "/status" (it needs a model key, like any headless run).

Get started

Run it

Lifecycle

Features

Helix Cloud

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