Read Me First — MR Universe

Welcome. If you have just come across MR Universe and are wondering what it is, whether it is meant for you, and where to begin, this is the page to read. It uses plain language throughout. When you are ready for step-by-step instructions, the map of the other documents near the end tells you where to go next.

---

1. Who this is for

MR Universe is for organisations that build software and keep many pieces of it together in one shared code base.

• The people who use it every day are the engineers who look after how software is built and tested: often called platform, developer experience or build engineers. It suits teams of roughly 50 to 500 developers.
• The people who benefit from it include engineering leaders who want build and test pipelines that run faster and cost less, and security or compliance staff who need to know exactly what third-party software went into each product.

You do not need to be one of these people to understand it. This page assumes no programming knowledge.

---

2. What it does

MR Universe is a tool you run from a terminal window (there are no screens to click through). Pointed at a code base, it:

• draws the map: it finds every separate piece of software in the code base and works out which pieces depend on which;
• works out what a change touches: when someone edits one piece, it tells you exactly which other pieces could be affected;
• does only the work that is needed: it builds and tests only those pieces, in the right order, and reuses earlier results for everything that did not change;
• produces security paperwork as it goes: an "ingredients list" for each piece of software, and a check of those ingredients against a list of known security problems;
• helps with releases: it works out new version numbers from the team's own notes on each change, and can publish pieces in the right order;
• answers questions from AI assistants: it can tell an AI coding assistant what a change affects, giving exactly the same answer the tool itself would give.

It is open source, it runs on your own computers, and it needs no account, no server and no subscription.

---

3. The domain: how software teams build software

Some background, for anyone outside the software trade.

A modern software product is rarely one single program. It is made of many smaller pieces, called packages: a website, a mobile back end, a shared library of building blocks, a payments service, and so on. Each piece may be written in a different programming language. In this field the common ones are TypeScript and JavaScript, Python, Go and Rust.

Teams store these pieces in a repository, a shared, versioned store of all the code. Many organisations now keep all their pieces in one large repository, called a monorepo (short for "mono repository"). That is the "MR" in MR Universe. A monorepo makes it easy to see and change everything together, but it brings a cost: every time someone changes anything, the safe thing to do is to rebuild and retest everything. On a large code base that can take an hour or more, many times a day, on paid computing time.

Teams run that rebuilding and retesting automatically on shared machines, a practice called continuous integration, or CI. Making CI fast, cheap and trustworthy is a large part of the job for the engineers this tool is for.

Two further pressures have grown in recent years:

• Supply-chain security. Most software is assembled partly from outside components written by others. Customers and regulators increasingly ask for a list of those components, a software bill of materials (SBOM), and expect known security problems in them to be caught before release.
• AI coding assistants. Developers now work alongside AI tools that need accurate facts about the code base. An assistant that guesses wrongly about what a change affects can cause real harm.

MR Universe addresses all three: slow builds, supply-chain paperwork and trustworthy answers for AI tools.

---

4. Where it fits

Who uses it. Software organisations whose code base holds several pieces, especially pieces written in more than one programming language. Other tools in this space tend to handle only JavaScript and TypeScript well; MR Universe is built to handle several languages in one tool, including when a piece in one language depends on a piece in another.

Where it runs. On a developer's own computer, and inside the team's automated build system (CI). It works with any CI service that can run a command; it is not tied to one vendor.

What it works alongside:

• Git, the version-control system almost every software team uses. MR Universe reads the history from git to work out what has changed.
• Each language's own tools. It does not replace the commands your team already uses to build or test each piece. It runs those commands for you, in the right order, and only when needed.
• A shared folder, if you want the whole team and the CI machines to reuse each other's build results. Any folder every machine can reach will do: a network drive or a volume your CI service provides.
• Package registries, the public or private catalogues where finished software is published (for example, the ones for JavaScript, Python or Rust). Its release feature publishes to these using each language's own publishing command.
• AI coding assistants that support the Model Context Protocol (MCP), an open standard for giving assistants access to tools.

What it does not do. It has no web interface and no online service, it does not fetch information from the internet, and it does not offer an API for other systems to call over a network. It reads your code base and reports, and that is all.

---

5. First run

The simplest way to install MR Universe is from crates.io, the registry for software written in Rust. With the Rust language tools installed, the single command cargo install mruniverse downloads it and builds it in a few minutes. Ready-made downloads that need no Rust tools are planned. The installation guide covers this, and also building from the source code, which you obtain from the project home at https://wbsp.ai/catalog/monorepo-management-tool. You need the source for the sample code base below, because the samples come with it.

Once it is built, the best first step is to try it on the small sample code base that comes with it, before pointing it at your own. The getting-started guide walks you through this in about five minutes:

