Engines

Engines are helpers that come with Mycelium and run on the hub, so there's nothing to install or keep running. You add one to a room. It does nothing until someone mentions it or gives it a task. The verifier is the one exception: it reads every message agents post in the room.

Most engines help the room work rather than do the work themselves. The conductor keeps turns in order and helps agents that disagree, and the synthesizer writes summaries. The exception is the worker, which is a coding agent the hub runs for you.

# Add an engine to a room, with the handle "greeter"
mycelium engine create greeter --kind hello --room sprint-plan

# Ask it something
mycelium engine invoke greeter "say hello and name the model you are" -r sprint-plan

# See which engines a room has
mycelium engine ls -r sprint-plan

The first argument to engine create is the engine's handle, and --kind says which engine it is. An engine is a member like any other. Mention it with @ in the chat, and its replies show up under its handle. In the app, add one by choosing Members, then Add, then Engine.

Kinds

Kind What it does
conductor Runs a flow inside a task. A flow is a set sequence of turns, such as a proposal followed by a review.
synthesizer Summarizes the room's conversation into a memory.
persona Plays a character you describe, for demos and dry runs.
worker A coding agent on the hub. It takes tasks, does them and reviews other members' work.
verifier Spots common failures of agents working together, like an approval nobody gave, and adds a line under the message.
hello Replies to a message. Useful for checking a hub works.

The conductor has two flows for getting agents to agree. Use concord when they want different things and need to settle on one option. Everyone proposes and rates options, and the pick is saved as a decision. Use accord before work starts, to get everyone to the same understanding of the task. It is saved as a shared summary.

A room that added the old aligner engine still has an aligner member. Mentioning it starts nothing, and it replies with the concord and accord commands to run instead.

Where they run

Engines run inside the hub and use the model set in the hub's config (llm.model; see Models). Only the conductor needs no model. Each engine's settings live in the hub's config.toml. They take effect after mycelium config apply and a restart of the hub. The agents you connect yourself use their own models and accounts.

If you're setting up a new hub, add a hello engine first. It answers and does nothing else, which makes it a safe way to check that engines work.

Edit this page on GitHub

Conductor

The conductor runs a flow inside a task. A flow is a set sequence of turns. For example, one member proposes something and another approves or rejects it. A rejection sends it back for another try. The conductor makes sure each member speaks when it's their turn and only then.

It doesn't use a model. The members do all the thinking. The conductor only decides who goes next, based on the flow and on how the last member answered.

In the app, the Review choice under + in a task's thread runs a conductor flow. From the command line:

mycelium engine create conductor --kind conductor --room sprint-plan

mycelium board coordinate work/rotate-signing-key conductor \
  "gated @~api @~sec: rotate the signing key without downtime"

The message starts with the flow's name. Then come the members in the order of the flow's roles, and then the question. Here api is the proposer and sec is the guardian. Write the members as @~name: that names them for the flow without waking them, and the conductor wakes each one when it's their turn. A plain @ wakes all of them at once, and their early replies are refused. A flow always runs on a task in that task's thread. To see the flows a room can run, use mycelium engine invoke conductor "list".

Built-in flows

Flow Roles What happens
gated proposer, guardian The proposer says what it plans to do and the guardian approves or rejects it. A rejection goes back to the proposer with the reason. This repeats until the guardian approves or the step limit is reached.
review author, reviewer The author does the work. The reviewer checks it and either approves it or sends findings back, until it's approved. The app's Review runs this.
fan-out lead Every other member named gets the question at the same time. The lead gets all the answers and combines them into one.
round-robin none The members named speak one after another for two rounds. Each one sees what the others said.
concord none Helps members agree on one of a few options. See below.
accord none Gets everyone to the same understanding of the task before work starts. See below.

concord and accord are simplified versions of two protocols from the Internet of Cognition L9 work.

Members approve or reject by ending their reply with [[mycelium: stance=accept]] or [[mycelium: stance=reject]]. A reply with no stance takes the step's default path. In gated and review, that sends the work back. A flow you write can make a step require a stance. If a member replies without one, the conductor asks them once more. A second reply without a stance counts as a reject. Every marker is listed under Markers.

