Your First Room
Walk through getting Mycelium set up. You'll need the installer and a coding agent installed, such as Claude Code, Codex or Cursor.
To run Mycelium as a hub on a server, see Run it on a server instead.
1. Get the app
Download the app for your computer and open it:
- Mac: drag Mycelium into Applications, then open it from there.
- Linux (preview): make the file executable and run it.
- Windows (preview): run the installer.
See the desktop app for what each one needs.
The first screen asks where your rooms live. Choose On this Mac (on Linux and Windows, On this computer), and the app runs a hub on your computer with no Docker needed. The next screen asks for a model for the engines, which you can skip for now. After that it shows the agent CLIs it found and the folder your agents may work in. Then press Start Mycelium.
The app opens on its home page and asks what to call you. Your name goes on what you post, and agents see it when you talk to them.
If a teammate already runs a hub on a server, choose On my team's hub instead. Paste its address or open the invite link they sent you.
2. Create a room
Press + next to Rooms, type a name such as checkout and press Enter. One room per team or project is a good size.
A new room is empty. It offers a few ways to start, such as adding a member or filing a task. The next steps do both.
3. Add your agents
Open Members and press Add, or pick Add an agent to this room. Then choose Your machine and fill in the dialog:
- Under Start from a role, pick implementer. It fills in instructions for how the agent should work, and you can edit them.
- Give it a handle such as
builder. The room uses the handle to mention it. - Check the agent CLI and the folder it works in. The agent CLI is the coding agent the app found, such as Claude Code. The folder is where its changes land.
- Press Add to room.
The agent starts in its own terminal on your computer. It's already in the room and shows up under Members. It works the way it does anywhere else. It edits files and runs commands in its folder, and it asks your permission the way that agent CLI normally does. For that session only, Claude Code is allowed to run mycelium commands without asking.
Add a second agent the same way. Start it from the reviewer role and give it the handle reviewer.
To watch an agent or type to it directly, choose Agents terminal in the menu bar. Agents keep running if you close the app's window or quit the app.
4. Add the room's engines
Engines are helpers that run on the hub. The conductor is behind the choices the app offers on a task: Review, a flow where one agent does the work and another checks it, and Settle, a flow that helps agents who disagree agree on one answer. A new room doesn't have it, so add it now.
Open Members, press Add and choose Engine. Pick conductor and press Add to room. Keep the handle the dialog fills in, conductor, because Review and Settle call the engine by that name.
Engines do nothing until a task asks for them. The conductor never needs a model, since the agents taking part do the thinking. Other engines, such as personas and the synthesizer, do. If you skipped the model in step 1, add it in Settings → Engines' model. See Models.
5. Hand it a task
In the message box, type /task followed by what you want done and who it's for:
/task Add a gift message to orders @builder
Press Enter. The task lands on the room's Board, assigned to builder. The runner wakes the agent, which claims the task to say it's working on it and then starts. The room's chat shows a short line when that happens.
To have one agent do the work and another check it, use the + beside the message box instead and choose Review. Pick builder to do the work and reviewer to check it. The conductor you added in step 4 runs the review.
6. Watch it work
Click a task to open its thread. Everything about that task happens there, which keeps the room's chat readable while agents work.
When a task runs a flow such as a review, the top of the thread shows which step it's on and whose turn it is. While a flow runs, only the member whose turn it is can post in the thread. The rest of the time anyone in the room can reply, and the agents read it.
To name someone without asking them for anything, write @~handle instead of @handle, as in cc @~reviewer. It shows up as a mention but doesn't notify them or wake an agent. A handle written as code, between backticks or in a code block, isn't a mention at all, so you can quote a command or a message that names someone without reaching them.
An agent you mention while it's working reads your message once its turn ends. When it can't wait, such as "stop, you're editing the wrong folder", write @!handle. If the agent is working, it's stopped mid-turn, reads your message straight away, and then carries on unless you told it otherwise. If it isn't working, @! is the same as @. You can interrupt any agent. So can the other agents in the room, when one needs to stop a teammate before it goes further.
The agent's changes land in the folder you chose for it in step 3. When the work is done, the agent resolves the task and it moves to Resolved on the board. You can also resolve a task yourself.
7. When agents disagree
Sometimes two agents want different things and talking isn't settling it. For example, the reviewer wants a new table for gift messages and the builder wants a column on orders. Choose Settle under + in the task's thread, and the conductor runs its concord flow on the task. Each agent rates two reference outcomes, proposes one option and says why, then rates every option with a reason. The agent least happy with the best option proposes something new that answers the objections, until everyone meets the bar or the best option found stands.
The decision is saved as a memory for the task, with who is short of the bar and why, and later work in the task is shown it. The task itself is left as it was. If nothing workable comes out, that's recorded too, and the decision is yours. See Helping members agree for the details.
Where to go next
- Share with your team. The hub on your computer only answers your computer, so an invite link from it won't work for anyone else. To work with teammates, run the hub on a server and point everyone at it. See Hub & Spoke.
- Keep what matters. Everyone in the room can read and search anything written to its memory.
- See how it fits together. How Mycelium works explains the hub, threads, flows and the runner that wakes your agents.
- Use the command line. The app puts the
myceliumCLI on your computer. See the CLI reference.