1. Ask it to draw the map of the sample (the mruniverse graph command). You will see the sample's three pieces and how they depend on each other.
2. Ask it to build everything (mruniverse run build). Notice it builds the pieces in dependency order.
3. Run the same build again. This time every piece is reported as coming from the cache. Nothing was rebuilt, because nothing changed. That moment is the heart of the product.
4. Make a change to one piece and ask what it affects (mruniverse affected). Only that piece and the ones that depend on it are listed.

---

6. Setting up your working environment

Setting MR Universe up on a real code base takes four steps. Your engineers will do these once.

1. Describe the code base. In the top folder of your repository, the mruniverse init command looks around, finds your pieces and writes a short settings file called mruniverse.toml. Your engineers then add the tasks they want it to run (such as "build" and "test") and which pieces each depends on. The configuration reference lists every setting.
2. Connect it to your build system (CI). Have your CI service run MR Universe instead of rebuilding everything. Typically it builds and tests only the pieces affected by each proposed change. The CI guide has ready-made examples.
3. Optionally, share results across the team. Set up a remote shared cache: a shared folder plus a secret password ("token") that every machine is given. Then a result built once, anywhere, is reused everywhere. The remote cache guide explains it. If the shared folder is ever unreachable, builds simply carry on without it; nothing fails.
4. Optionally, switch on the extras:
   • Architecture rules: rules such as "shared libraries must never depend on applications", checked automatically. See the security guide.
   • Security scanning: give the tool a list of known security advisories, a single file your team supplies and keeps up to date. The tool never downloads advisories itself. See the security guide.
   • Releases: see the release guide.
   • AI assistants: register MR Universe with your assistant. See the AI / MCP guide.

There is no data to upload and nothing to sign up for. Everything MR Universe needs already lives in your repository.

---

7. Day to day

Once it is set up, most people barely notice MR Universe: it makes their builds faster. The routine tasks look like this:

• A developer makes a change and asks what it affects, then builds and tests just those pieces on their own computer, reusing cached results for the rest.
• CI checks every proposed change the same way: only the affected pieces are built and tested, and results are shared through the remote cache if you set one up.
• The architecture check runs in CI and stops a change that breaks one of your rules, before the problem spreads.
• The security scan runs in CI. If an outside component has a known problem at or above the severity you choose (by default, "high"), the run fails so it cannot be missed. If the tool cannot tell which version of a component will be used, it says so plainly as "undetermined" instead of guessing.
• At release time, someone asks for a release plan. MR Universe reads the notes left on each change since the last release and proposes new version numbers. Nothing is written until they confirm. They can then have it write the new versions and change logs, and publish the pieces in the right order. If one publication fails, it reports exactly what was and was not published.
• When an ingredients list is requested, by a customer, an auditor or your own security team, MR Universe produces one per piece in either of the two industry- standard formats (called SPDX and CycloneDX).
• Developers using AI assistants can ask the assistant what a change affects, and get the same answer the tool gives.

---

8. Ongoing care

MR Universe needs very little looking after. The things to keep an eye on:

• Keep the security advisory list current. The scan is only as good as the list you give it. Agree who refreshes it and how often, for example weekly, or whenever your security team publishes an update. An out-of-date list cannot warn you about new problems.
• Keep the settings file up to date. When a new piece is added to the code base, or a team changes how something is built, update mruniverse.toml so the map stays right. Running the map command after such changes is a quick sanity check.
• Disk space used by the cache. Each computer keeps its cached results in a hidden folder called .mruniverse at the top of the repository, and the shared cache keeps its own copy. There is no automatic clean-up yet. Deleting either is safe: the next build simply recreates what it needs, a little more slowly the first time.
• Look after the shared-cache token. Treat it like any other password. To change it, replace it in the shared folder and give the new one to your CI service and your team. A machine with a wrong or missing token simply builds without the shared cache.
• Backups. MR Universe keeps no data of its own that needs backing up. Your code, your settings file and your advisory list live in your repository, and are backed up however you back that up. The caches can always be rebuilt.
• Reports. The ingredients lists and scan results are produced fresh each time they are asked for. If you need a record over time, for audits for example, have CI save them alongside each release.

---

Glossary

