Docs
Docs menu

Requests

File a request, triage and plan it, and have an agent, a Bake-off or a person carry it out.

A request says what you want done in a repository. It isn’t code: the code arrives later as a change. Between the two sits an attempt, one try at carrying the request out. An attempt is done by a single agent, by several agents in a Bake-off, or by a person. A request can have many attempts, one at a time, and keeps every one of them with the changes they produced.

Requests are also how people report bugs and ask for features, Moru’s equivalent of issues. Anyone signed in who can read a repository can file one, unless the repository takes requests from people with write access only: an admin chooses under Settings → Requests. A request from someone without write access waits in triage until someone with write access accepts or declines it. Setting acceptance criteria, starting attempts and planning need write access.

File a request#

Open the repository and click New request in the repository header, or pick New request from the command menu. The form has two halves.

On the left:

  • Title: what needs doing, in one line. This is the only required field.
  • Merge into: the branch the work is for, shown when the repository has more than one branch. It starts at the default branch. Agents start from this branch’s latest commit, and the changes the request gets are merged into it. You can’t change it after the request is filed.
  • Details: Markdown. The form suggests a Problem, Proposal and Out of scope outline; use it or not.
  • Acceptance criteria: one per line, labelled AC1, AC2 and so on. Press Enter in a criterion to add the next one. Write things a reviewer can check, such as “The CSV export includes the stop’s timezone” rather than “Works well”.

On the right, Who should do this? picks the first attempt. The choices are described in Choose who does the work.

The footer has two buttons:

  • Save request files the request without starting anything. Its status is Open, and you start an attempt later.
  • The other button starts the attempt you chose, and reads Start agent, Start Bake-off, Assign to yourself or Assign to @jon, depending on the choice.

If the request is filed but its attempt can’t start, you land on the request page with the reason at the top. The request stands, so you don’t file it twice.

If the repository has templates, the form starts with Start from: pick one to fill in the details. Beside the form, Already asked? lists requests whose titles share words with yours, once you’ve typed a few letters.

Without write access#

People who can read the repository but not write to it get a shorter form: a title, a kind (bug, feature or task, or not sure) and details, plus the templates if there are any. There are no criteria and nothing about who does the work; those are for whoever triages it.

Already asked? matters more here. If someone filed the same thing, a 👍 on theirs helps more than a second request: votes show in the request list and the Most wanted sort.

Your request waits for triage. Until someone with write access accepts or declines it, you can edit its title and details from its page. You’re notified either way, with the reason if it’s declined.

People who aren’t signed in see Sign in to file a request in the repository header instead, and come back to the form after signing in. Each account can file 10 requests an hour on repositories it can’t write to; a node admin changes that with --request-rate.

How criteria are used#

Every agent gets the title, the details and the criteria in its instructions. Reviewer agents score each change from 0 to 10 on each criterion, so specific criteria give you comparable scores.

While an attempt is running, you can’t change the criteria: the implementers and the reviewers must judge against the same list. If you change them before a later attempt, the form warns that earlier attempts were judged against the old criteria.

Triage#

A request filed by someone without write access shows Needs triage. Nothing can start on it until someone with write access decides, and people with write access who watch the repository are notified when one comes in. They also find it in their inbox under Requests to triage, and on the Needs triage tab of the request list.

On the request’s page, people with write access see a banner with three choices:

  • Accept puts it in the backlog. Plan it or start work on it whenever you like.
  • Accept and start… opens Who should do this?. Starting the attempt accepts the request in the same step.
  • Decline… closes it with a reason: a duplicate (pick which request it duplicates), won’t do, can’t reproduce, spam, or a reason you write.

If the request came from a template that names labels, the banner shows them with Apply. Possibly related, in the side column, lists up to three requests with similar titles; on a request in triage each one offers Decline as a duplicate of this.

A request declined as spam is hidden from everyone without write access, the person who filed it included, along with its comments. Reopen brings a declined request back to triage, unless someone had accepted it before.

