# Commands Source: https://docs.mutagent.io/cli/commands The Mutagent CLI command reference — account, providers, install, setup, and feedback. Every command supports `--json` for structured output and `--non-interactive` to suppress prompts (`CI=true` does the same). Run `mutagent --help` for flags and examples. ## Account | Command | Description | | ------------------------------------ | --------------------------------------------------------- | | `mutagent login` | Sign in — browser OAuth. Alias for `auth login`. | | `mutagent auth login` | Sign in (`--browser`, `--non-interactive`, `--endpoint`). | | `mutagent auth status` | Show the current authentication state. | | `mutagent auth logout` | Sign out and clear credentials. | | `mutagent config list` | Show the resolved configuration. | | `mutagent config get ` | Read a config value. | | `mutagent config set workspace ` | Set the default workspace. | | `mutagent config set org ` | Set the default organization. | | `mutagent workspaces list` | List your workspaces. | | `mutagent workspaces get ` | Show a workspace's details. | ## Providers Manage LLM providers (BYOK). A provider belongs to **one workspace** — the one you are configured for. There is no scope to select and nothing is inherited, so no command here takes a scope. | Command | Description | | -------------------------------- | ------------------------------------------------------------------------------------- | | `mutagent providers list` | List the workspace's providers (`--limit`, `--offset`, `--type`, `--models`). | | `mutagent providers get ` | Show a provider. The key comes back masked. | | `mutagent providers add` | Add a provider. | | `mutagent providers update ` | Update a provider (`--name`, `--api-key`, `--base-url`, `--active`, `--set-default`). | | `mutagent providers delete ` | Remove a provider (`--force` to skip the prompt). | | `mutagent providers test ` | Re-run the connection test against the live provider. | ### `providers add` `--provider`, `--name` and `--api-key` are always required. The rest apply only to the entries that need them — see [provider setup](/platform/providers/setup) for which fields each entry takes. | Flag | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `-p, --provider ` | The catalog entry. One of `openai`, `anthropic`, `google`, `moonshot`, `glm`, `deepseek`, `xai`, `azure`, `vertex`, `bedrock`, `custom`. | | `-n, --name ` | Display name for this configuration. | | `-k, --api-key ` | The entry's secret. | | `--hosted-family ` | Which model family a gateway configuration targets. Required for gateways hosting more than one. | | `--base-url ` | Custom base URL for the provider API. | | `--resource-endpoint ` | Azure resource endpoint. | | `--deployment-name ` | Azure deployment name. | | `--api-version ` | Azure API version, e.g. `2024-08-01-preview`. | | `--project-id ` | Google Vertex project ID. | | `--region ` | Vertex location, or AWS Bedrock region. | | `--set-default` | Set as the default provider of its kind. | ```bash theme={null} # Direct entry mutagent providers add --provider openai --name "My OpenAI" --api-key $OPENAI_API_KEY # Gateway hosting two families — name the one this configuration is for mutagent providers add --provider azure --name "Azure GPT" --api-key $AZURE_KEY \ --hosted-family openai --resource-endpoint https://my-resource.openai.azure.com \ --deployment-name my-gpt-deployment ``` The credential is checked against the live provider before it is stored. If the provider rejects it, nothing is saved and the provider's own reason is shown. ## Install Install Mutagent packages into your coding agent. `install` takes a package and a harness. | Command | Description | | ------------------------------ | -------------------------------------------------- | | `mutagent install helix` | Install the Helix orchestrator + lifecycle skills. | | `mutagent install diagnostics` | Install the Diagnostics skill. | | `mutagent install evaluator` | Install the Evaluator skill. | Flags: `--harness HARNESS` (one of `claude-code`, `codex`, `omp`) to choose the coding agent, `--global` to install for all projects, `--version` to pin a version. ```bash theme={null} mutagent install helix --harness claude-code ``` ## Setup | Command | Description | | ------------------------------------ | --------------------------------------------------------------------------------------- | | `mutagent init` | Initialize a project (writes the local config). | | `mutagent skills install` | Install the CLI's own skill for coding agents. | | `mutagent hooks install` | Install hook handlers for coding-agent telemetry. | | `mutagent hooks claude-code ` | Install a specific Claude Code hook (session-start, pre/post-tool-use, stop, and more). | ## Usage | Command | Description | | ---------------- | --------------------------------- | | `mutagent usage` | Show your plan and current usage. | ## Feedback Send product feedback to the Mutagent team straight from the CLI. | Command | Description | | ---------------------------------- | -------------- | | `mutagent feedback send ` | Send feedback. | | Flag | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------- | | `--title TEXT` | A short title for the feedback. | | `--category CATEGORY` | One of `cli`, `helix`, or `stage:` + a stage (`spec`, `build`, `evaluate`, `diagnose`, `optimize`). | | `--session` | Attach the current session context. | | `--attach-transcript [PATH]` | Attach a session transcript. | ```bash theme={null} mutagent feedback send "The install step hung on Codex" --category cli --title "Install hang" ``` # CLI Installation Source: https://docs.mutagent.io/cli/installation Install and authenticate the Mutagent CLI. The Mutagent CLI (`@mutagent/cli`) is published on [npm](https://www.npmjs.com/package/@mutagent/cli). ## Install ```bash bun theme={null} bun add -g @mutagent/cli ``` ```bash npm theme={null} npm install -g @mutagent/cli ``` ```bash pnpm theme={null} pnpm add -g @mutagent/cli ``` ## Verify ```bash theme={null} mutagent --version ``` ## Authenticate ### Interactive login ```bash theme={null} mutagent login ``` Opens a browser to authorize the CLI. This is the normal path for local development. ### Non-interactive (CI / agents) Set the API key as an environment variable — no login step needed: ```bash theme={null} export MUTAGENT_API_KEY=mg_live_... ``` Managed keys use the `mg_live_` prefix. See [API Keys](/quickstart/api-keys). You can also pass `--non-interactive` (or set `CI=true`) to suppress interactive prompts. With `MUTAGENT_API_KEY` set, the CLI authenticates without `mutagent login`. This is the recommended pattern for CI pipelines and AI agents. ### Check status ```bash theme={null} mutagent auth status ``` ## System requirements | Requirement | Minimum | Notes | | ----------- | ----------------------- | --------------------------- | | Bun | ≥ 1.1 | Recommended package runtime | | Node.js | ≥ 18 | Alternative package runtime | | OS | macOS · Linux · Windows | — | ## Configure The CLI resolves configuration from flags, then environment variables, then your saved config. Set a default workspace or org to skip repeating them: ```bash theme={null} mutagent config set workspace mutagent config set org # inspect mutagent config list mutagent config get endpoint ``` ## Uninstall ```bash bun theme={null} bun remove -g @mutagent/cli ``` ```bash npm theme={null} npm uninstall -g @mutagent/cli ``` To also remove saved credentials, delete `~/.config/mutagent`. # CLI Overview Source: https://docs.mutagent.io/cli/overview The Mutagent CLI — install Helix, manage providers and workspaces, and send feedback. The **Mutagent CLI** (`mutagent`) is your client for the Platform and the installer for Helix. Sign in, install Helix into your coding agent, manage providers and workspaces, and send feedback — all from the terminal. `mutagent install helix` installs the Helix orchestrator and lifecycle skills into your coding agent (Claude Code, Codex, or Oh My Pi). Every command supports `--json` for machine-readable output, and `--non-interactive` for CI and agents. ## Get started ```bash theme={null} npm install -g @mutagent/cli ``` ```bash theme={null} mutagent login ``` Opens a browser to authorize the CLI. Set `MUTAGENT_API_KEY` to skip the browser in CI. ```bash theme={null} mutagent install helix ``` Then open your coding agent and run [your first loop](/helix/install/first-loop). ## What it's for | Area | Commands | | --------- | ---------------------------------------------------------------- | | Account | `login` · `auth` · `config` · `workspaces` | | Providers | `providers` — add, list, and test LLM providers (BYOK) | | Install | `install` — Helix, diagnostics, evaluator into your coding agent | | Setup | `init` · `skills` · `hooks` | | Usage | `usage` — plan and usage | | Feedback | `feedback` — send product feedback straight from the CLI | See the [command reference](/cli/commands) for every command and flag. ## JSON & non-interactive Add `--json` to any command for structured output (useful for AI agents and scripts), and `--non-interactive` (or `CI=true`) to suppress prompts: ```bash theme={null} mutagent providers list --json mutagent --non-interactive install diagnostics ``` # How the loop works Source: https://docs.mutagent.io/helix/how-the-loop-works The five ADLC stages, how they hand off, and the two rules that keep the loop honest. The Agentic Development Lifecycle is one loop with five stages. Each stage is owned by a standalone skill, and you can enter at any stage — the orchestrator routes onward from there. ```mermaid theme={null} flowchart LR S["Spec"] --> B["Build"] --> E["Evaluate"] --> D["Diagnose"] --> O["Optimize"] O -. "you approve" .-> B classDef s fill:#140d22,stroke:#7E47D7,color:#ede7f8; class S,B,E,D,O s; ``` | Stage | What happens | You get | | ------------ | -------------------------------------------------- | ---------------------------------- | | **Spec** | Define what the agent should do. | A portable `agentspec.yaml`. | | **Build** | Implement the spec into your framework or harness. | A working agent. | | **Evaluate** | Score the result against real traces. | A pass/fail verdict per criterion. | | **Diagnose** | Root-cause the failures on evidence. | Ranked remedies. | | **Optimize** | Apply an approved remedy, then run again. | A better agent, re-checked. | ## You stay in control No stage advances on its own. Every change to your code or config is held for your explicit approval before it lands, and nothing runs until you ask — Helix is on-demand, not a background process. The stages are also kept separate on purpose: **Evaluate** only decides pass or fail and routes any failures to **Diagnose**, which proposes the fixes. The stage that scores your agent is never the one that changes it, so a passing verdict can't come from the tool that was supposed to earn it. ## Enter anywhere You don't have to start at Spec. Point Helix at an agent you already have and ask it to **evaluate**; it will derive criteria from your traces and score the current behaviour. Ask it to **diagnose** and it will root-cause what the evaluation flagged. The loop is a flexible path, not a fixed pipeline. Two of the lifecycle skills — the **Evaluator** and **Diagnostics** — also publish on npm and run on their own, without the rest of Helix. See [the lifecycle pages](/helix/lifecycle/evaluate). # Your first loop Source: https://docs.mutagent.io/helix/install/first-loop From a fresh install to a spec, a build, and a first verdict — the whole ADLC loop in a few minutes. Once Helix is installed and booted, you drive it in plain English. This page walks the shortest path from nothing to a first verdict. Not installed yet? Set up the [Plugin](/helix/install/plugin) or the [Standalone](/helix/install/standalone) binary first. ## Start something new Begin at Spec. Describe the agent you want — in this walkthrough, a support-triage agent: ``` I want a support-triage agent for inbound email ``` Helix runs a guided interview and emits `agentspec.yaml`, the definition of the agent. Then build it: ``` build it ``` Helix implements the spec into your framework or harness and stops at a working agent. ## Improve one you already have If you already have an agent and some traces, go straight to Evaluate: ``` evaluate support-triage against my traces ``` Helix derives success criteria from the runs, scores each, and returns a verdict. Where it flags failures, ask why: ``` why is support-triage mislabeling refund requests? ``` Diagnose returns ranked remedies. Nothing is applied until you approve; when you accept one, Helix applies it and re-runs the loop so you can confirm it helped. ## You're done when * The Helix dashboard renders, and * `*spec` (or just asking for a spec) starts the interview. A full `*evaluate` needs a subject and its traces — that's the loop proper, above. Prefer commands to prose? Every stage has a shortcut: `*spec`, `*build`, `*evaluate`, `*diagnose`, `*optimize`. They're alternatives to natural language, not requirements. See [Commands](/helix/reference/commands). # Plugin Source: https://docs.mutagent.io/helix/install/plugin Install Helix into the coding agent you already use — Claude Code or Codex — through the mutagent CLI. The **Plugin** adds Helix to a coding agent you already have. It installs through the [`mutagent` CLI](/cli/overview), which pulls the Helix skills into your editor. **Before you start:** a working **Claude Code** or **Codex**, and Node (for the CLI). The Plugin upgrades a coding agent you already have — it doesn't give you one. ```bash theme={null} npm install -g @mutagent/cli ``` See [CLI installation](/cli/installation) for pnpm / bun and details. ```bash theme={null} mutagent login ``` Opens a browser to authorize the CLI. Set `MUTAGENT_API_KEY` to skip the browser in CI. ```bash theme={null} mutagent install helix ``` Installs the Helix orchestrator and the lifecycle skills into your coding agent's `.claude/`, and links `CLAUDE.md` / `AGENTS.md` so the agent boots the orchestrator. Add other skills the same way — for example `mutagent install diagnostics`. Helix runs **inside** the coding agent you installed it into — **Claude Code** or **Codex**. Open it in your project directory. (Helix isn't a shell command; the next step is typed into the agent, not your terminal.) In the agent, invoke the Helix skill: ``` /mutagent-helix ``` Typing `*mutagent` works too. From there you drive Helix in plain English. Nothing happened? Boot-on-load is a request to the host agent, not a guarantee. Type `boot the orchestrator` to force it. ## Update Re-run `mutagent install helix` to refresh the orchestrator and skills. ## Remove it Delete the skill directories the install wrote under `.claude/`, then remove the Helix section from your `CLAUDE.md` / `AGENTS.md`. Run a spec → build → evaluate pass end to end. # Standalone Source: https://docs.mutagent.io/helix/install/standalone Helix as its own coding agent, in a single binary. Install with one command — no Node, no npm, no checkout. The **Standalone** form is a single binary with the whole system inside — it *is* a coding agent. Nothing else to install. It's proprietary, and it runs on macOS (Apple Silicon or Intel) and Linux (arm64 or x64). Two binaries. Whichever you choose is the command you run for every step below. ```bash theme={null} curl -fsSL https://install.mutagent.io/helix | bash ``` Gives you the `mutagent-helix` command. ```bash theme={null} curl -fsSL https://install.mutagent.io/helix-omp | bash ``` Gives you the `mutagent-helix-omp` command. Don't pipe a script you haven't read straight into a shell. Download it first, look at it, then run it: ```bash theme={null} curl -fsSL https://install.mutagent.io/helix -o helix.sh # read it, then: bash helix.sh ``` Opt out of the PATH edit with `--no-modify-path` and add `~/.mutagent/bin` yourself. The installer places the binary in `~/.mutagent/bin` and adds that to your shell's startup file (it prints which one). Reload it, or just open a new terminal. ```bash theme={null} source ``` `--strict` is the real check. (The installer already runs a branded verify for you.) ```bash theme={null} mutagent-helix doctor --strict ``` ```bash theme={null} mutagent-helix-omp doctor --strict ``` Helix launches straight into its dashboard. ```bash theme={null} mutagent-helix ``` ```bash theme={null} mutagent-helix-omp ``` ## Update Re-run the same installer command. It replaces the binary after verifying its checksum. ## Remove it ```bash theme={null} curl -fsSL https://install.mutagent.io/helix | bash -s -- uninstall ``` ```bash theme={null} curl -fsSL https://install.mutagent.io/helix-omp | bash -s -- uninstall ``` Add `--purge` to also drop the cached runtime. Run a spec → build → evaluate pass end to end. # Build Source: https://docs.mutagent.io/helix/lifecycle/build Stage ② — implement a validated spec into your framework or harness, test-first. Stage ② of the loop · owned by the **Builder** skill. **Build** takes a validated [`agentspec.yaml`](/helix/lifecycle/spec) and implements it into the target you chose — a framework or a coding-agent harness. It works test-first: it lays down the checks the spec implies, then builds until they pass. Two agents run in tandem: an **implementer** writes the code, and a **reviewer** checks each pass against the spec and flags drift. They loop — implement, review, correct — until the checks are green. You get the finished agent and a build report, not the intermediate steps. ## Run it Point Helix at the spec and the target: ```text theme={null} Build the Refund Processing agent on Mastra with the Stripe tool and get its test suite green. ``` Other ways people ask: * *Implement the Lead Qualification agent for Codex — enrich each lead, score it, and route the hot ones to sales — and stop at a working agent I can run.* * *Add the escalation rule so the Refund Processing agent hands disputes over \$500 to a human instead of auto-approving.* Build implements the spec, runs its checks, and stops when you have a working agent. ## Keeping spec and code in sync Code drifts from the spec as you iterate. When that happens, ask Helix to **resync the spec** — it reconciles `agentspec.yaml` against what the implementation actually does, so the definition and the code stay in agreement. Any change to the spec is shown to you before it's written. ## What you get * A working agent that implements your spec. * A spec and an implementation that agree. Score the agent against your real traces. # Diagnose Source: https://docs.mutagent.io/helix/lifecycle/diagnose Stage ④ — root-cause the failures on evidence and rank the remedies. Failures come from Evaluate; fixes go to Optimize. Stage ④ of the loop · owned by the **Diagnostics** skill · also on npm as [`@mutagent/diagnostics`](https://www.npmjs.com/package/@mutagent/diagnostics). **Diagnose** takes the failures that [Evaluate](/helix/lifecycle/evaluate) flagged and finds *why* they happened — grounded in your real traces, not guesses — then ranks the fixes. It runs a set of **analyzer agents in parallel** across a slice of your traces; each returns findings tied to specific runs, which Helix merges, de-duplicates, and ranks by expected impact. ## Run it Point Helix at what's failing: ```text theme={null} Diagnose why the Refund Processing agent keeps failing the policy check on partial refunds. ``` Other ways people ask: * *Run a root cause analysis on the Deep Research agent's low-scoring runs and rank the fixes worth trying.* * *Find the traces where the Refund Processing agent mis-read the dispute amount and surface the common pattern.* ## What you get * **Root causes**, each tied to evidence from your traces. * **Ranked remedies** — the changes most likely to move the verdict, in priority order. Diagnose proposes; it doesn't apply. Remedies hand off to [Optimize](/helix/lifecycle/optimize), which applies them only after you approve. ## Use it on its own Diagnostics publishes independently as `@mutagent/diagnostics`. Point it at your agent's traces to get evidence-grounded root causes and ranked remedies without the rest of Helix. Apply an approved remedy and re-run the loop. # Evaluate Source: https://docs.mutagent.io/helix/lifecycle/evaluate Stage ③ — score your agent against real traces. Derives criteria, judges each one, and validates the judge before trusting it. Stage ③ of the loop · owned by the **Evaluator** skill · also on npm as [`@mutagent/evaluator`](https://www.npmjs.com/package/@mutagent/evaluator). **Evaluate** turns your traces into a trustworthy verdict. It doesn't ask you to write the eval — it derives the criteria from your own runs, judges each one, and checks the judge against your labels before it trusts it. ## Run it Ask for a verdict against your real runs: ```text theme={null} Evaluate the Refund Processing agent against last quarter's 800 disputes and show the pass rate per policy rule. ``` Other ways people ask: * *Score the Deep Research agent's answers for citation accuracy and flag which criteria fail.* * *Check how often the Refund Processing agent approves disputes that should have been escalated.* ## What it does Reads your traces and derives binary, actionable success criteria from the runs that worked and the runs that didn't — no criteria list to hand-write. Fans out **one critique-before-verdict judge per criterion**, running in parallel, and scores each run: pass or fail, with a confidence. Each judge reasons before it rules, so every verdict arrives with its rationale. Measures each judge against your own labels. Below a threshold of labels, a judge is marked `unvalidated` rather than trusted — you always know which verdicts to believe. Rolls the per-criterion results into one verdict on the whole run — a critical failure sinks it. ## Judge only — it never fixes The evaluator decides; it does not change your agent. Failures route to [Diagnose](/helix/lifecycle/diagnose), which proposes the fixes. Separating the grader from the fixer is what keeps the verdict independent of the change it triggers. ## Use it on its own The evaluator publishes independently as `@mutagent/evaluator`, so you can build a trustworthy eval suite without adopting the rest of Helix. Root-cause what evaluation flagged. # Optimize Source: https://docs.mutagent.io/helix/lifecycle/optimize Stage ⑤ — apply an approved remedy and re-run the loop until it converges. One approval, at the point it matters. Stage ⑤ of the loop · owned by the **Optimize** skill. **Optimize** closes the loop. It takes a remedy that [Diagnose](/helix/lifecycle/diagnose) proposed, applies it, and re-runs build → evaluate → diagnose to confirm whether the change helped, then repeats until it converges. It **conducts the loop itself**: it dispatches each stage in turn, feeds one stage's output to the next, and stops when there's no better change to make or the moment you decline a remedy. ```mermaid theme={null} flowchart LR B["Build"] --> E["Evaluate"] --> D["Diagnose"] --> O["Optimize"] -. "↻" .-> B classDef s fill:#140d22,stroke:#7E47D7,color:#ede7f8; class B,E,D,O s; ``` ## Run it Tell Helix what to improve and when to stop: ```text theme={null} Optimize the Refund Processing agent's policy-check prompt and keep iterating until the partial-refund criterion passes. ``` Other ways people ask: * *Apply the top remedy from diagnosis to the Deep Research agent and re-run the eval loop until the agent holds.* * *Tighten the Refund Processing agent's escalation rule so large disputes stop getting auto-approved.* ## One approval, where it counts Optimize is a bounded loop, not an open-ended one. You confirm once at the start, and there's a single approval at convergence — the point where a change is about to be written. Nothing lands on your code without that approval. ## What you get * An agent that measurably improved against your criteria, or a clear result that it didn't. * A change history you approved, each step re-checked. See how the five stages connect. # Spec Source: https://docs.mutagent.io/helix/lifecycle/spec Stage ① — define what your agent is. A guided interview that emits a portable agentspec.yaml. Stage ① of the loop · owned by the **AgentSpec** skill. **Spec** captures *what an agent is* before anyone writes code — its job, its tools, where it runs, and how you'll know it's working. The output is a single portable file, `agentspec.yaml`, that the [Build](/helix/lifecycle/build) stage consumes. ## Run it Describe the agent you have in mind: ```text theme={null} I have an idea for a Refund Processing agent — reads Stripe disputes, checks our refund policy, approves or routes to a human. Help me turn it into a spec. ``` Other ways people ask: * *Conceptualize a Deep Research agent that answers market questions with sourced, current citations — shape what it does, its tools, and its success criteria.* * *Spec out a new Lead Qualification agent from scratch: what it decides, what data it needs, and how we'll know it's working.* Helix runs a short guided interview — persona, jobs to be done, tools, context sources, activation triggers, and the criteria that count as success. It runs **in your own session**, no background agents, and every answer is validated against a schema before the file is written — so [Build](/helix/lifecycle/build) always starts from a well-formed definition. When you want to be sure it's sound, ask Helix to **validate the spec** — it re-checks the file against the schema. A valid spec is the contract the rest of the loop builds and judges against. ## Targets A spec can target a **framework** or a coding-agent **harness**: | Target | Options | | --------- | ----------------------------------------------------- | | Framework | Mastra · DeepAgents · Pydantic AI · LangGraph | | Harness | Claude Code · Codex · Cursor · Pi · Oh My Pi · Hermes | ## What you get * A portable `agentspec.yaml` — the definition of your agent. * Binary success criteria you can later evaluate against. Turn the spec into a working agent. # Commands Source: https://docs.mutagent.io/helix/reference/commands The Helix command roster. Every stage has a shortcut, but you can drive it all in plain English. Helix is a natural-language router — you can just say what you want. The `*command` shortcuts below are the explicit form of the same intents, grouped by the stage that owns them. ## Orchestrator | Command | Does | | ---------- | --------------------------------- | | `*sync` | Re-index the system. | | `*status` | Report where you are in the loop. | | `*onboard` | Set up or reconfigure. | | `*help` | Render the dashboard. | ## Lifecycle | Command | Stage | Does | | -------------------------- | ------------------------------------- | ------------------------------------------------------------------ | | `*spec` · `*validate-spec` | [Spec](/helix/lifecycle/spec) | Run the guided interview; validate the resulting `agentspec.yaml`. | | `*build` · `*sync-spec` | [Build](/helix/lifecycle/build) | Implement the spec; resync it from implementation drift. | | `*evaluate` | [Evaluate](/helix/lifecycle/evaluate) | Derive criteria from traces, judge, and return a verdict. | | `*diagnose` | [Diagnose](/helix/lifecycle/diagnose) | Root-cause the flagged failures and rank remedies. | | `*optimize` | [Optimize](/helix/lifecycle/optimize) | Apply an approved remedy and re-run the loop. | `*evaluate` is what you want almost always — it's the judge. There's also a separate static auditor, `*audit`, for a deeper structural review of a skill or agent. It's explicit-only; it's never the fallback for a plain evaluate. ## Natural-language queries work too Every command has a natural-language equivalent, routed automatically to the stage that owns it — so you don't have to memorise the command surface. These two do the same thing: ```text You type theme={null} check this agent against my traces ``` ```text Helix runs theme={null} *evaluate ``` A few more phrasings and where they land: | You say | Routes to | | ---------------------------------------------------- | ----------- | | "I need an agent that triages inbound support email" | `*spec` | | "build it" · "implement the spec" | `*build` | | "how's it doing on my traces?" | `*evaluate` | | "why are these cases failing?" · "root-cause this" | `*diagnose` | | "apply that fix" · "run another pass" | `*optimize` | | "where am I in the loop?" | `*status` | Boot Helix first with `*mutagent` (or `/mutagent-helix`), then type either form into your coding agent. When a request is ambiguous, Helix asks a clarifying question instead of guessing — it never advances a stage you didn't ask for. Shortcuts and plain English are interchangeable, and so is calling a skill directly (for example `/mutagent-evaluator`). Use whichever is fastest for you. # Config Source: https://docs.mutagent.io/helix/reference/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 ``` # FAQ Source: https://docs.mutagent.io/helix/reference/faq Common questions about Helix — scoring, data, the two forms, removal, and what ships. Every criterion — derived from your own traces, not invented by us — gets a pass/fail with a confidence. Those roll into one verdict on the whole run: a critical failure sinks it. Below a threshold of human labels, a judge is marked `unvalidated` rather than trusted, so you always know which verdicts to believe. No. Traces stay on your machine; Helix reads them locally. When it judges, it reasons on your own coding agent's model, so we hold no provider key and add no inference bill. The shipped package has no analytics. The hosted Platform is opt-in, through the separate `mutagent` CLI. The [**Plugin**](/helix/install/plugin) installs into the coding agent you already use. The [**Standalone**](/helix/install/standalone) binary is proprietary and *is* its own coding agent. Both run the same loop. No. If you're building something new, start at [Spec](/helix/lifecycle/spec) and [Build](/helix/lifecycle/build). Evaluate and Diagnose start working once you ship and your agent begins logging runs. **Plugin:** delete the skill directories under `.claude/` and remove the Helix section from your `CLAUDE.md`. **Standalone:** `curl -fsSL https://install.mutagent.io/helix | bash -s -- uninstall`. Helix bundles the full loop — the orchestrator plus AgentSpec, Builder, Evaluator, Diagnostics, and Optimize — installed through the [`mutagent` CLI](/cli/overview). Two skills also publish on npm and run on their own: [`@mutagent/evaluator`](https://www.npmjs.com/package/@mutagent/evaluator) and [`@mutagent/diagnostics`](https://www.npmjs.com/package/@mutagent/diagnostics). # Traces Source: https://docs.mutagent.io/helix/traces Helix judges your agent against the runs it already logs. Here's what counts as a trace and where it reads from. Helix scores your agent against **real traces** — the runs your agent already produces in development or production. It reads what you already have; you don't add instrumentation for Helix. ## Supported sources Read traces from a Langfuse project. Any OTel-compatible trace export. A file of runs on disk — no service required. Your **Claude Code** or **Codex** session transcripts, as-is. If you log to something that isn't listed, the local JSONL path is the escape hatch — export a batch of runs to a file and point Helix at it. ## What a trace needs to be useful A trace is one run of your agent: the input, what the agent did, and the output. The more of the run that's captured — tool calls, intermediate steps, the final result — the more precisely the evaluator can judge and the diagnostics can root-cause. A bare input/output pair still works; a full trajectory works better. **No traces yet?** You can still start. Run [Spec](/helix/lifecycle/spec) and [Build](/helix/lifecycle/build) to create the agent; Evaluate and Diagnose become useful the moment it starts logging runs. ## Where your data goes Your traces stay on your machine — Helix reads them locally and does not upload them. When the evaluator judges, it reasons on your own coding agent's model, so there's no separate provider key and no extra inference bill from us. # What is Helix Source: https://docs.mutagent.io/helix/what-is-helix The Agentic Development Lifecycle, run inside your coding agent — spec, build, evaluate, diagnose, optimize. **Research Preview** · `v0.1.0-alpha.15`. Helix is early and moving fast. The loop runs end to end today; expect the command surface to change. Helix is the **Agentic Development Lifecycle (ADLC)**, run inside your coding agent. It takes an agent through one loop — **spec → build → evaluate → diagnose → optimize** — and holds every change for your approval, so nothing ships until it has been re-checked against your real traces. ```mermaid theme={null} flowchart LR S["① Spec"] --> B["② Build"] --> E["③ Evaluate"] --> D["④ Diagnose"] --> O["⑤ Optimize"] O -. "you approve" .-> B classDef s fill:#140d22,stroke:#7E47D7,color:#ede7f8; class S,B,E,D,O s; ``` ## What it does Point Helix at an agent — one you're building, or one already running — and it drives the loop: it writes a spec, builds, scores the result against your [real traces](/helix/traces), root-causes what failed, and applies a fix. Every change waits for your approval; nothing lands until you say so. See [how the loop works](/helix/how-the-loop-works) for the full mechanism. **No traces yet?** Building something new is fine — start at **Spec** and **Build**. Evaluate and Diagnose start working once you ship and your agent begins logging runs. ## Two ways to run it Helix comes in two forms. Choose by whether you already have a coding agent you like. Installs Helix into **Claude Code** or **Codex** as a plugin, through the `mutagent` CLI — the editor you already use. ```bash theme={null} mutagent login mutagent install helix ``` **binary · Proprietary.** A single binary with the whole system inside — no Node, no npm, no checkout. Helix *is* the coding agent. ```bash theme={null} curl -fsSL https://install.mutagent.io/helix | bash ``` Not sure which? Take the **Plugin** if you already use Claude Code or Codex; take the **Standalone** binary if you'd rather have a ready-made agent. Then run [your first loop](/helix/install/first-loop). ## How you use it Helix is a natural-language orchestrator. Describe what you want — *"Evaluate the Refund Processing agent against last quarter's disputes and show the pass rate per policy rule"* — and it routes to the stage that owns the job. Nothing runs until you ask, and nothing lands until you approve. # Cloud Deployment Source: https://docs.mutagent.io/integrations/cloud-deployment Deploy agents to managed cloud platforms — Paperclip, Mastra Cloud, Vercel EVE. Ship your agent not just as a change, but as a **running agent** on a managed cloud platform. The same loop that applies an approved fix to your repo can deploy the agent to its host and keep watching it against your traces. ## Deployment platforms Mutagent's managed-agents platform — deploy and run your agents for you. Deploy Mastra-based agents to Mastra's hosted runtime. Deploy agents to Vercel EVE, Vercel's managed agent runtime. Deploy agents built on the Claude Agent SDK to a managed host. ## How it fits the loop The shape doesn't change: Evaluate scores the agent, Diagnose root-causes the failure, Optimize applies the approved fix — and then, instead of stopping at a merged PR, the loop ships the agent to its host and keeps watching it against your traces. Everything you can do with a deploy target you can already do locally: run the loop against your own repo today with [Helix](/helix/what-is-helix). Cloud deployment takes the same loop to a managed platform. # GitHub Source: https://docs.mutagent.io/integrations/github Connect a repository so Helix can read agent code and ship approved fixes as pull requests. GitHub is Helix's transport for your agent's source. It reads your agent from a repo and ships every approved fix back as a **pull request** — it never writes to your default branch. ## What Helix does with your repo * **Reads the subject.** Helix resolves the agent it's working on from the repo — harness markdown (e.g. `.claude/agents/*.md`) or agent code — so Spec, Build, and Evaluate reason over the real definition, not a copy. * **Writes via PR only.** When Optimize applies an approved remedy, Helix prepares the change on a branch and opens a pull request with the diff. Markdown targets apply as file edits; code targets apply as a code change. Review and merge on GitHub — the apply gate is your merge. Every apply is **approval-gated**. Helix proposes; GitHub is where you accept. Nothing lands on your default branch without your merge. ## Configure it Point a target at the repo and how fixes apply. A `local` target uses a checkout you already have; a `remote` target clones from `repo_url`: ```yaml .mutagent/config.yaml theme={null} global: workspace: repo: your-org/your-repo path: . targets: - name: local-agents platform: local-claude # Claude Code markdown agents mode: local # local = use this checkout · remote = clone repo_url root: .claude/agents # where the agent files live apply: kind: markdown # markdown agent files → PR ``` `platform` selects the harness or framework; `root` scopes where fixes are written; `apply.kind` is `markdown` for agent files or `code-pr` for a code change. See the [config reference](/helix/reference/config#globaltargets) for every key, and [apply targets](/integrations/targets/harness) for the harness vs code split. ## Authentication Local targets use your existing git credentials — the same `gh`/ssh setup you push with. Remote targets clone over `repo_url` using the credential named by `credential_ref` (an env-var name, never the secret itself). Helix needs only read access to evaluate and write access to open the PR branch. For the hosted loop, GitHub is also how Managed Agents reaches your code. See [Managed Agents](/platform/agents/overview). # Integrations Source: https://docs.mutagent.io/integrations/overview How Helix reads your traces, writes approved fixes, and connects to the tools around your agents. Helix plugs into the tools around your agents in three ways: it **reads traces** from wherever your agent runs, it **writes approved fixes** back to your agent's source, and it connects to **general-purpose** services like GitHub and Slack. Cloud deployment targets are on the way. Helix **reads** traces — it doesn't store them. Your traces stay in the source you already use. Where your agent's runs come from — local transcripts, JSONL exports, or an OpenTelemetry observability backend. Where approved fixes land — harness markdown agents or agent code, via GitHub. GitHub — connect a repo, read agent code, ship fixes as PRs. Slack — drive Helix. Managed-agent deployment platforms — Paperclip, Mastra Cloud, Vercel EVE. ## Local vs cloud * **Local** integrations run on your machine, no cloud account: transcripts, JSONL, and GitHub PRs against a repo you own. * **Cloud** integrations use credentials on a hosted platform: an observability backend (Langfuse, OpenObserve, SigNoz) for traces, and managed-agent deployment platforms for shipping the agent. # Slack Source: https://docs.mutagent.io/integrations/slack Get Helix run notifications in Slack — and drive the loop from a channel. Slack brings the loop into the channel where your team already works. Helix posts run events there, and takes commands from there. ## Notifications Helix emits an event at the points in the loop that need a human: a diagnose report ready for review, an eval verdict, an **apply waiting on your approval**. Each posts to a channel you choose, so a long-running evaluate or a gated apply doesn't need a watched terminal — the approval request comes to you. The apply notification carries the remedy summary and the diff it would apply, so you can review and approve without switching back to the editor. ## Drive the loop from a channel The same intent routing the orchestrator uses in your editor extends to Slack. A listener routes a channel message to the stage that owns the job — *"evaluate this," "apply that fix," "run another pass"* — so you steer the loop from a message the same way you do in the editor. ## Connect Slack uses a **bot token** with `chat:write` (and Socket Mode for the inbound listener). Add it as a credential — an env-var name, never the token in the config: ```yaml .mutagent/config.yaml theme={null} global: providers: - name: slack credentials_ref: SLACK_BOT_TOKEN ``` Point your run at a channel and Helix posts there. The token is read from the environment at runtime; see the [config reference](/helix/reference/config) for the credential model. Slack is general-purpose — it works alongside any trace source or apply target. It's the conversational front-end to the same loop you drive in your editor. # Local Trace Sources Source: https://docs.mutagent.io/integrations/sources/local Read your agent's runs from local transcripts and JSONL exports — no cloud account needed. When your agent runs on your own machine, Helix reads its traces from local sources — the transcripts your coding agent already writes, or a JSONL export. Everything stays on disk; nothing is uploaded. Reads sessions your Claude Code agent writes under `~/.claude/projects/`. Works out of the box — point Helix at the project and it finds the runs. Reads Codex session transcripts (`~/.codex/sessions/`) in the same way. Reads Pi and Oh My Pi session transcripts for agents built on those runtimes. Any agent that can emit a trace in JSONL/NDJSON form — one run per line — can be read as a source. Bring your own format; gzipped files are supported. ## How it connects Point Helix at the source and it binds it to Evaluate and Diagnose: ```yaml .mutagent/config.yaml theme={null} global: sources: - name: sessions platform: claude-code # claude-code · codex · local-jsonl · langfuse · otel ``` A single local source needs no credentials. For a JSONL export, point `paths` at your files. See the [config reference](/helix/reference/config#globalsources) for every key. Have traces in a hosted observability platform instead? See [OpenTelemetry sources](/integrations/sources/otel). # OpenTelemetry Sources Source: https://docs.mutagent.io/integrations/sources/otel Read traces from an OpenTelemetry-compatible observability platform — Langfuse, OpenObserve, SigNoz. # OpenTelemetry trace sources If your agent already emits traces to an **OpenTelemetry-compatible observability platform**, Helix reads them straight from that backend — it treats the platform as the trace source and doesn't store a copy. Read traces from a Langfuse project over its API. Read traces and OTel log-event streams from OpenObserve. Read traces from SigNoz or any OpenTelemetry-compliant backend. These are **cloud integrations** — they need the platform's endpoint and credentials. Local transcripts and JSONL need neither; see [local sources](/integrations/sources/local). ## How it connects Declare the source in your config with the platform and a credential reference (the **name** of the env var holding the key — never the key itself): ```yaml .mutagent/config.yaml theme={null} global: sources: - name: prod platform: langfuse # langfuse · otel credential_ref: LANGFUSE_SECRET_KEY ``` `otel` targets an OpenTelemetry-compatible endpoint; `langfuse` targets a Langfuse project. See the [config reference](/helix/reference/config#globalsources) for `endpoint`, `project`, and the rest. One source auto-binds to Evaluate and Diagnose, so a single backend is enough to run the loop on your production traces. # Code Targets Source: https://docs.mutagent.io/integrations/targets/code Apply approved fixes to code-based agents — Mastra, Claude Agent SDK, DeepAgents, Pydantic AI — via GitHub. When your agent is **code** — a framework implementation rather than harness markdown — Helix applies approved fixes by editing that code and opening a **pull request** on GitHub, the same as for harness agents. Agents built on the Mastra framework. Agents built on the Claude Agent SDK. Agents built with DeepAgents. Agents built with Pydantic AI. ## How a fix lands The flow mirrors [harness targets](/integrations/targets/harness): Diagnose ranks a remedy, you approve it, Helix prepares the code change on a branch, and it opens a **GitHub pull request** for you to review and merge. Code changes go through the same approval gate — nothing merges without you. Declare a code target in your config: ```yaml .mutagent/config.yaml theme={null} global: targets: - name: code-agents platform: local-mastra # local-mastra · local-cloud-agent-sdk mode: local apply: kind: code-pr # ship fixes as a GitHub pull request ``` The loop is the same whether your agent is markdown or code — Evaluate scores it, Diagnose root-causes it, and Optimize applies the approved fix as a PR. Only the target differs. # Harness Targets Source: https://docs.mutagent.io/integrations/targets/harness Apply approved fixes to harness markdown agents — Claude Code, Codex, OpenCode, Pi, Oh My Pi, Hermes — via GitHub. When your agent is defined as **markdown in a coding-agent harness** — its system prompt, config, and instructions as files in your repo — Helix applies approved fixes by editing those files and opening a **pull request** on GitHub. Supported harnesses include Claude Code, Codex, OpenCode, and the Pi family (Pi, Oh My Pi, Hermes). Agents defined in `.claude/agents/*.md`. Agents defined as Codex markdown / TOML. Agents defined as OpenCode markdown. Agents defined for the Pi runtime. Agents defined for Oh My Pi. Agents defined for the Hermes runtime. ## How a fix lands Helix never writes to your repo directly. After Diagnose ranks a remedy and you approve it: 1. Helix prepares the change on a branch. 2. It opens a **GitHub pull request** with the diff. 3. You review and merge — the change is yours to accept. Every apply is **approval-gated**. Helix proposes; GitHub is where you accept. Nothing lands on your default branch without your merge. Declare a harness target in your config: ```yaml .mutagent/config.yaml theme={null} global: targets: - name: local-agents platform: local-claude # local-claude · local-codex · local-cursor · local-opencode mode: local root: .claude/agents apply: kind: code-pr # ship fixes as a GitHub pull request ``` Building an agent as **code** instead of markdown? See [code targets](/integrations/targets/code). # Welcome to Mutagent Source: https://docs.mutagent.io/introduction The Agentic Development Lifecycle, as a product. # Mutagent Platform Mutagent is built around one idea: an **Agentic Development Lifecycle (ADLC)** for AI agents — **spec → build → evaluate → diagnose → optimize**. You run that loop locally today with [Helix](/helix/what-is-helix), and it becomes a hosted, managed service on the Platform. **Helix** runs the loop on your machine right now. **Managed Agents** — the same loop, hosted on the Platform — is [coming soon](/platform/agents/overview). ## Two products, one loop The ADLC engine that runs **in your coding agent** — as a Plugin or a Standalone binary. Live today. The same loop, **hosted on the Platform** and driven from the `mutagent` CLI. Coming soon. ## The `mutagent` CLI The [`mutagent` CLI](/cli/overview) is your client for both: it installs Helix into your project and connects you to the Platform. ```bash theme={null} npm install -g @mutagent/cli ``` Opens a browser to authorize the CLI. Set `MUTAGENT_API_KEY` to skip the browser in CI. ```bash theme={null} mutagent login ``` ```bash theme={null} mutagent install helix ``` ## Quick links The ADLC loop, explained. The hosted loop — coming soon. Trace sources, apply targets, GitHub & Slack. # Agents Source: https://docs.mutagent.io/platform/agents/overview Managed Agents — the Helix ADLC loop, hosted and driven from the mutagent CLI. Coming soon. **Managed Agents** brings the same loop you run locally with [Helix](/helix/what-is-helix) — spec, build, evaluate, diagnose, optimize — to the Platform, driven from the [`mutagent` CLI](/cli/overview). # Providers Overview Source: https://docs.mutagent.io/platform/providers/overview Bring your own LLM provider keys. One level of provider configuration, attached to the workspace. A provider is an LLM service Mutagent runs on — the models used to build, evaluate and reason over your agents. You bring your own keys: you add a credential for a provider you already pay for, and Mutagent uses it on your behalf. ## One level, attached to the workspace **A provider configuration belongs to exactly one workspace.** That is the whole model. There is no personal level, no organization level, and nothing is inherited from anywhere. A workspace's providers are the providers it has, and no others. If two workspaces both need OpenAI, each gets its own configuration — even if the key behind them is the same. Because there is only one level, there is nothing to override and no precedence to reason about. A provider either exists in the workspace or it does not. Everything a configuration needs is named at the point you create it, and the workspace it lands in is the workspace you are working in. You never select a level. ## The provider catalog Mutagent offers eleven provider entries. Seven talk directly to the vendor that trained the model; three are gateways that host somebody else's models; one is an escape hatch for any endpoint speaking an OpenAI-compatible API. | Entry | Kind | What it serves | | -------------------------- | ------- | ----------------------------------------------------- | | OpenAI | Direct | GPT models, served by OpenAI | | Anthropic | Direct | Claude models, served by Anthropic | | Google Gemini | Direct | Gemini models, served by Google AI Studio | | Moonshot AI | Direct | Kimi models, served by Moonshot AI | | z.ai (GLM) | Direct | GLM models, served by z.ai | | DeepSeek | Direct | DeepSeek models, served by DeepSeek | | xAI | Direct | Grok models, served by xAI | | Azure | Gateway | Azure AI Foundry, hosting OpenAI and Anthropic models | | Google Vertex | Gateway | Vertex AI, hosting Gemini and Anthropic models | | AWS Bedrock | Gateway | Bedrock, hosting Anthropic models | | Custom (OpenAI-compatible) | Direct | Any endpoint speaking an OpenAI-compatible API | Each entry asks for a different set of credentials — a direct entry usually wants only a key, while a gateway wants the coordinates of your deployment as well. [Provider setup](/platform/providers/setup) lists the fields entry by entry. ## Gateways host more than one vendor A gateway does not have models of its own; it serves models that belong to someone else. Azure and Vertex each host two model families, so selecting one of them asks a second question: **which family is this configuration for?** | Gateway | Hosted families | | ------------- | ----------------- | | Azure | OpenAI, Anthropic | | Google Vertex | Gemini, Anthropic | | AWS Bedrock | Anthropic | One configuration covers one family. To use both OpenAI and Anthropic models through Azure, add two Azure configurations — one per family. They differ in that single choice and live side by side in the same workspace. Bedrock hosts one family, so there is nothing to choose. A gateway never offers more than the direct entry it derives from. If a model is not available on Anthropic directly, it is not available through Azure, Vertex or Bedrock either. ## Credentials are tested before they are stored When you add a provider, Mutagent contacts the provider with the credential you submitted **before** writing anything. If the provider rejects it, nothing is saved and you are told why. A stored configuration is therefore one that has connected successfully at least once. The check runs on the server, so it applies however you add the provider — dashboard, CLI or API alike. ## Which models a provider offers You do not maintain a model list. Each entry carries its own policy, and the models on offer follow from it: * Some entries admit models at or above a version floor, so a newer release from the vendor becomes available without any change on your side. * Some admit a fixed, named set. * Gateways admit whatever their hosted family admits, addressed the way that gateway expects. * A custom endpoint offers whatever it publishes. The dashboard and `mutagent providers list --models` show what a given configuration currently offers. Optionally, most entries accept a **model allow-list** to narrow that further. ## Managing providers Manage providers in the dashboard under [Settings → Workspace → Providers](https://app.mutagent.io/settings/workspace/providers), or from the [`mutagent providers`](/cli/commands#providers) CLI. ```bash theme={null} mutagent providers list mutagent providers add --provider anthropic --name "Anthropic" --api-key $ANTHROPIC_API_KEY mutagent providers test ``` ## What providers power * **Generation** — the model used across the loop as you build and optimize. * **Evaluation** — the judge model. To judge on your coding agent's own model instead — no separate provider call, no extra bill — set `lifecycle.evaluator.judge_runtime: agent-dispatch` in the [config](/helix/reference/config#globalmodels). Providers configured here are distinct from the `credentials_ref` entries in a local Helix `config.yaml`. Those name an environment variable on your own machine. A provider added to a workspace stores the credential itself, encrypted, so Mutagent can call the provider for you. ## Next steps Field-by-field configuration for every catalog entry # Provider Setup Source: https://docs.mutagent.io/platform/providers/setup Add a provider to your workspace, field by field, for every catalog entry. This page covers adding a provider to a workspace and the exact fields each catalog entry asks for. For the model behind it — one level, attached to the workspace — see the [providers overview](/platform/providers/overview). ## Adding a provider to a workspace A provider configuration belongs to the workspace you add it in. There is no level to pick. Go to [Settings → Workspace → Providers](https://app.mutagent.io/settings/workspace/providers). Confirm the workspace named there is the one you mean to configure. Select **Add provider** and pick the entry. Selecting a gateway that hosts more than one model family (Azure, Vertex) asks which family this configuration is for. The form asks only for the fields that entry needs — see the tables below. Give the configuration a name that will still mean something to a teammate later. Mutagent contacts the provider with the credential before storing it. If the provider accepts it, the configuration is saved; if not, nothing is written and the provider's own reason is shown. The same is available from the CLI, which goes through the same server-side check: ```bash theme={null} mutagent providers add --provider anthropic --name "Anthropic" --api-key $ANTHROPIC_API_KEY ``` ## Reading the field tables Every entry stores exactly one secret. Secrets are masked on entry, encrypted at rest, and never returned by the API — reads come back with a masked value such as `sk-p...4f2a`. Everything else is ordinary configuration and is shown back to you as typed. ## Direct entries Seven entries talk straight to the vendor. All of them take the same three fields. | Field | Required | Description | | ----------------- | -------- | --------------------------------------------------------------------------------------------------- | | API key | Yes | The key issued by the provider. This is the entry's secret. | | Base URL override | No | Route requests through a proxy or a regional endpoint instead of the default one. | | Model allow-list | No | Narrow the models this configuration offers. Entries outside the provider's own policy are ignored. | Where each key comes from: | Entry | `--provider` value | API key | | ------------- | ------------------ | ------------------------------------------------------- | | OpenAI | `openai` | An OpenAI API key, issued from the OpenAI platform | | Anthropic | `anthropic` | An Anthropic API key, issued from the Anthropic console | | Google Gemini | `google` | A Google AI Studio API key | | Moonshot AI | `moonshot` | A Moonshot AI platform API key | | z.ai (GLM) | `glm` | A z.ai API key | | DeepSeek | `deepseek` | A DeepSeek platform API key | | xAI | `xai` | An xAI API key | ```bash theme={null} mutagent providers add --provider deepseek --name "DeepSeek" --api-key $DEEPSEEK_API_KEY ``` ## Custom (OpenAI-compatible) Use this for any endpoint that speaks an OpenAI-compatible API — one you run, or a third party's. | Field | Required | Description | | ---------------- | -------- | ---------------------------------------------------------------------------------------------------- | | Base URL | Yes | The endpoint serving the OpenAI-compatible API. | | API key | Yes | The key the endpoint expects, sent as a bearer token. This is the entry's secret. | | Wire format | No | The request shape the endpoint speaks — `openai` or `anthropic`. Defaults to the OpenAI wire format. | | Model allow-list | No | Narrow the models this configuration offers. | A custom endpoint offers whatever it publishes; Mutagent applies no policy of its own to it. ```bash theme={null} mutagent providers add --provider custom --name "My endpoint" \ --api-key $MY_KEY --base-url https://models.example.com/v1 ``` ## Gateway entries A gateway hosts models trained by someone else, so it needs the coordinates of your deployment as well as a credential. Azure and Vertex host two families each — state which family a configuration is for, and add a second configuration for the other. ### Azure Hosts **OpenAI** and **Anthropic** models. Azure addresses a model by the name given to its deployment rather than by model ID, which is why the deployment name is required. | Field | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Resource endpoint | Yes | The Azure resource endpoint, for example `https://my-resource.openai.azure.com`. | | API key | Yes | The key issued for the Azure resource. This is the entry's secret. | | Deployment name | Yes | Azure addresses a model by the name given to its deployment, not by model ID. | | API version | No | Pin the Azure API version, an ISO date optionally suffixed `-preview` (for example `2024-08-01-preview`). Defaults to the current stable version when omitted. | ### Google Vertex Hosts **Gemini** and **Anthropic** models. Vertex authenticates with a service-account key rather than an API key, so the JSON credential is the secret here. | Field | Required | Description | | -------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | Project ID | Yes | The Google Cloud project holding the Vertex AI entitlement — 6 to 30 lowercase characters, starting with a letter. | | Region | Yes | The Vertex location the models are served from, for example `us-central1` or `europe-west4`. `global` is also accepted. | | Service-account credential | Yes | The service-account key JSON granting Vertex AI access to the project. This is the entry's secret. | | Model allow-list | No | Narrow the models this configuration offers. | Vertex regions are full-word locations (`europe-west4`, `asia-northeast1`, `northamerica-northeast1`). They are not AWS-style region codes — `eu-central-1` is not a Vertex location. ### AWS Bedrock Hosts **Anthropic** models. One family, so there is nothing to choose. | Field | Required | Description | | ----------------- | -------- | --------------------------------------------------------------------------------------------------- | | Region | Yes | The AWS region the Bedrock models are invoked in, for example `us-east-1`. | | Bearer API key | Yes | A Bedrock bearer API key. This is the entry's secret, and the only credential type Bedrock accepts. | | Inference profile | No | Pin a cross-region inference profile. Defaults to the profile for the configured region. | **Bedrock takes a bearer API key only. Long-lived AWS access-key credentials are not supported.** An access key ID and secret access key pair — whether submitted as an `AKIA…` value or as `ACCESS_KEY_ID:SECRET` — is rejected before any connection is attempted. Issue a Bedrock API key and use that instead. Bedrock addresses Anthropic models as region-prefixed cross-region inference profiles, such as `us.anthropic.claude-opus-5-v1:0`. A bare model ID without the region prefix is not a valid Bedrock target. ## The connection test Mutagent contacts the provider with the submitted credential **before** persisting anything. This runs on the server, so it applies to every client equally — a configuration added through the CLI is checked exactly as one added in the dashboard. * **If the provider accepts the credential**, the configuration is saved. * **If it does not**, nothing is written and the provider's own error is returned. Your secret is stripped out of that message before you ever see it. Two failures are worth recognising because they are answered before the network is touched: * **No credential submitted.** Mutagent never falls back to a key sitting in the environment. A blank credential fails the test rather than silently picking one up from somewhere else. * **An unnamed gateway family.** A gateway hosting more than one family cannot be proven against a family nobody named, so state which family the configuration targets. To re-check a configuration that is already stored: ```bash theme={null} mutagent providers test ``` ## Verifying from the CLI ```bash theme={null} # List the workspace's providers mutagent providers list # Include the models each one currently offers mutagent providers list --models # Show one provider — the key comes back masked mutagent providers get # Re-run the connection test against the live provider mutagent providers test ``` ## Security Provider secrets are encrypted at rest and never returned by the API. * Each configuration holds exactly one secret, encrypted at rest. * API responses always mask it — the real value is never echoed back, not even to the person who entered it. * A configuration is reachable only from the workspace it belongs to. * Rotate keys by updating the configuration; the replacement is connection-tested like any other. ## Troubleshooting Nothing was saved — the message shown is the provider's own. Check that the key is current and has not been revoked, and that any endpoint, region or project field matches the deployment the key belongs to. Expected. Bedrock accepts a bearer API key only; an access key ID and secret pair is refused before a connection is attempted. Issue a Bedrock API key and submit that. Azure and Vertex each host two families, and one configuration covers one family. Pick the family this credential is for, then add a second configuration for the other. Providers belong to a single workspace. Check you are pointed at the right one with `mutagent config list`, then `mutagent providers list`. A gateway only offers what its hosted family offers, and a model allow-list narrows that further. Run `mutagent providers list --models` to see what the configuration actually offers. # API Keys Source: https://docs.mutagent.io/quickstart/api-keys Authenticate the mutagent CLI and SDK with your Platform account. API keys authenticate the [`mutagent` CLI](/cli/overview) and SDK with your Mutagent Platform account. Managed keys use the `mg_live_` prefix. For interactive use you don't need to copy a key — [`mutagent login`](/cli/overview) opens a browser and authorizes the CLI for you. API keys are for CI, scripts, and headless environments. ## Create a key Go to [app.mutagent.io/settings/api-keys](https://app.mutagent.io/settings/api-keys). Click **Create API Key**, give it a name, and copy the key — it's shown only once. Export it for the CLI or SDK: ```bash theme={null} export MUTAGENT_API_KEY=mg_live_... ``` With this set, `mutagent` commands authenticate without the browser flow. ## Good practice * Keep keys in environment variables or a secrets manager — never commit them. * Use one key per environment or machine, and rotate on a schedule. * Revoke a key from the same dashboard page the moment it's no longer needed. # Quickstart Source: https://docs.mutagent.io/quickstart/overview From zero to your first loop in a few minutes. The fastest way to start is **Helix** — the ADLC loop that runs in the coding agent you already use. The Platform account you sign into here is the same account Managed Agents will use when it ships. ```bash theme={null} npm install -g @mutagent/cli ``` ```bash theme={null} mutagent login ``` Opens a browser to authorize the CLI. Set `MUTAGENT_API_KEY` to skip the browser in CI. ```bash theme={null} mutagent install helix ``` Installs the Helix orchestrator and lifecycle skills into your coding agent. Helix runs **inside** a coding agent — **Claude Code**, **Codex**, or another supported harness. Open it in your project directory. (Helix isn't a shell command; the next step is typed into the agent, not your terminal.) In the agent, invoke the Helix skill: ``` /mutagent-helix ``` That boots the Helix orchestrator — from there you drive the loop in plain English. Typing `*mutagent` works too. See [your first loop](/helix/install/first-loop) for a full walkthrough. Understand the spec → build → evaluate → diagnose → optimize loop. The hosted loop — coming soon. # SDK Source: https://docs.mutagent.io/sdk/overview The Mutagent SDK — authenticate to the Platform from TypeScript or Python. The Mutagent SDK lets your code authenticate to the Platform and manage account resources programmatically. Install the CLI for interactive use; use the SDK when you're scripting against the Platform from TypeScript or Python. The SDK's job today is **authentication and account resources** — signing in and managing providers. The ADLC loop itself is driven by [Helix](/helix/what-is-helix) in your coding agent, not by an SDK call. `npm install @mutagent/sdk` `pip install mutagent-sdk` ## Construct a client The SDK exports a `Mutagent` client. It reads `MUTAGENT_API_KEY` from the environment by default: ```typescript theme={null} import { Mutagent } from '@mutagent/sdk'; const client = new Mutagent(); // uses MUTAGENT_API_KEY ``` From there you manage [providers](/sdk/typescript/providers) and account configuration. See [configuration](/sdk/typescript/configuration) for the client options. # Configuration Source: https://docs.mutagent.io/sdk/python/configuration Configure the Mutagent Python SDK client. The `Mutagent` client (and its async twin `AsyncMutagent`) takes options controlling auth, the API endpoint, and timeouts. With no options it reads `MUTAGENT_API_KEY` from the environment and targets the hosted Platform. ```python theme={null} from mutagent import Mutagent client = Mutagent( api_key="", # defaults to the MUTAGENT_API_KEY env var server_url="https://api.mutagent.io", # optional endpoint override timeout=30.0, # seconds ) ``` | Option | Description | | ------------ | ------------------------------------------------------- | | `api_key` | Credential. Defaults to the `MUTAGENT_API_KEY` env var. | | `server_url` | API endpoint. Defaults to the hosted Platform. | | `timeout` | Per-request timeout in seconds. | ## Async ```python theme={null} from mutagent import AsyncMutagent async with AsyncMutagent() as client: ... ``` `Mutagent()` with `MUTAGENT_API_KEY` exported is enough for most scripts. Override `server_url` only for a non-default endpoint. # Installation Source: https://docs.mutagent.io/sdk/python/installation Install the Mutagent Python SDK. # Install the Python SDK ```bash theme={null} pip install mutagent-sdk ``` ## Construct a client ```python theme={null} from mutagent import Mutagent client = Mutagent() # reads MUTAGENT_API_KEY ``` Set `MUTAGENT_API_KEY` in your environment, or pass credentials explicitly — see [configuration](/sdk/python/configuration). Then manage [providers](/sdk/python/providers). # Providers Source: https://docs.mutagent.io/sdk/python/providers Manage LLM providers on the Platform with the Python SDK. Providers connect your Platform account to LLM providers (BYOK). The SDK lists, adds, and tests them. The credential is the **name** of an env var holding the key — never the key itself. ```python theme={null} from mutagent import Mutagent client = Mutagent() # List configured providers providers = client.provider_configs.list_providers() # Add one — points at the env var that holds the key client.provider_configs.create_provider( name="openai", credentials_ref="OPENAI_API_KEY", ) # Verify a provider's credentials work client.provider_configs.test_provider(id="") ``` Managing providers interactively is usually easier through the [`mutagent providers`](/cli/overview) CLI or the dashboard. Use the SDK when you're scripting it. # Configuration Source: https://docs.mutagent.io/sdk/typescript/configuration Configure the Mutagent TypeScript SDK client. The `Mutagent` client takes options controlling auth, the API endpoint, timeouts, and retries. With no options it reads `MUTAGENT_API_KEY` from the environment and targets the hosted Platform. ```typescript theme={null} import { Mutagent } from '@mutagent/sdk'; const client = new Mutagent({ // Auth — defaults to the MUTAGENT_API_KEY env var. security: { apiKey: process.env.MUTAGENT_API_KEY }, // Optional: override the endpoint, timeout, and retry behaviour. serverURL: 'https://api.mutagent.io', timeoutMs: 30_000, retryConfig: { strategy: 'backoff' }, }); ``` | Option | Description | | ------------- | -------------------------------------------------------- | | `security` | Credentials. Defaults to the `MUTAGENT_API_KEY` env var. | | `serverURL` | API endpoint. Defaults to the hosted Platform. | | `timeoutMs` | Per-request timeout in milliseconds. | | `retryConfig` | Retry strategy for transient failures. | You rarely need to set anything — `new Mutagent()` with `MUTAGENT_API_KEY` exported is enough for most scripts. Override `serverURL` only if you're pointed at a non-default endpoint. # Installation Source: https://docs.mutagent.io/sdk/typescript/installation Install the Mutagent TypeScript SDK. # Install the TypeScript SDK ```bash bun theme={null} bun add @mutagent/sdk ``` ```bash npm theme={null} npm install @mutagent/sdk ``` ```bash pnpm theme={null} pnpm add @mutagent/sdk ``` ## Construct a client ```typescript theme={null} import { Mutagent } from '@mutagent/sdk'; const client = new Mutagent(); // reads MUTAGENT_API_KEY ``` Set `MUTAGENT_API_KEY` in your environment, or pass credentials explicitly — see [configuration](/sdk/typescript/configuration). Then manage [providers](/sdk/typescript/providers). # Providers Source: https://docs.mutagent.io/sdk/typescript/providers Manage LLM providers on the Platform with the TypeScript SDK. Providers connect your Platform account to LLM providers (BYOK). The SDK lists, adds, and tests them. The credential is the **name** of an env var holding the key — never the key itself. ```typescript theme={null} import { Mutagent } from '@mutagent/sdk'; const client = new Mutagent(); // List configured providers const providers = await client.providerConfigs.listProviders(); // Add one — points at the env var that holds the key await client.providerConfigs.createProvider({ name: 'openai', credentialsRef: 'OPENAI_API_KEY', }); // Verify a provider's credentials work await client.providerConfigs.testProvider({ id: '' }); ``` Managing providers interactively is usually easier through the [`mutagent providers`](/cli/overview) CLI or the dashboard. Use the SDK when you're scripting it.