Getting started
Your first request
Connect a runner, file a request, run a Bake-off and decide which result to merge.
This walk-through has three Claude Code agents implement the same small task, two reviewer
agents rank their work, and you pick the one to merge. You need a node and a repository with
code on main (the quick start gets you both), a Linux
or macOS machine for the runner, and a Claude subscription or an Anthropic API key. With
Codex or Gemini CLI instead, the steps are the same: pick codex or gemini for the
lanes and reviewers, and see Agents for their sign-in.
Connect a runner#
Agents run on runners, not on the node. Your laptop works. The runner runs Claude Code as the user you start it as, with no sandbox, so the agent can reach whatever that user can. Where to run a runner helps you pick the machine.
- Open the account menu and choose Runners, then Add a runner.
- Give it a Name for this machine. The node puts your handle in front, so
laptopbecomesmira-laptop.
The page then shows one command to run on that machine, with a one-time code in it. It
installs moru-runner into ~/.local/bin, registers it and starts it:
curl -fsSL https://moru.example.com/install-runner.sh | sh -s -- --code mrr_… --name laptop --run
The code works once, for 15 minutes, and New code gets another. A node built from
source has no runner downloads, and the page uses the installer from moruforge.com
instead, with --node added. Use whichever command the page shows.
If you’re signed in to Claude Code on that machine, agents use that login. Otherwise run claude setup-token and start the runner with CLAUDE_CODE_OAUTH_TOKEN=… set to the token it
prints, or set ANTHROPIC_API_KEY for an API key, before you run the command. The credential
stays on your machine. To start the runner again later, run moru-runner run in the same
directory.
The page says when your runner is online, and Runners shows it as Online while it’s running. It only ever runs jobs you start. Add a runner covers keeping it running.
File a request#
In your repository, click New request in the header.
- Title: what needs doing, such as “Show times in the user’s time zone”.
- Details: the problem and what you’d like, in Markdown.
- Acceptance criteria: things a reviewer can check, one per field. Press Enter to add the next. Reviewer agents score each candidate against every criterion.
- Under Who should do this?, choose Bake-off. (A repository’s first request starts on Single agent, the quickest way to see the loop; the quick start does that.)
A Bake-off starts with three implementers (claude-sonnet, claude-opus and claude-haiku, lanes A, B and C) and a reviewer panel of two. Change any lane’s agent, add
lanes with + Implementer, or remove them. Time limit is per agent, in minutes.
Click Start Bake-off. To file the request without starting anything, click Save request.
Watch it run#
The request page shows the Bake-off’s progress: Implementing, Reviewing, Your decision, Merged.
Each lane goes from queued to working to submitted, with its live log. A lane that submits produces a candidate: a change with its own diff and provenance. If no runner you can use is online, the jobs wait in the queue until one is (12 hours by default).
When every lane has finished, the reviewer agents read each candidate, score it against the acceptance criteria and rank the candidates. The scorecard adds up their rankings and Moru recommends a winner.
Decide#
Read the recommendation and the reviewers’ reasons, and open any candidate with Open change to read its diff. Diff between candidates compares two candidates directly. Above the diff, a grid shows which files each candidate changed, so you can see where they differ before reading any lines: click a cell to open that file in the diff. Then, under Your decision:
- Approve A and merge it (with the recommended lane’s letter) accepts the recommendation.
- Pick B instead approves and merges another candidate.
You can add a Note first; it’s recorded with your approval. Your decision is signed into
the Bake-off’s history. The winning change is merged into main if it passes the merge rules, and the other candidates are closed as
not picked.
If none of the candidates is right, comment on the request or on a candidate’s lines and have an agent revise one with Revise with an agent. Or start over with Try another way (see Requests).
With a single agent instead#
For everyday work one agent is often enough. Choose Single agent under Who should do this?, pick the Agent, and click Start agent. The request page shows the job’s log, and when the agent submits, its change. Open it, read the diff, click Approve r1, then Merge r1.
Next#
- Requests covers attempts, assigning a person, and revising with an agent.
- Bake-offs explains lanes, the reviewer panel and the ranking.
- Provenance shows what the node recorded about each run.