Murmurent

Shared AI infrastructure for researchers, labs, core facilities and research centres. Murmurent gives a research group a set of AI assistants, called agents, that know the group's data, its conventions and its accumulated findings. Each group works independently, and can pool its agents and data with other groups when collaboration helps.

There are three ways to use it: on your own, as a way of working with the other members of your lab, or as shared infrastructure across many labs and core facilities at an institution.

Documentation: https://hallettmiket.github.io/murmurent/

Stuck on any step? Once Claude Code is installed, ask it. Murmurent puts its own documentation and commands inside Claude Code, so questions such as "walk me through installing Murmurent", "did my install work?" or "how do I issue a member card?" are answered directly, and it can run many of these steps for you.

Contents

1. Install it
2. Say who you are
3. Set up a folder to work in
4. Keep it up to date
5. What to do next, according to what you are doing
6. Getting help

1. Install it

You need Python 3.12 or newer, but you do not have to install it yourself: uv fetches the right version. If you do not have uv, one line installs it.

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install Murmurent.

uv tool install murmurent
murmurent install
murmurent doctor

Those three commands download Murmurent, connect it to Claude Code, and check that it worked. Run murmurent doctor whenever something looks wrong: it reports each problem it finds together with the command that corrects it.

If your shell cannot find murmurent afterwards, close the terminal and open a new one. uv puts the command in ~/.local/bin.

curl -fsSL https://raw.githubusercontent.com/hallettmiket/murmurent/main/scripts/bootstrap.sh | bash

2. Say who you are

murmurent init

This records your name, your email, your institutional username, and your GitHub and Slack accounts. Everything else is built on it, whether or not you ever join a lab.

It also asks which of three roles you hold, so decide before you start.

murmurent whoami shows what was recorded.

3. Set up a folder to work in

The agents are available in every folder on your machine as soon as you install, so setting up a particular folder is not what gives you them. It does something different: it turns on Murmurent's check on sensitive data, which removes personal identifiers from anything leaving your machine, such as a web search or a fetched page. That check does not run in folders you have not set up. Setting up a folder also allows it to join a Murmurent project later.

Do this for any folder holding research data, and for every folder holding sensitive data.

Murmurent works in folders that git tracks and that live under ~/repos/. Ask what state your folder is in.

murmurent repo status ~/repos/<folder>

Then run the command beside the answer you get.

Neither command needs options, and neither alters anything already in the folder. Your files, your history and any Claude Code settings of your own are left as they are. What is added is a .murmurent.yaml file recording the setup, a CLAUDE.md template, and VS Code settings. Commit the first two, and everyone else working in that folder has the same setup.

To mark a folder as holding sensitive data, add one line to .murmurent.yaml.

sensitivity: clinical

murmurent repo list shows the state of every folder on your machine at once.

Setting up a folder is separate from creating a Murmurent project, which is a different thing and does not happen automatically. See Making a repo Murmurent-ready.

4. Keep it up to date

uv tool upgrade murmurent
murmurent install

Run murmurent install with no options. It completes the update everywhere it is needed, including in the folders you have already set up, and it is safe to run when nothing has changed.

Changes to the wording of an agent or a rule take effect with no command at all. A newly added agent arrives with the murmurent install above. There is never anything to run folder by folder.

If you installed from a clone rather than from PyPI, replace the first command with git pull inside that clone, followed by uv tool install --python 3.12 --reinstall -e .. Use uv rather than pip here. The pip on your path often belongs to a different Python installation, such as a conda environment, and then the upgrade either lands in the wrong place or stops with an error about the Python version.

5. What to do next

Find the row that describes you.

6. Getting help

Ask Claude Code first. It has Murmurent's documentation and commands available, and can usually diagnose and repair an installation problem directly.

Failing that, TROUBLESHOOTING.md covers the common installation problems. Bug reports and requests for new features go to the development repository, where the work happens. Issues are turned off here deliberately, so that the discussion stays in one place.

The three repositories

Authors

Mike Hallett — michael.hallett@uwo.ca

Licensed under Apache-2.0. See LICENSE.