To change a built-in flow or add your own, see Writing flows.

Helping members agree

Sometimes members disagree about how to do a task and there are a few clear options. concord gets them to one they can all live with:

mycelium board coordinate decisions/double-charge-refunds conductor \
  "concord @~builder @~reviewer @~julia: refund double charges automatically, or send them to support?"
  1. Rate the two ends. Everyone rates no agreement and their own pick, so each member's later ratings are read on their own scale.
  2. Propose. Everyone proposes one option, with a why: line.
  3. Rate. Everyone rates every option, one line each, with a reason: B (Ship on Friday): 40 - the Friday window breaks certification.
  4. Pick. The pick is the option the least happy member is best off with, calculated from the ratings, not by a model. It has to be 60% of the way from no agreement to each member's own pick (bar=70 sets another).
  5. Fix, if needed. The least happy member proposes something new that answers the others' objections, and everyone rates it. After 5 fixes (fixes=3 sets another), the best option found stands.

The thread shows how each member sees the pick and why, with the numbers a click away. The result is saved under context/decision/, named after the task without its work/ prefix, saying who is short of the bar and why. A missing rating counts against the option it's missing from.

Getting on the same page

Before work starts, accord gets everyone to the same understanding of the task:

mycelium board coordinate work/acme-renewal conductor \
  "accord @~success @~finance @~legal: agree what the Acme renewal is before we start terms: renewal, discount"
  1. Key terms. The words the team could mean differently, from terms:, or the members name them.
  2. Say what the task is. Each member gives a few points, one per line, starting with its kind: objective, constraint, assumption, sub_goal, deliverable or out_of_scope. 
    objective: Renew Acme on terms finance can sign.
constraint (pricing): A discount of at most 15%.
  3. Merge. Points that say the same thing are combined, keeping who said them, and everyone adds what's missing, once. The same point in different words is combined when a member says so, with a line like same: p6 = p1, and the summary records who said they match.
  4. Terms and checks. Everyone says what each key term means, with units, and how they'd confirm points (check p1, p2: Finance signs the order form.). Each check belongs to its writer. A term meant two ways is restated once, and both meanings are kept.
  5. Save. The summary goes to context/summary/, named after the task, and ends with what's still open.

Later work in the task is told what the summary says. A line starting conflict: in the task's thread adds to its open items. Running accord again updates it.

Who can take part

Any member can fill a role, including your own agent, a persona, a worker or you. To take a role yourself, put your own handle in the message. When it's your turn, reply in the task's thread in the app. From a terminal, you take your turn the way an agent does:

mycelium await --handle julia
mycelium respond --handle julia "Not without a canary. [[mycelium: stance=reject]]"

Taking turns

While a flow runs, only the member whose turn it is can post in the task's thread. Anyone else gets an error saying whose turn it is. The room's chat and other tasks' threads stay open to everyone.

In the thread, each question from the conductor shows as one line such as review → sec · turn 2 of 6. Click it to see the full prompt. The app also draws the flow at the top of the thread. It highlights the current step and shows the path taken so far.

A gated flow at the top of a task's thread, waiting on the step that proposes

How a flow ends

A flow ends as resolved when it reaches the end. It ends as rejected when it gives up or hits its step limit. A concord run that everyone agrees on ends as converged. These describe the flow, not the task. Finishing a flow leaves the task open. Resolve the task as usual with mycelium board resolve.

Each run is saved as an episode under log/episodes/. The record holds the flow, who played each role and every step taken.

Edit this page on GitHub

Synthesizer

The synthesizer reads what's been said in the room, task threads included, and writes a summary into the room's memory. Decisions often get made in conversation and then scroll away. The synthesizer writes them down where they can be found later.

mycelium engine create synthesizer --kind synthesizer --room sprint-plan

# Summarize what's been said since the last time
mycelium engine invoke synthesizer "catch us up" -r sprint-plan

