brainmod docs
brainmod is a Claude Code mod for teams: a band above your prompt with your teammates' live Claudes, a hold before two Claudes edit the same file, short messages to a teammate's Claude, and a personal brain of notes synced across your machines. This page covers everything you can set and run. It is free during the beta.
Install
You need Claude Code 2.1.287 or later (the release that added mods). At the Claude Code prompt:
/plugin install brainmod@<marketplace>Not public yet<marketplace> is a placeholder: the marketplace that will carry brainmod is not published yet.
- Where it draws: the terminal and the Claude Code Desktop app. The VS Code panel does not draw the band; the hooks still run there, so the hold, notes and messages work.
- Managed organisations: if your org sets
allowManagedModsOnly, an admin has to add brainmod to the managed mods before it loads. - Without an account it works on one machine right away. See local mode.
Commands
| Command | What it does |
|---|---|
/brain | Opens the brain pane: your notes for this repo, recent team notes, who is online. |
/brain note <text> | Saves a note to your personal brain. Options: --kind gotcha|fix|decision (default note), --area <path> for the part of the repo it is about. |
/brain list | Lists your notes for this repo, newest first, with their ids. |
/brain promote <id> [team] | Shares a copy of one of your notes with a team. Never automatic. |
/brain forget <id> | Deletes a note of yours on every machine. |
/brain login | Signs this machine in with a device code. See how sign-in works. |
/brain logout | Revokes this machine's token on the server, deletes it locally and returns to local mode. |
/brain status | Shows the server, who you are signed in as, your teams, and whether this repo shares file paths. |
/brain share-files on|off | Turns file-path sharing on or off for the current repo. See what a repo shares. |
/team | Lists your teams and the Claudes live in them. |
/team create <name> | Creates a team with you as its owner. |
/team invite [team] | Prints an invite link: 7 days, 25 uses. Any member can invite. |
/team join <code|url> | Joins a team from an invite link or its code. |
/team leave <team> | Leaves a team. The last owner can't leave while others are in it. |
/team msg <@login|all|#team> <text> | Sends a short message to a teammate's Claude, to everyone in your teams, or to one team. |
Claude can also save a note through brainmod's tool when it finds something worth keeping. Each note it posts is shown to you, goes to your personal brain, and is scanned for secrets first like every other note.
Options
Set these in brainmod's plugin options in Claude Code. Each has a default that works without setting anything.
| Option | Values | Default |
|---|---|---|
server | The brainmod server's base URL. The BRAINMOD_SERVER environment variable overrides it. | https://brainmod.apps.clod.farm |
holdMode | Interactive sessions. ask: hold the edit and ask. warn: let it through and show a warning. off: no check. | ask |
holdModeHeadless | Headless runs (claude -p, no one to ask). block: refuse the edit with a "file busy" result Claude can read. warn: let it through with a warning. off. | block |
holdWindowMinutes | How recent a teammate's edit must be to hold yours. | 10 |
sharedFiles | Repos that share file paths, as owner/name or owner/* patterns. /brain share-files on|off edits this list for the current repo. | empty |
band | always: show the band. others: only when someone else is live. off. | always |
notesPerTurn | How many relevant notes Claude gets as context at the start of a turn. 0 turns it off. | 3 |
The credentials file lives at ~/.config/brainmod/credentials.json (mode 0600); the BRAINMOD_CREDENTIALS environment variable points elsewhere.
The collision hold
Before Claude edits or writes a file, brainmod compares the file's hash with the hashes teammates' sessions reported in the same repository. If another Claude touched it within holdWindowMinutes, the edit waits and you choose:
- Wait: Claude does not edit the file now; it is told the file is busy.
- Go anyway: the edit goes through. Your teammate's band shows your Claude on the same repo.
- Message them: write a short message to that teammate's Claude session, then decide.
Two clones of the same remote match: the repository key is a hash of the normalised origin URL, so git@github.com:acme/api.git and https://github.com/acme/api are the same repo. A repo without a remote never matches anyone else's.
What a repo shares
Signed in, each open session sends a heartbeat every 15 seconds with: a random session id, your machine name, the repo name and branch, the status (idle, thinking, the tool's name, or asking) and the hashes of up to 30 files touched in the last 30 minutes.
For repos in sharedFiles, it also sends the repo-relative paths of those files and the file the current tool is working on, so teammates read Edit src/billing/invoice.ts instead of just Edit. Everything else stays on your machine: prompts, transcripts, Claude's replies, file contents and tool inputs are never sent. The full list is on the privacy page.
How sign-in works
/brain loginasks the server for a device code and prints it with a link to brainmod's device page.- You open the link, sign in with GitHub (scope
read:user: your id, login, name and avatar), check that the code matches and approve. - The terminal, polling every 5 seconds, receives a token and saves it in the credentials file. Codes last 15 minutes and work once.
Tokens are stored hashed on the server and expire after 90 days unused. Every machine and browser signed in is listed on your account page, where you can revoke it. /brain logout revokes the current machine's token.
Teams and invites
You see the live sessions and team notes of every team you are in, and your own other sessions. Create a team with /team create or on your account page; invite with /team invite or on the team's page. Owners can remove members and delete the team, which deletes its notes, invites and messages. Members can leave at any time.
A message to a teammate's Claude is shown to that person, and their Claude sees it as untrusted context at the next turn they start. It never starts a turn, runs a tool or spends their usage. Each Claude runs on its owner's own seat; brainmod never routes work or usage between people.
Local mode
Signed out, brainmod sends nothing. On your machine it still shows your other Claude sessions in the band, holds an edit when two of your own sessions touch the same file, and keeps your notes. All of it lives in the machine's local mod store. /team explains how to sign in. When you sign in later, your teams' sessions join the band.
Limits
| Note | 500 characters (area 200) |
|---|---|
| Message | 1,000 characters, kept 7 days |
| Team name | 60 characters |
| Rate limits per person | 240 requests/min, 30 notes/h, 60 messages/h, 20 invites/day |
| Live session | heartbeat every 15 s, gone 120 s after the last |
| Price | Free during the beta. |
Questions or a bug: support@jestr.ai. Last updated 5 October 2026.