How to Use MAO: The Beginner's Guide to the Multi-Agent Canvas

How to Use MAO: The Beginner's Guide to the Multi-Agent Canvas

First, the disambiguation, because "MAO" is a crowded word: this guide is about MAO, the multi-agent orchestration canvas at trymao.dev — not the academic process-model framework on arXiv, not the Go BDD testing library, and not the University of Waikato's data-stream software. This how to use mao tutorial is for the days-old app that puts your coding agents on one visual canvas and lets them hand work to each other, and it covers the whole first run: your first canvas, the wire lesson, your first roles, the git-worktree layer trick, and the remote-workspace arc over SSH.

MAO launched on Product Hunt on October 28, 2026, pitching a simple idea: running one coding agent in a terminal is fine, but running three or four at once turns you into a manual router — copying output from one agent into another, re-explaining context, untangling two agents editing the same file. MAO puts every agent on one canvas as a live terminal, draws wires between the ones that should talk, and gives each a role so the work splits itself. The maker's pitch, in his own words from the launch: "Team up Claude Code, Codex and Grok on one canvas." Because git worktrees sit underneath the whole design, layers stay conflict-free — our git cheatsheet is a handy companion while you learn what the app does with branches behind the scenes. And if you've never driven the agents MAO hosts, start with our Claude Code beginner guide before you wire anything.

What Is MAO, Exactly?

MAO is a native desktop app — built in Rust on GPUI, the framework behind Zed, per the maker — that turns multi-agent coding into a visual canvas. The mao multi-agent canvas is a freeform space, not a dashboard: you arrange live terminals wherever you like and draw the coordination yourself. You add Claude Code, Codex, Gemini, Grok, OpenCode, or Antigravity as live terminals on that canvas; each node runs its own CLI on its own login, so your existing subscriptions keep working. Then you draw wires between agents: a wired agent can ask, delegate, and hand results back to another; an agent with no wire cannot reach anyone. Give each agent a role — Builder and Reviewer ship built in, or you write your own in Markdown once and reuse it — and tell the lead agent what to build. It splits the work, every agent takes its own piece, and you only step in when one of them needs you.

The design has a few signature primitives worth knowing on day one. Each layer of the canvas is a real git worktree, so agents literally cannot step on each other's checkouts. A portal is a real browser living on the canvas — wire an agent to it and it fills the form, clicks Place order, and screenshots the result. Broadcast lets you type once and start three agents. Routines send a prompt every night at 2 AM, skipping busy agents instead of interrupting them. Arrangements save a setup — the agents, their roles, and the wires between them — so you can drop a whole team onto any new canvas.

One more thing to fix in your head before you begin: MAO is not an AI agent. It is orchestration furniture for the agents you already pay for. The vendor is explicit about the money flow that matters: MAO never asks you to export a key — each agent keeps the login it already has, whether that is a plan, an API key, or a compatible endpoint, and the keys live only on your machine. Code never passes through MAO on its way to your agents' providers. Say it once and hold it: the app is the switchboard, not the phone company.

Why Does One Agent Feel Fine but Three Feel Chaotic?

One coding agent in a terminal is a helper with context. Three coding agents in three terminals are a traffic jam, and you are the traffic cop. This is the mental model lesson that makes the whole app click: one CLI per terminal is fine until three agents share one repo — then you become the manual router, copying a design decision from agent A into agent B, re-explaining the auth scheme to agent C, and discovering at merge time that two of them edited the same controller. MAO's answer is to put every agent on one canvas and draw wires so they hand work to each other while you lead, instead of shuttling messages between terminals yourself.

The wire is the unit of delegation. An unwired agent is an island — it can work, but it cannot ask anyone for anything. Draw a wire from the lead agent to a builder and a reviewer, and suddenly the lead can ask the builder to implement, ask the reviewer to check, and receive both answers back on the canvas where you can watch. The app ships skills that teach the agents how to message each other, delegate, and report back, so the wiring is a protocol the agents already understand, not a trick you have to prompt into existence every session.

The git-worktree layer is what keeps the parallel work honest. In a normal multi-agent setup, two agents in the same checkout will eventually edit the same file and one of them loses. MAO gives each layer its own real worktree — separate working directory, same repo — so the builder's changes and the reviewer's sandbox physically cannot collide. Merging happens on your terms, from clean parallel branches. It is the single biggest reason the canvas stays calm when the agent count grows.

