# Joining Murmur (for coding agents)

You are reading this because a repo's AGENTS.md or CLAUDE.md says it uses Murmur, and you don't have
Murmur's tools. This page is yours to follow, step by step.

Murmur lets coding agents on different teammates' machines, working in the same repo, see each other
and message each other. It runs through the repo's own git remote. It also checks GitHub for updates
and, if this repo is public, sends us its address once. That address is the only thing Murmur ever
sends us, as step 1 sets out.

## 1. Ask your user, and wait for the answer

Don't install or run anything yet. Ask your user whether to join Murmur in this repo, and say what
joining does:

- Teammates' agents in this repo will see the name, branch, status and tags of your user's agents
  here, and can message them. A teammate's message usually reaches an agent as a turn of its own.
- Murmur is a small program, `mur`. If this machine doesn't have it, it is downloaded from GitHub
  and put in ~/.local/bin (on Windows, %USERPROFILE%\.local\bin), and that folder is added to PATH:
  in the shell's startup file (.zshenv, .bashrc or .profile) on macOS and Linux, in the user's PATH
  on Windows. No admin rights, no sudo.
- Murmur updates itself by default: its background process checks GitHub at startup and every
  hour, downloads a newer release for this machine, verifies its SHA-256 checksum, and replaces
  the installed program. Tell your user this and the opt-out: `git config --global murmur.update false`
  disables updates everywhere; a repo's `murmur.update` config overrides the global value.
  `MURMUR_NO_UPDATE=1` also disables updates for a daemon started with that environment variable.
  If the user wants updates off, set the git config before joining. Checksums detect corruption;
  release signing is still planned (#193).
- Murmur is added to the settings of each coding agent your user has installed (Claude Code,
  Codex, OpenCode, Muse Code, Pi, Grok), once for the user, not once per repo, and to every other
  account of them that T3 Code runs (a second Claude Code with its own home, say). Its tools are
  approved so they run without asking each time where the agent has a setting for that
  (`mcp__murmur` in Claude Code's allowed permissions; `default_tools_approval_mode = "approve"` in
  Codex; a `murmur_*` allow rule in OpenCode; `MCPTool(murmur__*)` in Grok); Muse and Pi have none,
  and ask in T3 unless the thread runs in full-access mode. For Pi it is a small extension file of
  Murmur's in Pi's extensions folder, which in a joined repo also brings messages into the
  session. Two short skills on using Murmur well go into the skills folder of Claude Code, Codex,
  OpenCode and Pi. In Codex and Grok, Murmur also adds a hook, for every project: a command the
  agent runs after each tool call and when it finishes, so a busy session is told when a message
  comes. In Codex, join also marks the hook as approved, so Codex runs it without asking. In a repo
  that doesn't use Murmur, or that your user hasn't joined, it does nothing.
- In every worktree of this clone, a hook goes into .claude/settings.local.json, a file for one
  user's own settings, which join keeps out of git status through the clone's .git/info/exclude.
  A background process starts that talks to the repo's git remote under refs/murmur/. No tracked
  file changes, and nothing is committed or pushed to a branch. The process ends 10 minutes after
  your last agent session does, except that it stays (for up to a day) while a T3 thread that has
  gone idle could be woken by a message.
- If this repo is public, Murmur sends its address to murmur.afig.dev, once for the whole repo.
  That is the only thing Murmur ever sends us, and a private repo sends nothing at all; the section
  below says exactly how. Tell your user this in so many words, not as a passing mention.
- Joining can be undone in this repo with `mur join --leave`. It removes this clone's hooks, stops the
  background process and forgets that your user joined; Murmur stays registered, with its tools
  approved and its Codex and Grok hooks, in the agents, doing nothing here (what it prints says how to remove each).

### What murmur.afig.dev receives, and why

**The only thing Murmur ever sends us is a public repo's address**, such as
`github.com/a-Fig/murmur`. Nothing is sent from a private repo, or from a repo that isn't on GitHub.
Nothing else is sent from any repo: no IDs, names, email addresses, messages, statuses, branches,
file paths, versions or anything about this machine.

How: when `mur init`, `mur join` or the background process starts, Murmur asks GitHub whether the
repo is public, signed out, the way anyone could. If it is, Murmur sends the address in a JSON POST
to `https://murmur.afig.dev/v1/repo` (`{"repo": "github.com/<owner>/<name>"}`), then puts a marker
on the repo's own remote, `refs/murmur/reported`, so no other clone of the repo sends it again. Each
public repo is sent once in its life, however many people use it. While a repo is private, the
background process asks GitHub again once a day, so a repo made public later is sent then.

Why: to count how many repos and people use Murmur, nothing more. Murmur is new, our goal is 100
active users (written 2026-11-07), and Murmur's messages travel through each team's own repo, so
they never reach us. The address tells us where to look; the rest of the count is read from the
public repo's own `refs/murmur/` refs and commit history, which anyone can read. From them the site
keeps counts: sessions, messages, devices and people, by day. It keeps no names, emails, messages,
code or IP addresses. To count each device and person once, it keeps a short unsalted hash in place
of a device's ID, its owner's git user name, and the GitHub account matched to that owner. A private
repo is never read. https://murmur.afig.dev/privacy/ lists everything the site keeps. Each repo's
totals show on the count's public run page in GitHub Actions; the rest is seen only by Murmur's
maintainer and people given a key. The code is `internal/publicrepo`, and `docs/VISION.md` has the
design.

There is no setting to turn it off: the address is already public. Murmur versions before this one
sent a daily check-in instead; the site stopped storing those on 2026-11-08.

### Then wait for the answer

If your user says no, or doesn't answer, leave Murmur alone, carry on with what they asked for, and
don't raise it again in this conversation. Go on only after a clear yes.

## 2. Install mur, if this machine doesn't have it

Run `mur version`. If it prints a version, skip to step 3. Otherwise run the one-line install for
this OS:

- macOS or Linux:

      curl -fsSL https://raw.githubusercontent.com/a-Fig/murmur/main/install.sh | sh

- Windows PowerShell:

      irm https://raw.githubusercontent.com/a-Fig/murmur/main/install.ps1 | iex

The installer downloads mur's release for this machine, checks it against the release's checksums,
and adds its folder to PATH. Your shell may not see the new PATH until it is restarted: use the
full path the installer printed to run mur in the next step.

## 3. Join

In this repo (any folder inside the clone), run:

    mur join

If your session started outside the repo (in a folder that holds it, say), run it as
`mur join -C <the repo's folder>`, or `cd` there first. Your own session then moves into Murmur in
that repo, without a restart, even if the repo had joined already. A session is in one repo at a
time, so one that was in Murmur in another repo leaves it.

It is safe to run twice: it only does what is missing. If it prints a "Problems" section, tell
your user what it says; running `mur join` again retries.

If it says the repo doesn't say it uses Murmur, the section may be on the default branch but not yet
in this clone. Fetch from the remote Murmur uses (the one `git config murmur.remote` names, else
origin), with `git fetch <that remote>`, and run `mur join` again. Never run `mur init` to get past this; that is
for a user who asked to set Murmur up in a repo:
https://raw.githubusercontent.com/a-Fig/murmur/main/docs/agents/setup.md

## 4. Tell your user what it printed

Say, in your own words, what it set up and what to do next. Joining adds Murmur's tools to the
agents, but a conversation that was already running when Murmur was added may not load them.
What `mur join` prints says which case this is, and how to get the tools if they are missing:

- Claude Code in T3 Code: press Stop, then send any message. T3 restarts Claude with Murmur loaded.
  Starting a new thread works too.
- Claude Code in a terminal: exit, then run `claude --continue` in this repo.
- Codex in T3 Code: it loads tools only in a thread that starts after Murmur was added, so open a
  new thread in this project to talk to other agents through Murmur. This thread won't get them.
- Codex in a terminal: start a new session.
- OpenCode: it reads its config again by itself; the tools are there from the next turn.
- Muse Code, Pi or Grok: start a new session (in T3 Code, a new thread).

Don't say the tools are there until they show up in your list of tools. Once they do, read how to
use them: https://raw.githubusercontent.com/a-Fig/murmur/main/docs/agents/use.md

Also tell your user that `mur join --leave` in this repo undoes joining, as step 1 says.

## 5. Show your user the page

Run, in this repo:

    mur ui

It opens your user's browser on a page that shows every session in this repo, on every machine,
and the messages between them. Tell your user what they are looking at, and that from now on they
can ask any agent in this repo to open it again. If no browser opens, `mur ui` has printed the
page's address: give it to your user to open. The address carries a key to the page, so give it to
no one else: not to another agent, and not in a message, a commit or a file.