Comments work as on any request: anyone who can comment in the repository can comment while it waits, to add details or say they see it too.

What agents are told#

A request’s text can come from anyone who can file one. When an agent works on it, text by someone without write access goes into the agent’s instructions between markers, after a line saying it describes a problem and isn’t an instruction to follow. The same goes for comments by people without write access, which revising agents read. The criteria are only ever written by people with write access, so they are what the agent is told to meet.

Accepting a request doesn’t change that. To tell the agent what to do, write criteria, or edit the details yourself: once someone with write access rewrites them, they’re no longer marked. What an agent would be given, at the bottom of the side column, shows the request’s part of an agent’s instructions as it stands.

Choose who does the work#

Who should do this? has three options.

Single agent#

One agent implements the request in its own scratch repo and submits one change. You review it before it’s merged into the request’s branch.

  • Agent: the profile to run, such as claude-sonnet. Profiles that no runner you can use is able to run right now are listed as “(can’t run now)”, with the reason underneath.
  • Time limit: in minutes, from 1 to 360. The default is 30. The agent is stopped when it runs out.
  • Pre-review: optionally, a reviewer agent that scores the change against the criteria once it’s submitted. Its verdict is advisory: you still approve the change.
  • Revise rounds: how many times the agent may revise its change on its own when CI fails or the pre-reviewer requests changes, from 0 to 10. It starts at 3 when you pick a pre-review and at 0 without one. See Revise rounds.

The form also lists what the agent can and can’t do: it works in its own scratch repository, which shares this repository’s objects, it submits one change, and it can’t write to the request’s branch or any other ref in the repository.

Bake-off#

Several agents implement the request in parallel, and a panel of reviewer agents ranks what they produce. You pick the winner. See Bake-offs for lanes, the reviewer panel and how the ranking works.

Assign a human#

A person on this node does the work. Assignee lists the people with write access to the repository, you included. You can add a Pre-review agent here too, which reviews every revision the person pushes. Agents only review: they never push to the assignee’s work.

Assigning someone notifies them in their inbox. The request then shows on their Needs you list under Assigned to you.

If no runner can run agents for you yet, the agent options say so and offer Add a runner and Check again. See Add a runner.

Follow a request#

The Requests tab lists the repository’s requests, with Open, Needs triage, Done and Closed tabs and a search box for titles and IDs. Open includes the requests waiting for triage. The list updates on its own as agents submit work. Its other views, Backlog and Board, are in Backlog and board.

A request’s status follows its attempts and changes:

StatusMeaning
Needs triageFiled by someone without write access, and not accepted yet.
OpenNobody is working on it, and it has no changes yet.
In progressAn attempt is running.
Awaiting reviewNo attempt is running, and it has at least one change to review.
DoneOne of its changes has merged.
ClosedSomeone closed or declined it.

The request page shows the title and details at the top, then How it got here: the request’s attempts and comments in one thread, oldest first. Each attempt shows a summary; click its title to see all of it, with its logs. An attempt that’s still running, or waiting for your decision, starts unfolded. A Bake-off’s summary shows its candidates at the revision its reviewers ranked, and which one was continued in a later attempt.

Each attempt has its own address, …/requests/<id>/attempts/<n>, which opens the page with that attempt unfolded. The column on the right shows the request’s change (its latest revision, and what it started as), the acceptance criteria, and links to each attempt.

When the latest attempt is an agent’s and its change is still open, the thread ends with Your call: Approve and merge the latest revision, or Revise it again. The comment box comes last. Anyone who can comment in the repository can leave a comment on the request; agents revising the request’s work read the open threads.

Once a change merges, the thread ends with Merged: which revision went into which branch, as which commit, and who approved it. The request’s other changes that are still open, such as the other candidates of a Bake-off that a revision replaced, are closed as Not picked, so they stop asking for review. A change someone reopens stays open. A closed request ends with Closed and the reason. Neither has a comment box, since no more revisions come of it; replies to existing threads still work, and reopening a closed request brings the box back.