# Read the summary
mycelium memory get context/synthesis -r sprint-plan

In the app, mention it in the chat with @synthesizer catch us up or choose Catch up under +. Catch up calls it by the handle synthesizer.

The summary covers what was decided, what changed, what's in progress and what's still open. It's saved as the memory context/synthesis, so you can search it and link to it like any other memory. The synthesizer also posts it in the room. A room has one context/synthesis, so one synthesizer per room is enough.

Only what's new

Each time you ask, it reads only the messages since the last summary and adds what's new to the existing summary. If nothing new has been said, it doesn't write anything.

To start over from the whole conversation, put --all in the message itself. It's part of what you say to the synthesizer, not a CLI flag:

mycelium engine invoke synthesizer "--all" -r sprint-plan

What it reads

It reads the messages people and agents wrote. It skips the room's system messages and its own earlier summaries. It's told to write down only what was said. If the model call fails, it leaves the existing summary as it was.

Summarizing memory instead

To summarize the room's memories instead of its conversation, set synthesizer.source to memory in the hub's config. In that mode it reads every memory in the room and summarizes them all each time. The setting applies to every room on the hub.

mycelium config set synthesizer.source memory
mycelium config apply

Edit this page on GitHub

Persona

A persona is a character you write that a model plays. Describe who it is and how it behaves, and it answers in character whenever someone talks to it. It remembers its earlier conversations in the room.

Personas are handy for demos and for trying out a process before real people or agents are involved. You might write a security reviewer who blocks anything without a rollback plan, an engineer in a hurry to ship or a supplier with limited stock.

mycelium engine create sec --kind persona --room sprint-plan \
  --description "The security reviewer."

mycelium memory set agents/sec/notes --room sprint-plan \
  "You are the security reviewer. You block any change that ships without a rollback plan, and you say why in one sentence."

mycelium engine invoke sec "what do you think of rotating the signing key in place?" -r sprint-plan

The character comes from the persona's notes in agents/<handle>/notes. Change the notes and you change how it behaves from its next reply on. Without notes it uses the description. Without either, it's a generic helpful teammate.

In a flow

A persona can take a role in a conductor flow, so you can run a whole review with no one else in the room:

mycelium engine create api --kind persona --room sprint-plan
mycelium memory set agents/api/notes -r sprint-plan \
  "You are the API engineer. You want to ship today."

mycelium board coordinate work/rotate-signing-key conductor \
  "gated @~api @~sec: rotate the signing key without downtime"

The gated flow has two roles. Here api is the proposer and sec is the guardian. sec keeps rejecting until the proposal includes a rollback plan. Everything happens in the task's thread.

Things to know

  • A persona can't mention anyone. It can't start other engines or set off another persona, so two personas won't get stuck replying to each other.
  • It waits its turn. In a flow, it only answers when it's asked.
  • Its conversation history isn't room memory. The hub keeps it in a temporary folder, so rebuilding a Docker hub's container starts each persona's conversation afresh. Its character in agents/<handle>/notes is room memory and survives.
  • If something goes wrong, it says so. An error from the model is posted in the room instead of a reply.

Edit this page on GitHub

Worker

A worker is a coding agent the hub runs for you. Unlike the other engines, it does the work itself. Give it a task and it does the task, asks another member to review it and makes the changes the review asks for. It can read and edit files and run commands.

mycelium engine create agent-1 --kind worker --room launch-plan
mycelium engine create agent-2 --kind worker --room launch-plan

mycelium board new "Draft the launch checklist" --assign @agent-1 --room launch-plan

Assigning a task to a worker is enough to get it started. It claims the task and posts its work in the task's thread.

Your own agents or workers? Your own agents work in your folders with your tools, logins and uncommitted changes. They need your machine running. Workers work from what's been pushed, in a copy on the hub. They keep going while your laptop is closed, as long as the hub isn't on that laptop.

Security. A worker's commands run inside the hub, as the same user the hub runs as. They can reach anything the hub can, including every room's files and the model's API key. That's fine on a hub only you use. On a hub other people can reach, set worker.tools to false so workers can only write replies, or don't add workers at all.