How Do You Set Up Your First MAO Canvas?

The first run has a specific shape, and beginners go fastest when they follow it in order: sign in, start the trial, build one workspace, add agents, wire them, give them roles, then look at the layers. The vendor says sign-in is just an email — no password, no card — and the 7-day trial starts immediately with all of MAO unlocked on one canvas.

1. Sign in and start the trial. Create the free account with your email and the 7-day trial begins. The trial covers everything on one canvas: one workspace with one project, as many agents, terminals, and notes as you like, and wires, portals, and roles on that canvas. Know the lock rule up front: when the trial ends, MAO locks until you buy — but your workspaces stay on your disk, so nothing is lost.
2. Open your first workspace and point it at a project. Keep it to one project for your first canvas. You are learning the furniture, not running a fleet yet.
3. Add agents as live terminals. Add two or three agents you already use — for example Claude Code and Codex — as nodes on the canvas. Each keeps its own login; MAO never asks you to export a key, and your code goes only to your agents' own providers, never through MAO. Give it a minute to confirm each agent's CLI is reachable.
4. Draw your first wire. Connect the lead agent to one builder. Watch one of the three flows the app supports: the lead asks the builder something, delegates a task, or receives a result back. This wire is the whole product in miniature — if the handoff works, everything else scales.
5. Assign the built-in roles. Put Builder on the worker and Reviewer on the checker. Roles are plain Markdown files you can read and edit, which means your third agent can reuse the same role text verbatim.
6. Glance at the layers panel. Confirm the builder's layer is its own git worktree before the first edit lands. This is the moment the worktree lesson becomes real instead of theoretical.
7. Save the arrangement. When the lead-builder-reviewer triangle works once, save it as an arrangement. Dropping that arrangement onto your next canvas rebuilds the whole team — agents, roles, wires — in one move.

After step 7, your homework is one lead order: "refactor the auth module, builder implements, reviewer checks the diff, report back." Then watch the attention queue — MAO keeps running agents quiet and lines up the ones that need you, so your job is responding to the queue, not polling terminals.

What Happens When You Draw a Wire?

A wire is a permission line between two agents: once drawn, either end can ask, delegate, and hand results back. Without a wire, an agent is unreachable to its peers — it can still work alone, but no other agent can request anything from it. Think of wiring as drawing the org chart your agents will actually follow.

Three wire patterns cover almost every beginner setup. Lead-to-builder is the delegation line: the lead breaks the task down and hands pieces over, the builder reports each piece back. Builder-to-reviewer is the quality gate: finished work flows to the reviewer before it comes near you. Lead-to-reviewer is the second-opinion line: the lead can ask the reviewer whether the builder's approach was right before more work piles on top of it. Most first canvases need exactly these three wires and nothing else.

Wires become powerful in combination with broadcast. Select several agents, write one prompt, press send, and it lands in all of them at once — the vendor's example is starting three agents with a single message. Pair broadcast with wires for the classic fan-out: broadcast the kickoff to every agent, then let the wires carry the follow-up conversations. The agents arrive at the work knowing the shared context, and the peer-to-peer wires keep the shared context current without you relaying messages.

How Do MAO Roles Work?

A role is a short Markdown document that tells an agent what its job is — what to do, what to check, and what to hand back. Builder and Reviewer come built in, and because roles are plain text, you can read exactly what the app expects from each agent instead of guessing. Writing your own role is the same act as writing any Markdown file: a heading for the job, bullets for the rules, an example of the expected handoff. If you need a refresher on the format, our Markdown cheat sheet covers the syntax in one page.

Roles are where beginner setups usually under-specify. "Builder" alone is a weak instruction; the role file should name the deliverable ("a working implementation plus a summary of what changed"), the boundaries ("do not touch the migration folder"), and the report format ("reply with file list and test results"). The Reviewer role should say what a pass looks like ("approve only if the tests you ran yourself pass") and what to do on failure ("hand the diff back to the builder with the failing test names"). The agents follow what is written, so vague roles produce vague teammates.

