Mutagent Helix runs our Agent Development Lifecycle as its own harness, one extension welded into the Pi coding agent. Six stages, eleven sub-agents, four launch modes, bring your own provider. The beta is public.
Introducing Mutagent Helix: A Custom Harness #
This week we shipped Mutagent Helix. It is our Agent Development Lifecycle with its own harness, the full loop from SPEC to SHIP running inside the Pi coding agent as one extension, no fork, with an orchestrator, six skills, and eleven sub-agents behind it. Version 0.0.16 went out on August 15 as a standalone binary. It is in beta, there will be bugs, and this post is the guide.
What you see at boot #
Boot the binary in a project directory and you’re in a Helix session. The orchestrator is the system prompt, so the lifecycle is live from the first turn, and twelve commands are registered at boot, the stage commands plus state and feedback. The dashboard frames all of it, the stages, the mounted skills, and where the loop stands.
One session, six stages #
A full cycle, stage by stage.
| stage | command | what happens |
|---|---|---|
| SPEC | /spec |
turn what you’re building into a spec the rest of the loop verifies against |
| BUILD | /build |
scaffold from the spec, test-first, with a reviewer agent that can steer or stop the build |
| EVALUATE | /evaluate |
success criteria learned from the agent’s real traces, binary verdicts at a gate |
| DIAGNOSE | /diagnose |
traces read before opinions, root cause pinned, fixes ranked, nothing applied without your approval |
| OPTIMIZE | /optimize |
change the layer the diagnosis actually named, validate before it counts |
| SHIP | /ship |
watch CI and post-deploy traces, recommend rollback with evidence, never execute it |
Each stage dispatches its own agents, and every agent has one job.
| agent | what it’s for |
|---|---|
| ai-architect | reviews builds before code lands, verdicts of PROCEED, STEER, or ABORT |
| ai-engineer | scaffolds the target and runs the test-first loop |
| evaluator | learns binary criteria from traces, judges runs, never fixes what it judged |
| dataset-builder | generates eval candidate cases, never judges them |
| diagnostics-analyzer | code-first trace analysis, model calls only for the deviations |
| discovery | collects and exports the trace batch |
| audit-executor | subject-agnostic static audits, four-tab report |
| explore | read-only search, a replica of the Claude Code built-in |
| monitor | the background watch cells, session triggers and release watches, rollback recommendations only |
Judge and fixer are different agents on purpose. The evaluator that scores a run is structurally not allowed to mutate it, so a verdict never optimizes itself into looking better.
Concrete run. Point Helix at a support-triage agent that’s been live for a month. /spec
turns its intended behavior into a checked-in spec. The agent already exists, so you skip /build
and go to /evaluate
, which reads a week of real traces, learns what a good triage looks like, and starts scoring runs pass or fail at a gate. One run fails. /diagnose
reads its trace, pinpoints the moment the agent picked the wrong tool after an unusual customer reply, ranks three remedies, and waits for your pick. You pick the prompt-section fix. /optimize
applies it scoped to that section and validates against the runs that failed, so the fix has to earn its count. /ship
watches the deploy out, CI green and post-deploy traces clean, and stands down.
Bring your own provider #
Helix doesn’t care whose models it runs. /login
signs you into a provider and stores credentials on your machine, /model
picks from the catalog, and your keys never leave your environment. Anthropic, OpenAI, Google, OpenRouter, Groq, xAI, DeepSeek, Moonshot, Kimi, and Z.ai are supported, plus Bedrock and Vertex through their credential chains.
Any dispatch can also pick its model, a fuzzy name like sonnet
or a full provider/modelId
, so one session can think on one provider and search on another.
Built for long runs #
/goal
keeps a queue. Add goals, pull one to the front, , resume, skip, clear, and give each one a token budget so a runaway objective stops itself. The queue renders beside the dashboard, so an unattended run always shows what it’s working toward next. A nightly run might queue triage the inbox first, then draft the weekly digest, each with its own budget.
Skills are drop-in. Any folder with a SKILL.md
under .claude/skills/
mounts automatically as a /skill:
command, so your own tooling appears next to the lifecycle. Skills without a lifecycle stage stay fully usable, they just stay out of the lifecycle panel.
The Monitor
tool watches any shell command’s output line by line and turns each line into a notification the agent reacts to, with flood and timeout guards built in.
Three modes, one binary #
The same binary runs in three modes, and the mode decides what sits in the system prompt.
| mode | command | what runs |
|---|---|---|
| Helix Orchestrator | mutagent-helix |
the full embedded orchestrator, dashboard, skills, and crew |
| Agent | mutagent-helix agent --name X |
your agent definition, replacing the embedded orchestrator |
| Prime | mutagent-helix --prime |
the code-interpreter runtime, no orchestrator at all |
| Prime agent | mutagent-helix agent --name X --prime |
your definition on the lean code-interpreter runtime |
The agent mode is the one to try first, because the pathway is direct. At boot the launcher resolves your definition, parses the frontmatter, and injects it as the system prompt over a lean scaffold, into the same slot the embedded Helix orchestrator occupies in default mode. Nothing else of the orchestrator loads. /agent
prints exactly what was resolved, the source, the scaffold, the skills, and the model.
There are three ways to feed it a definition. --name
resolves from the agent roots, your project’s .mutagent/agents/
first, then your global agent directory, then the bundled roster. --file
takes any path on disk. --prompt
takes an inline definition for one-off runs.
mutagent-helix agent --name ui-smoke # resolved from the agent roots
mutagent-helix agent --file ./agents/qa.md # any path
mutagent-helix agent --prompt "You audit PRs." # inline, one-off
A definition is just markdown with frontmatter. Drop this in .mutagent/agents/ui-smoke.md
:
---
name: ui-smoke
description: runs the Playwright smoke suite and summarizes failures
model: sonnet
skills: [playwright-cli]
---
Run the smoke suite against the local build and group the failures by page.
mutagent-helix agent --name ui-smoke
runs it directly. Dispatching ui-smoke
from inside a Helix session resolves the same file, because both read the same roots in the same order. One definition, both runtimes.
Prime mode, a runtime instead of a crew #
--prime
folds everything away, the dashboard and the orchestrator included, and hands the model one tool. run
executes JavaScript in a session that stays alive between turns.
> run: x = 41
(ask it something else, two turns later)
> run: x
41
Define a function in one turn, call it three turns later. Skills that ship code beside their instructions become callable functions in the same namespace. When code needs the machine, read
, write
, and shell run behind a gate, every effect is announced before it happens and can be refused, and how much reaches the host is a three-level switch, compute only, gated, or bare.
Architecturally, prime is the inverted mode. In orchestrator mode the model dispatches a crew, handing briefs to the Agent
tool. In prime mode the Agent
tool is not on the model’s surface at all. The model gets a code interpreter, one tool, and everything else is reached through code. Skills become callable functions, and dispatch becomes a function call.
The approach is borrowed with credit, prime-agent’s recursive language model (RLM) design, an IPython-style setup where the code interpreter is the only tool and the model recurses through its own code, spawning sub-agents as ordinary function calls instead of dispatching briefs. Prime is our port of that design onto the harness’s Bun-built runtime. We took a partial inversion. Cells may be submitted in parallel, but execution is strictly sequential, so one runaway program cannot interleave with another. agent(...)
returns a handle, never the answer, and a child’s result arrives later as a new turn, which keeps the model’s context clean of bulk output. The bounds are ours. Recursion stops five levels deep with eight children alive at once, and the function is named agent()
, not rlm()
, because a borrowed name imports a borrowed contract.
/refine
lets a session record what it learned as claim and evidence pairs. A claim with no observation behind it is refused, the code calls it “an objective, not a learning.”
The honest edges. The namespace lives for the session, on-disk persistence is the next milestone, and the gate currently records effects without refusing them yet.
Get started #
One binary, macOS and Linux, arm64 and x64. It carries its own harness, skills, and agents inside, so nothing else needs installing.
-
Install the binary,
curl -fsSL https://install.mutagent.io/helix | bash -
Run
mutagent-helix
inside your project directory - Run
/login
to set up your LLM provider or subscription - Select your preferred model via
/model
doctor
verifies the install and your provider keys, update
self-updates. The same lifecycle also ships as plain markdown for any CLAUDE.md
reader, including Claude Code, if you want it without switching tools.
It’s beta. There will be bugs. When you hit one, /feedback
files a report from inside the session, with the run attached, which is the fastest way it gets fixed.