Metadata-Version: 2.5
Name: murmurent
Version: 2026.11.2
Summary: Multi-group agentic infrastructure for a bioconvergence centre — with the v1 registrar layer above any single lab.
Project-URL: Homepage, https://github.com/hallettmiket/murmurent
Project-URL: Documentation, https://hallettmiket.github.io/murmurent/
Project-URL: Issues, https://github.com/hallettmiket/murmurent_dev/issues
Project-URL: Source, https://github.com/hallettmiket/murmurent
Project-URL: Changelog, https://github.com/hallettmiket/murmurent/blob/main/CHANGELOG.md
Author-email: Mike Hallett <michael.hallett@uwo.ca>
License: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.40
Requires-Dist: click>=8.1
Requires-Dist: cryptography<=46.0.3,>=42; sys_platform == 'win32' and platform_machine == 'ARM64'
Requires-Dist: cryptography>=42; sys_platform != 'win32' or platform_machine != 'ARM64'
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: slack-sdk>=3.30
Requires-Dist: sse-starlette>=2.0
Requires-Dist: uvicorn>=0.30
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.115; extra == 'dashboard'
Requires-Dist: httpx>=0.27; extra == 'dashboard'
Requires-Dist: streamlit>=1.30; extra == 'dashboard'
Requires-Dist: uvicorn>=0.30; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: isort>=5.13; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Provides-Extra: gcal
Requires-Dist: google-api-python-client>=2.130; extra == 'gcal'
Requires-Dist: google-auth-httplib2>=0.2; extra == 'gcal'
Requires-Dist: google-auth-oauthlib>=1.2; extra == 'gcal'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
Provides-Extra: slack
Requires-Dist: anthropic>=0.40; extra == 'slack'
Requires-Dist: slack-sdk>=3.30; extra == 'slack'
Description-Content-Type: text/markdown