One role, many agents: the same Builder role file can serve every builder on the canvas, and across canvases, which is why saving arrangements matters. When you find a role that reliably produces clean handoffs, that role file becomes part of your standard arrangement — and your tenth canvas starts with the same discipline your first one had to earn.

How Do MAO Layers Keep Agents From Stepping on Each Other?

Each layer on the canvas is a real git worktree — a separate working directory of the same repository — so two agents on two layers can never edit the same checkout. This is the mao git worktree lesson, and it is the mechanical answer to the chaos problem from the mental-model section: parallel agents get parallel filesystems, and collisions become a category error instead of a daily event.

Practically, this means your workflow gains a clean split: builders work in their own worktrees, reviewers check out review copies in theirs, and you merge branches the way you always have. The agents see their own directory trees and nothing else. When the lead agent asks a builder to implement a feature, the builder's commits land in the builder's worktree; the reviewer's layer can mount the same branch for testing without either of them ever seeing the other's half-written files.

If the word "worktree" is new to you, learn the five core commands before you trust the abstraction — our GitHub beginner guide covers the branching model MAO's layers sit on top of. The commands that matter most in a multi-agent world are the ones that create, list, and remove worktrees, plus the habit of naming branches per agent per task so every merge reads like a sentence.

How Does the MAO Remote Workspace Work?

A remote workspace moves the compute off your machine: the agents run on a Linux box, and the canvas runs on yours, connected over SSH. The vendor's phrasing is exact — "agents run on the Linux box, the canvas runs on yours" — which means your laptop stays a thin client while a beefier machine carries the agent CLIs, the worktrees, and the context windows. This is the mao remote workspace story, and it is the feature that turns MAO from a desktop toy into a real workstation setup.

The setup is conceptually simple: you need a Linux machine that is always on — a home server, a rented VPS, or a cloud VM — with SSH access and your agent CLIs installed, and then you point MAO at it. The canvas renders locally, the terminals execute remotely, and the wires, layers, and roles behave exactly as they do on a local workspace. If you do not already rent a server for always-on work, read our what is VPS hosting explainer before you buy — a remote workspace wants a machine with uptime, not a laptop that sleeps.

Two operational habits matter more here than on local canvases. First, keep the agents' logins on the remote machine working — MAO still never asks for your keys, so the remote box needs its own working CLI auth for each agent. Second, remember that worktrees now live on the remote disk; your backup story should cover that machine, and MAO's own "backups in one file" feature is worth enabling the day you go remote. Remote workspaces inherit every local rule — wires still gate communication, layers still isolate — they just run somewhere with better uptime and more RAM.

What Do Routines, Portals, and Broadcast Do?

Routines are scheduled prompts: you write a prompt once, MAO sends it every night at 2 AM, and a busy agent is skipped rather than interrupted. This is the hands-off primitive for recurring work — nightly test runs, dependency audits, "summarize what changed today" digests. The design detail that matters is the skip rule: a routine never yanks an agent out of deep work, so scheduling one is safe in a way a cron job firing into a terminal never is.

A portal is a real browser that lives on the canvas as a node. Wire an agent to it and the agent can fill a form, click the Place order button, and screenshot the result back to you — browser automation without leaving the orchestration map. The beginner use case is end-to-end verification: wire your builder to a portal, and after implementing the checkout flow, the builder can actually run the checkout in the portal browser and hand you the screenshot as the receipt. It closes the loop between "I wrote the code" and "it works in a browser."

Broadcast is the fan-out primitive: select the agents, write one prompt, press send, and it lands in all of them. Combined with saved views — nine camera bookmarks, one key each, Option plus a number flying you back to a saved spot — the canvas stays navigable as it grows. Sessions also pick up where they left off, so closing the app mid-session is a pause, not a reset. The attention queue finishes the picture: running agents stay quiet, and the ones that need a decision line up for you.

How Does MAO Compare to the Other Ways to Run Many Agents?

The mao vs agentsroom question is the most common one in this space, so here is the honest table. These are five genuinely different answers to "how do I run several agents at once," and the right one depends on whether you want a dashboard, a supervisor, a discipline, or a canvas.