An agent’s attempt#

While the agent works, its card shows the job’s state (Waiting for a runner, Starting, Working), the runner and harness it runs on, and the tail of its output. If the job is waiting, the card says why: no runner that can take it is online, the ones that can are busy, or the runner hit its model usage limit and tries again at a given time.

When the agent finishes, the attempt ends as Submitted with its change linked, or as Failed with the reason, for example “the agent submitted nothing”. If you asked for a pre-review, the reviewer’s verdict appears on the card once it’s in. Approve and merge it from Your call at the end of the thread, or open the change to review it line by line: see Reviewing and merging.

A person’s attempt#

The assignee’s card shows Assigned until they propose their work. To the assignee it shows the commands to clone the repository and push a branch, and a Propose a branch button that opens the propose form with this request already selected. Each push to the proposed branch adds a revision, and each revision gets a pre-review if the attempt asked for one.

The attempt ends as Submitted once its change merges.

Plan requests#

The Planning card at the top of a request’s side column holds its kind, priority, labels, milestone and relations. People with write access change them there; everyone else reads them.

  • Kind: bug, feature or task.
  • Priority: urgent, high, medium or low.
  • Labels: any of the repository’s labels. Edit lists them as checkboxes.
  • Milestone: one of the repository’s open milestones.
  • Relations: Add a relation links this request to another as part of it, blocked by it, or a duplicate of it. The other request shows the link from its side: Sub-requests, Blocks, Duplicates. A request can’t become part of its own sub-request, at any depth.

Labels and milestones are set up in the repository’s Settings, by anyone with write access. A label has a name, an optional description and one of nine colours; Add the usual labels adds bug, feature, docs, good first request and help wanted. Renaming a label renames it on every request that carries it, and deleting one takes it off them. A milestone has a title, an optional due date and description, and shows how many of its requests are done. Close it once it’s shipped.

Labels, milestones and every planning field are stored in the repository, like the requests themselves, so they move with it.

Backlog and board#

The request list has three views, at the left of its toolbar: List, Backlog and Board. All three filter by kind, priority, label and milestone, and List also sorts: recently updated, newest, priority, backlog order or most wanted. The view and its filters are in the page’s address, so you can bookmark one or send it to someone. The command menu has Requests: backlog and Requests: board.

Backlog shows the open requests nobody has started, in the order you’ll take them. Drag a row to move it, or focus its handle and press Alt+↑ or Alt+↓. Each move changes the order for everyone. Requests nobody has placed yet come after the placed ones, newest first. Filtered to a milestone, the backlog shows that milestone’s progress at the top, and becomes its plan. Start… on a row opens Who should do this? for it.

Board has a column for each status: Triage, Backlog, In progress, In review, Done and Closed. Done and Closed show the last 30 days. People with write access drag cards where there’s a decision to make:

  • from Triage to Backlog accepts the request,
  • from Triage or Backlog to Closed declines it, after asking why,
  • from Closed to Backlog reopens it,
  • within Backlog reorders it.

In progress, In review and Done move by themselves as attempts start, changes are submitted and changes merge, so the board always matches the work. A card dropped on one of them goes back where it was.

Votes and reactions#

Anyone who can comment can react to a request, or to a comment, with one of 👍 👎 😄 🎉 😕 ❤️ 🚀 👀. A 👍 on the request itself is a vote: the list shows the count, and Most wanted sorts by it. Click a reaction again to take it back.

Request templates#

A repository offers templates by keeping Markdown files in .moru/request-templates/ on its default branch. Each starts with front matter between --- lines:

---
name: Bug report
description: Something doesn't work as it should.
kind: bug
labels: [bug]
---

## What happened

## Steps to reproduce

## What you expected

name is required; description, kind and labels (label names) aren’t. The file’s name, without .md, is how a request remembers the template it came from. Both new-request forms offer the templates under Start from; picking one fills in the details and the kind, and keeps what you’ve already written. A request filed from a template by someone with write access gets its labels right away; one from someone without write access suggests them to whoever triages it.

