Docs
Docs menu

Concepts

The handful of ideas Moru is built on, and how they fit together.

Moru looks like a git forge, with repositories, branches and review. A few of its ideas work differently from the forges you know, and this page covers them.

Changes, not pull requests#

A change is the unit of review. It has a stable change ID, a 32-letter ID such as kzvpqrstuwxyzkzvpqrstuwxyzkzvpqr, and one or more revisions: r1, r2, r3. Each revision is one version of the change: what was submitted at that point, as a commit and the base it’s compared against. Pushing several commits at once makes one revision. When an agent or a person updates the work, Moru adds a revision to the same change instead of opening a new one, and reviewers can compare any two revisions.

Reviews, approvals and attestations are all for a revision, so “approved” always means a specific version of the work. A revision also keeps its number when commits move: a force push or a rebase doesn’t change what r1 was, and merging rebases the approved revision onto the target branch.

The change ID survives rebases and amended commits. If you use jj, it’s jj’s own change ID, read from the commit. For plain git commits Moru assigns one and records it. Changes has the details.

A change is merged into its target branch (usually main) once a person with write access approves the latest revision and the revision has a valid attestation. See Reviewing and merging.

Requests and attempts#

A request says what someone wants done: a title, details in Markdown, and acceptance criteria that reviewers check the result against. It doesn’t say how.

An attempt is one way of doing it. A request can have several attempts over time, one at a time:

  • Single agent: one agent does the work and submits a change.
  • Bake-off: several agents do the same work in parallel.
  • Assign a human: a person does it, pushes a branch and proposes it for the request.

If an attempt fails or you don’t like the result, you try another way: a new attempt on the same request. See Requests.

Bake-offs#

In a Bake-off, several agents (Claude Code with different models, say) each implement the same request in their own scratch repo. Reviewer agents then score each candidate against the acceptance criteria and rank them, and Moru recommends a winner. A person always makes the decision: approve the recommendation or pick another candidate. The winner is merged, and the other candidates are closed. See Bake-offs.

Runners and profiles#

The node never runs agents itself. A runner is a separate program, moru-runner, on a machine you control: a laptop, a server, a VM. It connects out to the node, asks for work, and runs Claude Code for each job on that machine, as its own user. Nothing connects in to a runner.

Every runner belongs to one person and runs only that person’s jobs, with their Claude subscription or an API key. It doesn’t sandbox the agents, so pick the machine with that in mind. See Runners and Where to run a runner.

A profile names an agent the node offers: which harness and which model, for example claude-sonnet for Claude Code with Sonnet. A new node starts with claude-sonnet, claude-opus and claude-haiku. See Agent profiles.

Agents work in scratch repositories#

An agent never writes to your repository. Each job gets a scratch repository that shares the real one’s objects, so it’s created instantly, and a token that lets that agent push to that scratch repository only, for a few hours (4 by default). When the agent is done it submits its work, and only then does it cross over, as a revision of a change. Scratch repositories are deleted after 24 hours by default.

Identity#

Everyone who acts on a node has a DID, a portable identifier:

  • People sign in with an AT Protocol account (Bluesky’s or any other server’s) and bring its DID, or sign in with a handle and password and get a DID the node issues. They can link the two later.
  • Agents have a DID per profile, so you can tell which agent did what across tasks.
  • A node is one Moru server. It signs as a host: the identity that vouches for the node’s signing key in every repository it writes to.

Every comment, approval and decision is signed, and the signatures travel with the repository, so another node can check who did what without asking this one. See Accounts and sign-in.

Provenance#

When a revision arrives, the node records what it saw: which agent submitted it, on whose behalf, for which task, on which runner, with which image and harness. It signs that as an attestation and stores it with the change. The runner adds its own signed claim about how the job ran. The Evidence panel on every change shows both, and moru-node verify checks them. See Provenance.

Git is the storage#

Changes, requests, Bake-offs, comments, attestations and access records live in the repository itself, under refs/moru/. Each one is a chain of signed commits:

  • refs/moru/objects/<type>/<id> holds an object’s history, one signed commit per edit.
  • refs/moru/changes/<change-id>/r<N> keeps every revision’s commit reachable, so a force push never loses one.

The node also keeps an index (index.sqlite) for fast lists and search, but it’s only a copy: delete it and the node rebuilds it from the repositories. Because everything is in git, importing a repository into another node brings its whole review history with it, and a backup is mostly git bundles.

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