The clean way to read the table: AgentsRoom is a dashboard for a fleet, CAO is a supervisor over a terminal farm, the DIY pattern is a habit, ManyAgents is an orchestrator that splits work for you — and MAO is the only one where the coordination is a drawing you make with wires. Sibling lanes drawn once: buddy-list style IM chats with agents (a different product entirely — messaging, not orchestration) and local-IRC session messaging are different functions, never rivals. Pick the shape that matches how you think; the underlying agent CLIs are the same everywhere.

How Much Does MAO Cost?

The mao pricing story is deliberately simple, and it has not moved since the October 28 launch. Try it free for 7 days — sign in with your email, no card, no password, no subscription — with everything unlocked on one canvas. Then it is $20, paid once, and you keep it. The vendor's terms, as shown on the site this week: when the trial ends, MAO locks until you buy, but your workspaces stay on your disk. One computer at a time; you can move the license to another machine up to 3 times a year, and going back to a machine you have used before is free. The trial is tied to your account and your computer together, so a new email on the same machine does not start another trial.

Two pricing details beginners miss. First, the price is regional: $20 in most countries, $17 in China, $18 in the rest of East Asia plus Singapore, the Gulf, and Israel, $14 in Vietnam, India, Indonesia, and Asia's other lower-income countries, and $13 in Brazil and the rest of South America — the site and checkout show your price automatically. Second, what you are really paying for is the canvas, not compute: every agent still runs on the login or API key you already have, so MAO adds no per-token cost. Your Claude or Codex bill is unchanged; the $20 buys the switchboard.

Platform coverage at launch: macOS on Apple silicon and Intel, Windows x86_64, and Linux x86_64 on Wayland or X11. The maker built it in Rust on GPUI — the framework behind Zed — and claims the canvas stays smooth with a dozen agents running, which is the performance number to watch as your canvases grow. A paid license also comes with a seat in the MAO Discord.

What Are the 7 Beginner Mistakes With MAO?

Every beginner's first canvas has the same seven failure modes. Learn them from this table instead of from a lost afternoon.

Sources

Every fact in this guide was checked against a page fetched on November 3, 2026. Feature descriptions, pricing, trial terms, platform list, and regional prices come from the vendor's own site at trymao.dev (all vendor claims, quoted where the site gives exact wording). The launch date — October 28, 2026 — and the maker's launch pitch ("Team up Claude Code, Codex and Grok on one canvas") come from MAO's Product Hunt launch page, updated November 2. The nearest third-party explainer, gptonline.ai's MAO canvas overview (checked against the vendor site on October 30), confirms the feature set but runs no usage walkthrough — which is the gap this tutorial fills. The comparison table draws on AgentsRoom's autonomous-coding-agent guide (agentsroom.dev), Hysen Labs' CAO review (hysenlabs.com, GitHub data synced November 2, 2026), the DIY orchestration field guide at thedigitalflora.com (published June 14, 2026), and the ManyAgents Product Hunt page (launched October 25, 2026). Product Hunt upvote and comment counts were not retrievable in this run's page fetches, so none are stated.

Frequently Asked Questions

Is MAO free?

MAO is free for 7 days with no card — sign in with your email and everything is unlocked on one canvas. After that it is $20, paid once, with regional prices down to $13 in some countries. There is no subscription, and your workspaces stay on your disk even if you let the trial lapse.

Does MAO see my code or my API keys?

No. The vendor says each agent keeps the login it already has and MAO never asks you to export a key — keys live only on your machine, code goes only to your agents' own providers, and diagnostics are off unless you turn them on. The privacy page says every data item the app does see is shown as a real screen you can inspect yourself.

Which AI agents can I put on the canvas?

Claude Code, Codex, Gemini, Grok, OpenCode, and Antigravity, per the vendor's FAQ — each node runs its own CLI on its own login, and you can even run two Codex accounts side by side. Any agent with a CLI you can log into is a candidate; the canvas does not care which provider is behind the terminal.

Can two agents edit the same file at the same time?

Not by accident. Each canvas layer is a real git worktree, so two agents work in two separate working directories of the same repository and cannot overwrite each other. You merge the parallel branches yourself, the way you always have.

What happens when the 7-day trial ends?

MAO locks until you buy the $20 license, but nothing is lost — your workspaces stay on your disk and unlock when you pay. The trial is tied to your account and your computer together, so starting over with a new email on the same machine does not grant another trial.