<!-- The user-facing README. In the development repository this file is
     release/README_public.md; release/make_release.sh copies it to README.md
     when it builds the release tree. Edit it there, not here: a change made in
     the release repo is overwritten by the next release.

     Keep it short (issue #161): one command per step, and a link for every
     special case. Detail belongs in docs/. -->

# Murmurent

<!-- Badges: images drawn by shields.io from live data (PyPI, GitHub). -->
[![PyPI](https://img.shields.io/pypi/v/murmurent?label=PyPI)](https://pypi.org/project/murmurent/)
[![Downloads](https://img.shields.io/pypi/dm/murmurent?label=downloads)](https://pypistats.org/packages/murmurent)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-mikehallett.science-6f4da8)](https://mikehallett.science/murmurent/)
[![Built on Claude Code](https://img.shields.io/badge/built%20on-Claude%20Code-d97757)](https://claude.com/claude-code)
[![Stars](https://img.shields.io/github/stars/hallettmiket/murmurent?style=flat)](https://github.com/hallettmiket/murmurent/stargazers)

AI assistants for research groups, built on Claude Code. Each lab keeps
control of its own people and data, and can share with other labs when that
helps.

**▶ [Watch the 7-minute getting-started video](https://mikehallett.science/assets/videos/murmurent_getting_started.html)**

**📖 [Read the documentation](https://mikehallett.science/murmurent/)**: getting
started, joining a lab, projects, the agents, and every command.

You need a Mac or Linux computer with
[Claude Code](https://claude.com/claude-code) installed and signed in.

## 1. Install

Install `uv`, the tool that installs Murmurent:

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

Open a new terminal, then:

```bash
uv tool install murmurent
murmurent install
murmurent doctor
```

`murmurent doctor` checks the install. If something is wrong, it prints the
command that fixes it.

You also get a **Murmurent Dashboard** icon: in Applications on a Mac, in
the applications menu on Linux.

## 2. Say who you are

```bash
murmurent init
```

It asks for your name, your email and your role: **member** (you work in a
lab), **PI** (you lead a lab or core facility) or **mayor** (you run a centre).

## 3. Set up a folder

Do this for every folder that holds research data. It turns on the check that
removes patient identifiers from anything leaving your computer.

```bash
murmurent repo adopt ~/repos/<folder>
```

The folder must be a git repository inside your repositories folder (`~/repos`
unless you chose another).
[If it does not work](https://mikehallett.science/murmurent/install_special_cases/#setting-up-a-folder-did-not-work).

## 4. Start working

```bash
cd ~/repos/<folder>
claude
```

Ask Claude Code anything, including "how do I use Murmurent?".

## Updating

```bash
uv tool upgrade murmurent
murmurent install
```

## Next

- [See what Murmurent can do](https://mikehallett.science/murmurent/getting_started/)
- [Join your lab](https://mikehallett.science/murmurent/identity/#members-join-a-group)
- [Set up your lab or core](https://mikehallett.science/murmurent/identity/#pis-set-up-your-lab-standalone-no-mayor-needed)
- [Start a centre](https://mikehallett.science/murmurent/centre_overview/)
- [All documentation](https://mikehallett.science/murmurent/)

<!-- videos-and-news: generated by training/front_page.py from training/index.yaml; do not edit -->

## Videos and news

Every video, in one place: <https://mikehallett.science/assets/videos/>. Each one says which release it was checked against;
when a video and the written documentation disagree, the documentation is right.

| Video | Length | Covers |
|---|---|---|
| [Getting started with Murmurent](https://mikehallett.science/assets/videos/murmurent_getting_started.html) | 7:10 | What Murmurent is, installing it, saying who you are, setting up a folder, the agents, and joining a lab or a centre. (checked against 2026.11.0) |
| [A thesis an examiner can question](https://mikehallett.science/assets/videos/murmurent_thesis_package.html) | 6:20 | Paper packages, thesis packages and the docent. Who is in the room at a defence, how every claim is mapped to its evidence, what the candidate runs, how an examiner questions the package. (checked against 2026.11.0) |
| [Working through Claude Code](https://mikehallett.science/assets/videos/murmurent_claude_code.html) | 2:09 | You type plain English to Claude Code, name an agent when you want one, read the first line of every reply for the answer, and keep what you find in your own notebook and oracle. (checked against 2026.11.0) |
| [Backing up with /murmurent-push](https://mikehallett.science/assets/videos/murmurent_push.html) | 2:06 | The two backup skills: the checks that keep an access key or a large data file from leaving, backing up a whole project at once, and the note to the project's channel. (checked against 2026.11.0) |
| [A status update with /murmurent-update-me](https://mikehallett.science/assets/videos/murmurent_update_me.html) | 2:11 | The status-update skill: a plain-English note for the project's channel, built from facts the computer reads fresh each time, what stays out of the channel, and the dry run that shows the note without posting it. (checked against 2026.11.0) |
| [Learning a subject with teacher course](https://mikehallett.science/assets/videos/murmurent_course.html) | 2:18 | The teacher's course mode: an interview for your goal, lessons you mark up, a quiz in each, and a record of what you have shown you know, so nothing is taught twice. (checked against 2026.11.0) |
| [The mayor's and PI's tools](https://mikehallett.science/assets/videos/murmurent_mayor_tools.html) | 2:27 | The three administrative skills: priming context before admin work, processing an encrypted join request with an explicit decision, and resetting a machine after a backup and a dry run. (checked against 2026.11.0) |
| [Your lab notebook](https://mikehallett.science/assets/videos/murmurent_notebook.html) | 2:52 | A bench scientist's day with the lab notebook: the experimental design if you like, a gel photo from the phone, a voice note with gloves on, a prompt written in Obsidian and sent to Claude Code with one keystroke, the day recalled, and a report for the supervisor. Natural language throughout; the commands as footnotes. (checked against 2026.11.1) |
| [The data root: where big files live](https://mikehallett.science/assets/videos/murmurent_data_root.html) | 2:52 | Murmurent's third tier of memory: the lab's data root on its server, what immutable, append_only, modifiable, mothballed, release, cottage, tools and db are for, how a project's folders mirror its repository, what the hooks refuse, and the layout check. (checked against 2026.11.0) |

One two-minute movie per agent: what it does, what it will not do, one real run, and how to
use it through Claude Code.

| Agent | Movie | Length |
|---|---|---|
| [`oracle`](https://github.com/hallettmiket/murmurent/blob/main/agents/oracle.md) | [The oracle](https://mikehallett.science/assets/videos/murmurent_agent_oracle.html) | 2:06 |
| [`bookworm`](https://github.com/hallettmiket/murmurent/blob/main/agents/bookworm.md) | [The bookworm](https://mikehallett.science/assets/videos/murmurent_agent_bookworm.html) | 2:31 |
| [`adversary`](https://github.com/hallettmiket/murmurent/blob/main/agents/adversary.md) | [The adversary](https://mikehallett.science/assets/videos/murmurent_agent_adversary.html) | 2:40 |
| [`artist`](https://github.com/hallettmiket/murmurent/blob/main/agents/artist.md) | [The artist](https://mikehallett.science/assets/videos/murmurent_agent_artist.html) | 1:43 |
| [`scribe`](https://github.com/hallettmiket/murmurent/blob/main/agents/scribe.md) | [The scribe](https://mikehallett.science/assets/videos/murmurent_agent_scribe.html) | 2:07 |
| [`teacher`](https://github.com/hallettmiket/murmurent/blob/main/agents/teacher.md) | [The teacher](https://mikehallett.science/assets/videos/murmurent_agent_teacher.html) | 3:00 |
| [`lab_oracle`](https://github.com/hallettmiket/murmurent/blob/main/agents/lab_oracle.md) | [The lab oracle](https://mikehallett.science/assets/videos/murmurent_agent_lab_oracle.html) | 1:41 |
| [`blacksmith`](https://github.com/hallettmiket/murmurent/blob/main/agents/blacksmith.md) | [The blacksmith](https://mikehallett.science/assets/videos/murmurent_agent_blacksmith.html) | 1:51 |
| [`conscience`](https://github.com/hallettmiket/murmurent/blob/main/agents/conscience.md) | [The conscience](https://mikehallett.science/assets/videos/murmurent_agent_conscience.html) | 2:32 |
| [`lawyer`](https://github.com/hallettmiket/murmurent/blob/main/agents/lawyer.md) | [The lawyer](https://mikehallett.science/assets/videos/murmurent_agent_lawyer.html) | 2:19 |
| [`millwright`](https://github.com/hallettmiket/murmurent/blob/main/agents/millwright.md) | [The millwright](https://mikehallett.science/assets/videos/murmurent_agent_millwright.html) | 2:01 |
| [`centre_millwright`](https://github.com/hallettmiket/murmurent/blob/main/agents/centre_millwright.md) | [The centre millwright](https://mikehallett.science/assets/videos/murmurent_agent_centre_millwright.html) | 1:41 |
| [`judge`](https://github.com/hallettmiket/murmurent/blob/main/agents/judge.md) | [The judge](https://mikehallett.science/assets/videos/murmurent_agent_judge.html) | 2:17 |
| [`registrar`](https://github.com/hallettmiket/murmurent/blob/main/agents/registrar.md) | [The registrar](https://mikehallett.science/assets/videos/murmurent_agent_registrar.html) | 1:45 |
| [`security_guard`](https://github.com/hallettmiket/murmurent/blob/main/agents/security_guard.md) | [The security guard](https://mikehallett.science/assets/videos/murmurent_agent_security_guard.html) | 1:43 |
| [`clerk`](https://github.com/hallettmiket/murmurent/blob/main/agents/clerk.md) | [The clerk](https://mikehallett.science/assets/videos/murmurent_agent_clerk.html) | 2:31 |
| [`docent`](https://github.com/hallettmiket/murmurent/blob/main/agents/docent.md) | [The docent](https://mikehallett.science/assets/videos/murmurent_agent_docent.html) | 2:00 |

**News**, newest first (releases and new capabilities; the full record is the
[changelog](https://github.com/hallettmiket/murmurent/blob/main/CHANGELOG.md)):

- **2026-11-07**: One short movie per agent. Sixteen two-minute movies, one per commons agent, each with a real run, at the videos page. [More](https://mikehallett.science/assets/videos/).
- **2026-11-07**: Paper packages, thesis packages and the docent. A paper or a thesis becomes a package an examiner can question in Claude Code; the docent answers with locations and logs every question. Six-minute video. [More](https://mikehallett.science/assets/videos/murmurent_thesis_package.html).
- **2026-11-02**: Release 2026.11.0, repositories and projects settled. A repository may belong to several projects, membership grants access on every one, readiness travels with the clone, and a collaborator from another lab can finish joining from the message they receive. [More](https://github.com/hallettmiket/murmurent/blob/main/CHANGELOG.md).
- **2026-10-30**: Release 2026.10.8, one route for every Slack note. Every release note, job notice and status update follows the same route to a project's channel, and the lab's channel otherwise. [More](https://github.com/hallettmiket/murmurent/blob/main/CHANGELOG.md).
- **2026-10-19**: Release 2026.10.5, citations checked and the vault syncs itself. murmurent cite check looks up every DOI, PMID and arXiv identifier; the personal vault follows you between machines; spoken verdicts on macOS. [More](https://github.com/hallettmiket/murmurent/blob/main/CHANGELOG.md).
- **2026-10-14**: The getting-started video. Seven minutes from a fresh machine to a working lab member. [More](https://mikehallett.science/assets/videos/murmurent_getting_started.html).

<!-- /videos-and-news -->

## Help

Ask Claude Code first. If that does not solve it, see
[installation special cases](https://mikehallett.science/murmurent/install_special_cases/)
or [report a problem](https://github.com/hallettmiket/murmurent_dev/issues).

---

Mike Hallett, michael.hallett@uwo.ca. Licensed under [Apache-2.0](LICENSE).