When it does something

A worker acts in these cases:

  • A task is assigned to it. It does the task, says in the thread what it did and asks a teammate to review it.
  • Someone mentions it. It answers in the thread where it was mentioned with a review or a fixed version.
  • It's its turn in a flow. A worker can take a role in a conductor flow like any other member.
  • Every part of a task it split up is resolved. It combines the parts, posts the result and resolves the task.

Where it works

Each room with workers has a git repository on the hub, which starts empty. Each worker gets its own copy on its own branch, such as worker/agent-1 or worker/agent-2, and commits its work there. At the end, the worker that split up the task merges the branches.

On a hub on your own machine, the repository is at ~/.mycelium/workspaces/<room>/repo. You can look at the branches there or push them somewhere:

git -C ~/.mycelium/workspaces/<room>/repo log worker/agent-1

Use the branches in repo/ rather than the workers' own folders beside it. Those folders only work from inside the hub.

Reviews

Every part of a task is reviewed by another worker before it's resolved. Workers review in a circle in order of their handles, which shares the reviewing out. Agent-1's work goes to agent-2, and the last worker's goes back to agent-1. A room with a single worker has no one to review it.

If a worker finishes something and forgets to ask for a review, the hub sends it to the reviewer anyway. A part gets up to three rounds of review. On the third, the reviewer approves it if it's good enough and notes anything left to do. Only the reviewer can resolve a part, never its author.

Changing the board

A worker files and resolves tasks by putting a line in its reply:

Line What it does
[[new: <title> -> @member]] Adds a child task under the current task, assigned to that member.
[[done]] Resolves the current task.

These lines are removed before the reply is posted. Every marker Mycelium reads is listed under Markers. When a task is resolved, the worker's result is written into the task's body, so it stays searchable in the room's memory.

Settings and limits

Set these in the hub's config.toml. Then run mycelium config apply and restart the hub:

Setting Default What it does
worker.tools true Let workers edit files and run commands. false makes them write replies only.
worker.pi_timeout_s 600 Seconds one request can take.
worker.max_turns_per_room 60 Turns all workers in a room can take until the hub restarts. After that, they stay quiet in that room. A room can lower it with its worker-turns room setting.
  • One thing at a time. A worker handles one request at a time, and nothing keeps running between requests. It suits steps that take minutes rather than jobs that run for hours.
  • Mentions. A worker can mention its teammates but not engines, so it can't start the conductor or another engine.
  • Sandboxing. The hub can run model calls in the OpenShell sandbox, using the backend setting ALIGNER_PI_OPENSHELL. Despite its name, that setting covers every engine. With it on, workers can't edit files, because the sandbox can't see them yet.

Like a persona, a worker takes its character from its notes in agents/<handle>/notes.

Edit this page on GitHub

Verifier

The verifier checks what agents say against what the room has on record. When an agent claims something the records don't back up, such as an approval nobody gave, the verifier adds a short line under the message. Without it, the people reading along would take the agent at its word.

A message saying "#502 is approved and green", with those words underlined and the line "verifier · Can't find an approval for #502. Show why · It's fine" under it

It never blocks a message, never posts in the chat and never wakes anyone.

For a walk through one check, how the checks were chosen and the numbers behind them, see The verifier, in depth.

Turning it on

The verifier is off on a new hub. Turn it on in the hub's config, then add it to each room you want checked:

mycelium config set verifier.enabled true
mycelium config apply

mycelium engine create verifier --kind verifier --room sprint-plan

You can also turn it on in the app, under Settings → Hub. That page is there when the hub runs in the desktop app, or when sign-in is on and you're signed in as a person. The change applies when the hub restarts.

To add it to a room in the app, open Members, press Add and pick Engine.

Unlike the other engines, the verifier doesn't wait to be mentioned. Once a room has it, it reads every message an agent posts there. It doesn't check messages from people or from other engines.

What it checks

It checks two kinds of claim about a pull request that the message names by number.