Term	Meaning
Package	One separate piece of software in the code base, such as an app, a service or a shared library.
Repository	The shared, versioned store where a team keeps its code.
Monorepo	A single repository holding many packages. "MR" in MR Universe stands for mono repo.
Dependency	When one package uses another, it depends on it.
Dependency graph	The map of which packages depend on which.
Affected packages	The packages a change could influence: the ones changed directly, plus everything that depends on them.
Task	A job run on each package, such as "build" or "test".
Cache	Stored results of earlier tasks, reused when nothing relevant has changed.
Remote shared cache	A cache in a shared folder, so the whole team and CI reuse each other's results.
CI (continuous integration)	Automated building and testing of every change on shared machines.
Git	The version-control system that records every change to the code.
SBOM (software bill of materials)	An ingredients list of the components that make up a piece of software.
SPDX / CycloneDX	The two industry-standard formats for SBOMs.
Advisory	A published notice that a specific version of a component has a known security problem.
Severity	How serious an advisory is: critical, high, medium or low.
Undetermined	The tool knows a component has had a problem, but cannot tell which version will be used, so it flags it for a person to check.
Architecture rule / constraint	A rule about which packages may depend on which.
Release / publishing	Giving packages new version numbers and making them available in a package registry.
Package registry	A public or private catalogue where finished packages are published.
MCP (Model Context Protocol)	An open standard that lets AI assistants use tools such as this one.
mruniverse.toml	The settings file that describes your code base to MR Universe.

---

A map of the other documents

Everything below lives alongside this page.

Document	What it is for
Getting started	A friendly, plain-language introduction and a five-minute try-out on the sample. Read this next.
Installation	Building MR Universe from source and checking it works.
User guide	A narrative walkthrough of every command in practice.
CLI reference	Every command, option and result code, for engineers.
Configuration reference	Every setting in mruniverse.toml.
CI guide	Connecting MR Universe to your automated build system.
Remote cache guide	Sharing build results across machines.
AI / MCP guide	Connecting AI coding assistants.
Security guide	Ingredients lists, security scanning and architecture rules.
Release guide	Version numbers, change logs and publishing.
Performance notes	How fast it is and what affects speed.
Useful commands	A cheat-sheet for the engineers who work on MR Universe itself.
How it's tested	The testing MR Universe has been put through, in plain terms.
Positioning and capability ledger	What the product is, how we describe it, and the evidence behind every claim.
Documentation home	The full index, including sales and marketing material.

---

User roles

MR Universe has no user accounts and no roles. Anyone who can run it on a code base can use every feature. Control over who may do what comes from the systems around it:

• who can change the repository, which is set in your git hosting;
• who holds the shared-cache token, because a valid token is needed both to read and to write the shared cache;
• who holds the credentials to publish to your package registries.

---

Sample data, and starting fresh

The source code comes with small sample code bases used for trying it out and for its own testing, including the three-piece example that the getting-started guide uses, and others covering Python, Go, Rust and a mix of languages. They contain no real data. Whenever you change a sample (editing files or making commits), work on a copy of it, as the guides show, so the originals stay as they are.

To start fresh on your own code base, run mruniverse init in its top folder to create a new settings file. To clear out cached results at any time, delete the .mruniverse folder; nothing is lost, it is rebuilt on the next run.

---

Common questions and gotchas

Does it replace our existing build tools? No. It runs them for you, in the right order, and only when needed.

Is it only for JavaScript? No. It handles TypeScript and JavaScript, Python, Go and Rust, including pieces that depend on pieces in another language. Pieces in other languages, such as Java, are still found and built, but their dependencies are not read automatically: you list them in the settings file.

Does it send our code anywhere? No. It runs on your machines, contacts no internet service itself, and the shared cache is a folder you control. The one exception is when you ask it to publish a release: it then hands each package to that language's own publishing command, which uploads it to your package registry.

The second build was instant. Did it actually do anything? Yes: it checked every input and found nothing had changed, so it reused the earlier results. Change something and it rebuilds exactly the parts affected.

It says a change affects nothing, but I just changed a file. The comparison is with a starting point, usually your main line of work. If the change is already part of that starting point, there is nothing new to compare. Make the change on a separate line of work (a branch), as the getting-started guide shows.

The security scan passed. Are we safe? It means no known problem at or above your chosen severity was found in your advisory list. It is only as current as that list. Also look at anything marked "undetermined".

Can the AI assistant make it skip tests? No. The AI interface is read-only, and it never reports fewer affected pieces than the tool itself would.

Where do I download it? Install it with cargo install mruniverse, which needs the Rust language tools. Ready-made downloads that need no Rust tools are planned. The source code is at the project home, https://wbsp.ai/catalog/monorepo-management-tool. See the installation guide.

---

Where to get help

• The wbsp.ai community at https://wbsp.ai: ask questions, report problems, suggest improvements, and find people who can tailor MR Universe to your organisation. While you are there, look around. Community members build many versions of this and other applications.
• The project home at https://wbsp.ai/catalog/monorepo-management-tool: the source code and documentation. It does not take issues or pull requests, so bring problems and ideas to the wbsp.ai community instead.