Introducing Mutagent Helix: A Custom Harness

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.

Inside the harness

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, pause, 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.

1. Install the binary, curl -fsSL https://install.mutagent.io/helix | bash
2. Run mutagent-helix inside your project directory
3. Run /login to set up your LLM provider or subscription
4. 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.