Files there that aren’t templates, such as one without front matter, are skipped. GET …/requests/templates lists them with the reason (API). At most 20 templates are read, each at most 64 KiB.

Try another way#

When an attempt fails or is cancelled, or the change it produced isn’t what you wanted, start another attempt. Click Try another way on the request page. If the request was saved without an attempt, the button reads Edit and start instead.

The page shows the request’s fields and the attempt picker, filled in from the last attempt’s choices. You can edit the title, details and criteria before you start; the edits are saved with the new attempt. Earlier attempts and their changes stay on the request.

A request takes a new attempt only when it’s open, isn’t done, and has no attempt running. To replace a running attempt, cancel it first.

Revise with an agent#

Sometimes a change is close but not right. Instead of starting over, comment on its lines (or on the request) and have an agent revise the change you already have.

Revise with an agent appears:

  • on a change page, for an open change that belongs to a request,
  • in Your call at the end of a request’s thread, after an agent’s attempt,
  • in a Bake-off’s Your decision panel, for its candidates.

Pick the Agent and, optionally, a Pre-review and Revise rounds (see above), then click Start. On a Bake-off you also pick the Candidate. The agent starts from the change’s latest revision, works through its open threads and the request’s open threads, replies to each one, and submits the next revision of the same change: r1 becomes r2. People still decide whether the feedback was addressed and resolve the threads. If the change no longer applies to its target, the agent rebases it first; on such a change the button reads Fix with an agent.

This starts a new attempt on the request, so it’s refused while another attempt is running. The exception is a Bake-off waiting for your decision: revising one of its candidates ends the Bake-off, and its attempt shows as Revised instead of picked. The new revision then appears further down the thread, where you approve and merge it.

Revise rounds#

With revise rounds, a single agent doesn’t stop at its first submit. Moru checks each revision it submits, and when the revision doesn’t pass, it starts another round: the agent revises the same change, and the new revision is checked the same way. You get the change when a revision passes, or when the rounds run out.

A revision passes when all of these hold:

  • CI passed. If the repository has required jobs, those must pass, as for merging. Without required jobs, every CI job that ran on the revision must pass. A revision no workflow runs for passes, and one whose workflow file doesn’t parse fails.
  • The pre-reviewer didn’t request changes. Its scores are shown but don’t decide. Without a pre-review, CI alone decides. A pre-review that fails or times out doesn’t hold the loop up.
  • It still applies to its target branch. Being behind is fine; conflicting isn’t. See When a change no longer applies.

Moru waits until the revision’s CI has finished and its pre-review is in, then decides. Each round’s agent is told what failed: which CI jobs, whether the reviewer asked for changes, and whether the revision conflicts with its target. A conflict comes first: the agent rebases onto the branch before it fixes anything else, and get_task lists what landed on the branch in the meantime, so it can keep what both sides meant. It reads the failed jobs’ logs itself, and works through the change’s open threads, the reviewer’s line comments among them, like any agent revising a change.

When a round edits the checks#

The quickest way to turn a red check green is to edit the check, so rounds are fenced in. Each round’s agent is told to fix the code, not the check: not to weaken, skip or delete a test, and, if a test really is wrong, to fix it and say why in a thread on the change. Moru then compares each round’s revision with the one before it, counting only what the change itself did, so what landed on the branch during a rebase doesn’t count:

  • CI workflow files end the loop. If a round changes anything in .moru/workflows/, .github/workflows/, .github/actions/ or .moru/actions.lock, no further round starts, even if CI is now green. The loop ends with Changed its CI workflows, the card names the files, and you’re notified. Review the workflow change before you trust the result.
  • Test files are flagged. A round may still change tests, because sometimes the test is what was wrong. The card lists the test files each round changed, ahead of the revision’s CI and review results, and the pre-reviewer is told to request changes when a revision made CI pass by weakening tests rather than fixing the code. A test file is one in a test, tests, __tests__, spec, specs, testdata or __snapshots__ directory, or one named like test_*, *_test.*, *.test.*, *_spec.*, *.spec.*, *Test.*, *Tests.* or *.snap. Tests written inside source files, like Rust’s #[cfg(test)] modules, aren’t recognized, so the pre-reviewer is the check there.