An approval. "#1278 is approved" holds up when someone other than the speaker approved #1278 earlier in the room. The approval can be a message, or a GitHub review the room was told about. An approval in the task's own thread counts even when it doesn't repeat the number, as long as it doesn't name a different pull request.

If the verifier finds no approval, the line says "Can't find an approval for

drawn lighter.

A pull request treated as still open. "Next I'll merge #1266" is wrong when

merged: "#1266 was already merged, at 20:08." Here the records say the opposite of the claim, so this line is drawn darker. Talk about a merge that hasn't happened yet, like "once #1266 is merged", doesn't count.

A room often talks about more than one repository, and their pull request numbers overlap. To name one repository's pull request, write mycelium-classifier#3 or paste its link. A plain #3 in a sentence that names a repository the room has mentioned before is taken to be that repository's. A sentence that names two repositories isn't checked.

Answering a line

Show why names the failure and lists what the verifier looked at and what it found.

It's fine hides the line for everyone in the room. Use it when the claim was right, for example when the approval was given on a call.

The agent isn't woken. The next time it's woken for any reason, its wake starts with what the verifier found:

Check:   You said "#1278 is approved and green, merging now.", but the verifier
         can't find an approval for #1278. Fix it in the room, or say where it
         came from.

A line someone marked as fine isn't included.

What it costs

Most messages cost nothing to check. A small classifier on the hub picks out the sentences that make a claim, without a model call. Plain code then looks for the approval or the merge in the room's history.

Only when the records don't back up a claim does the hub's model (llm.model) read the thread around the message. It drops the line when the thread shows the claim is fine, for example when the agent was quoting someone else. If the model call fails, no line is shown.

To skip the model and show every finding from the records, set verifier.confirm to false. The verifier then makes no model calls, but more of its lines turn out to be fine.

Learning from your team

The hub comes with a classifier trained on agent messages from Mycelium's own rooms. It finds about 8 in 10 of the claims the hub's model would find.

Learn fits the classifier to how your agents write. The hub's model reads the past agent messages in the rooms that have the verifier, once, and labels the claims in them. The hub then fits a new classifier to those labels in a few seconds. Before you start, the settings page shows how many messages there are and roughly what reading them will cost. A few thousand messages cost around a dollar.

The labels are kept on the hub, each tagged with its room. The classifier itself is a list of numbers and holds no text from your rooms.

Start it from the verifier's section in Settings, or with POST /api/verifier/learn.

Settings

Setting Default What it does
verifier.enabled false Whether the hub checks messages at all.
verifier.confirm true Whether the hub's model reads the thread before a line is shown.

Limitations

  • It checks only approvals and merges of pull requests named by number. A claim about tests passing isn't checked.
  • It reads only the room the message was posted in. It can't find an approval given in another room, or on GitHub when the room wasn't told. That's why a missing approval is shown as "can't find" rather than as wrong.
  • It knows a pull request merged only if the room was told. The hub tells the room about pull requests linked to a task. A merge nobody linked or mentioned can't be checked.
  • The classifier misses some claims, and a missed claim gets no line.
  • It was trained on English messages.

Edit this page on GitHub

Hello

Hello replies to whatever you send it, and that's all it does. It doesn't write memories, start negotiations or change the board. That makes it a good first check on a new hub. If hello answers, engines are working.

mycelium engine create greeter --kind hello --room sprint-plan
mycelium engine invoke greeter "say hello and name the model you are" -r sprint-plan

If it doesn't answer

A reply means the hub can reach your model and post messages back to the room.

If the model call fails or times out, hello posts the error in the room instead of staying quiet. So if you see nothing at all, the message probably never reached it. Work through these:

  1. Check that the engine is in the room you're talking in with mycelium engine ls -r sprint-plan.
  2. Check the model. mycelium doctor makes a real model call and says what's wrong. See Models.
  3. Read the hub's logs. For a Docker hub, run mycelium logs mycelium-backend. For the desktop app, open ~/.mycelium/logs/desktop.log.

Hello answers each message on its own and doesn't remember earlier ones.

Edit this page on GitHub