Skip to main content
helix agent is a lean, general-purpose coding agent on the Helix harness. No orchestrator persona, no dashboard, no lifecycle commands. Everything else is there: your project context (AGENTS.md / CLAUDE.md), your provider, /trace, sub-agents, background monitoring, goal loops. Three ways to use it.

​
1. Interactive — a plain coding agent

You get a prompt, not a dashboard. Ask for work the way you would with any coding agent — it reads, edits and runs your code with the standard tool set:
An interactive helix agent session: a boot block naming the binary version, the model and the working directory; then the agent reads both files, runs the failing test, edits the buggy line with a visible diff, re-runs the test to ok, and reports the fix in two lines.

helix agent: the identity block at boot, then a bug-fix on calc.py with the test re-run to green.

​
2. Load a specific agent definition

Point it at a definition and that definition is the session:
--name looks in your project’s .mutagent/agents/ first, then .pi/agents/; both are detected on every boot. A definition is a Markdown file with optional YAML frontmatter; the body is the agent’s prompt:
Recognised frontmatter keys: name, description, tools, disallowed_tools, model, thinking, skills (a list of skill names to mount). Inside the session, /agent prints what loaded — source, skills, model, tools — so you can confirm you are talking to the right agent. Bare helix agent and helix agent --name general-purpose are the same thing: a local general-purpose.md in either agent directory overrides the built-in one.
If --name cannot be resolved, Helix prints an error to stderr naming every directory it searched — but the session still starts, as a plain harness session without your agent. Check stderr when an agent does not behave like itself; /agent inside the session shows what actually loaded.

​
3. Headless — run one task with -p

-p runs a single prompt and exits: the answer goes to stdout, diagnostics to stderr, so it composes with scripts and pipelines. It combines with everything above:
Harness flags pass through — for example --model picks the model for the session:

​
Built-in capabilities

Lean on ceremony, not on capability — all of this works without the orchestrator:

​
Compared to the other modes

Add --prime to run the same agent on the Prime loop — a code interpreter as its only tool.

Back to the modes overview

The orchestrator, agent mode, and the Prime loop side by side.