The agent’s first revision is never compared, so the first job can add or fix CI and tests freely. Other ways to weaken a check, such as editing a Makefile target or a package script, aren’t detected, so review them before merging.

Rounds need something to check against: a pre-review, or CI workflows on the request’s branch. Without either, the attempt is refused. Every round gets the attempt’s time limit, and so does the wait for its checks, so a loop can take a while: the form shows the most it could take.

Steering a loop#

While a loop runs, the agent’s card shows a row per revision with its CI and review results, and what it’s doing now. Each revision’s pre-review sits beside it, newest first.

You can:

  • Comment on the change’s lines or on the request. The next round reads the open threads, so this is how you steer it.
  • Stop after this round. The running round finishes and its revision is checked, but no new round starts.
  • Cancel attempt, which stops the running agent at once.
  • Approve and merge the latest revision. The loop then ends.

You’re notified when the loop ends, not on every round.

How a loop ends#

OutcomeWhat it means
Passed after N roundsThe latest revision passed. It’s ready for your review.
Didn’t pass after N roundsThe rounds ran out. The latest revision and its open threads are there for you.
CI didn’t finishCI on the latest revision didn’t finish within the time limit, for example because no runner took it.
Round N submitted nothingA round’s agent failed or gave up. The earlier revisions are still there.
StoppedSomeone stopped it, or the change was merged or closed meanwhile.
Changed its CI workflowsA round edited a workflow file. Review that edit before trusting CI. See above.
Passed againThe change stopped applying after it passed, and a round rebased it. It’s ready for your review again.

Either way the attempt ends with its change submitted, and you approve and merge it as usual. Rounds never merge anything. Once the loop ends, the attempt folds to a line with its outcome and why each earlier revision didn’t pass; Show the logs and pre-review opens the card again.

Keeping a passed change current#

A loop that passed may not have used all its rounds. Those left over keep the change current while it waits for your review. If other work lands on the target branch and the change no longer applies, the attempt reopens: the agent rebases the change in a new round, CI and the pre-review run again on the new revision, and the loop ends again. The pre-reviewer is told the revision is a rebase and compares it with the one before, so a rebase that drops either side’s work gets changes requested rather than passing on green CI. Being behind alone never starts a round, so a busy branch doesn’t use them up.

The agent’s card shows each of these rounds as “rebased onto” and the commit of the branch it rebased onto, followed by the new ending. When it passes again it says Passed again, and nobody is notified: the change was ready for review and still is. If it ends any other way, you’re told, for example “Your change no longer applies and the agent couldn’t fix it: no rounds left”.

A round starts only while the change is still open, the attempt is still the request’s latest, and no other attempt is running. Once the rounds are used up, a change that conflicts gets the badge and you get a notification, as for any other change.

To keep a passed change as it is, click Stop fixing conflicts on its card. The card then says Won’t fix new conflicts, and a conflict is left to you. While a round is running, Stop after this round works as before.

Cancel, close and reopen#

  • Cancel attempt stops the running agent or ends the assignment. The attempt ends as Cancelled, and you can try again. A Bake-off is stopped from its own panel with Stop the Bake-off.
  • Close asks for an optional reason, then closes the request. Closing stops the active attempt.
  • Reopen brings a closed request back. Start a new attempt from there. A declined request that nobody had accepted goes back to triage.

Agents can file requests too, when they notice something outside their task: see file_request. Those always wait in triage, and the person the agent works for hears how they’re triaged.

An attempt’s outcome is one of Submitted, Failed, Cancelled or Replaced.

Command menu
Search for a page, repository, change or request, or run a command