Get started
Install Gromit and join your team's grouping. Two people take part: you, the teammate, and the steward, who looks after the grouping. It takes about 15 seconds from the steward's approval to you being connected. Apple Silicon Macs only for now.
- Your side runs three commands:
brew install,gromit local install --invite … --person <name> --writeandgromit local status. - Never run
add-memberorgromit approveon the teammate's side. They send one line to the steward and wait. gromit local statusexits 1 while waiting for approval. That is expected, not an error.- Only the public key leaves the machine. Never read, print or send anything under
~/.local/share/gromit/keys/. - Once status says
connected, Claude Code needs a restart to load thegromitMCP server. You then act as<person>/claude. rejected:no_mandateafter joining: rungromit agent setup claudeand show your person what it says.
Gromit lets your tools and your Claude Code share work items, merge requests and decisions with the rest of the team. You run a small background process on your Mac (the sidecar). It signs what you do and swaps it with everyone else's through the team relay. Together they're the bus. Who's in the team, and what they may do, lives in a git repo of rules (the grouping). Any change to it, adding you included, needs a member's signed approval. Concepts explains each part.
The examples below use sam as the teammate and ines as the steward.
What you need
- An Apple Silicon Mac with Homebrew, or a shell for the install script.
- Claude Code, if you want your agent on the bus. It's optional.
- An invite from your steward: one
tally:…line.
The six steps
Each of you runs a few commands, in this order:
| # | Teammate (you) | Steward |
|---|---|---|
| 1 | Send you the invite: a tally:… string |
|
| 2 | Install Gromit | |
| 3 | Install from the invite, then send the steward the add-member line it prints |
|
| 4 | Wait. Status says you're waiting for the steward | |
| 5 | Add you with add-member, then approve it |
|
| 6 | Check status: connected, mandate acked. Restart Claude Code |
1. Steward: send the invite
gromit grouping invite
It prints one line, tally:eyJ…, holding the rules repo, the relay address
and the grouping's name. It holds no secrets. Send it to the teammate in
Slack or email.
2. Teammate: install Gromit
With Homebrew:
brew install TomPope94/gromit/gromit
gromit --version # gromit 0.2.0 or later
Or with the install script, which puts gromit in ~/.cargo/bin:
curl -fsSL https://github.com/TomPope94/gromit-releases/releases/latest/download/gromit-installer.sh | sh
Don't download the tarball in your browser: the binaries aren't signed, and macOS Gatekeeper blocks unsigned binaries fetched that way.
3. Teammate: install from the invite
Use the invite your steward sent and your own first name. --write makes the
changes; without it, install only prints what it would do:
gromit local install --invite "tally:eyJ…" --person sam --write
This makes a device key for this Mac, starts the sidecar as a launchd agent that runs at every login, and adds Gromit to Claude Code. The end of its output is the line to send the steward:
Your public key. Send it to the steward, who adds you with:
gromit grouping add-member sam --key "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDMAsper8NGahtK5AsSmj99sZyxR0znrwMwxj24rKjp1 sam"
Copy the whole gromit grouping add-member … line and send it to the
steward. It holds only your public key, so it's safe to paste anywhere.
The private key stays in ~/.local/share/gromit/keys/. Never send that one.
4. Teammate: wait
gromit local status
Until the steward approves you, it says so and exits 1:
sidecar waiting for the steward to approve you: your key isn't in the active rules yet. Send them `gromit grouping add-member sam --key "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDMAsper8NGahtK5AsSmj99sZyxR0znrwMwxj24rKjp1 sam"` if you haven't. [agent running, pid 63634]
mandate sam/claude: published once the steward approves you
adapter not installed (add --tiphys <url> to install it)
That's normal, exit code included. You don't need to do anything else: the sidecar checks every 15 seconds and connects by itself once you're approved.
5. Steward: add-member, then approve
Run the line the teammate sent:
gromit grouping add-member sam --key "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDMAsper8NGahtK5AsSmj99sZyxR0znrwMwxj24rKjp1 sam"
pushed a0bec9a8a7 to main: Add sam
grouping.yaml#members: needs at least one member's approval
The steward (ines) and the other members approve it with:
gromit approve a0bec9a8a7aeff7b007eed27ad30c896e4b6cc69
Then run the gromit approve line it printed. If the rules ask for more
approvals than the steward's, the output names them, and each of those
members runs the same line:
gromit approve a0bec9a8a7aeff7b007eed27ad30c896e4b6cc69
pushed approve/a0bec9a8a7aeff7b007eed27ad30c896e4b6cc69/ines
--gitlab <username> and --asana <user gid> on add-member link the
teammate to their GitLab and Asana accounts, so the bridges put their merge
requests and tasks on the bus. They're optional, and they can be added later
with --existing.
6. Teammate: check status
gromit local status
Once you're approved:
sidecar connected to wss://relay.example.com/ as sam, last heard 2026-11-13T18:15:04.573Z, 0 queued, 0 refused [agent running, pid 63634]
mandate sam/claude granted (9cdec1b74e), acked by the relay at 2026-11-13T18:15:04.571Z
adapter not installed (add --tiphys <url> to install it)
connected means you're in. The relay is whatever your invite names. You can
now read everything the team has published, including what was written
before you joined. The mandate is what your Claude Code is allowed to do
for you, and acked by the relay means the team has it. Now restart Claude
Code.
What Claude Code gets
Install added a user-wide MCP server called gromit. In that server Claude
acts as sam/claude, not as you. Restart Claude Code to pick it up. The
server has four tools:
tally_status: whether the sidecar is connected.tally_state: work items, change sets and decisions as the team sees them now.tally_inbox: what's waiting on you.tally_do: act on something.
The default mandate lets Claude do routine things on work items, change sets
and decisions. Protected acts, such as approving a change set, stay yours:
Claude gets requires_human if it tries. If you already had a gromit entry
in Claude Code, install leaves it alone; the claude mcp add command it
prints lets you add the entry by hand.
Installed already, or Claude gets rejected:no_mandate? Run
gromit agent setup claude. It says whether the MCP entry and the default
mandate are in place. With --write it adds the entry and, once you say yes
(or pass --yes), grants the mandate. Run again, it reports both in place and
changes nothing.
Your other tools
- GitLab and Asana need nothing on your Mac. The team's bridges mirror them, once the steward has linked your accounts (step 5).
- Argonauts. Add
--tiphys http://127.0.0.1:7780when you run the install. The adapter puts your Tiphys batches on the bus as work items, and brings back as seeds the tickets you hold and the changes teammates request on your MRs. The status lineadapter not installedthen becomes the adapter's last pass. - Anything else joins through an adapter. See Writing an adapter.
Upgrading
brew upgrade gromit
The sidecar restarts onto the new version by itself.
When it doesn't work
| You see | Do this |
|---|---|
waiting a minute after the steward approved |
Check the steward ran the gromit approve line, then read the last lines of ~/.local/share/gromit/logs/sidecar.log. Once you're approved it says rules now at … and granted sam/claude the default mandate. |
macOS blocks gromit |
You downloaded the tarball in a browser. Install with Homebrew or the install script instead. |
Claude gets rejected:no_mandate |
Run gromit agent setup claude --write. |
Claude gets requires_human |
That act is yours to do, not your agent's. Do it yourself. |
No gromit tools in Claude Code |
Restart Claude Code. Still missing? gromit agent setup claude --write. |
Still stuck? Send your steward the output of gromit local status and the
last lines of ~/.local/share/gromit/logs/sidecar.log.
How to leave
On your Mac:
gromit local uninstall --write
unload com.gromit.sidecar and remove ~/Library/LaunchAgents/com.gromit.sidecar.plist
keep ~/.local/share/gromit; delete it by hand to start over
This stops the sidecar. Your data and keys stay in ~/.local/share/gromit.
Then ask the steward to take you out of the grouping. That's an edit to
grouping.yaml that the other members approve, and once the relay picks it
up your key can't connect any more.
Next
- Concepts: what each part is and how they connect.
- Writing an adapter: connect a tool of your own.
- For agents: what to give your coding agent.
The commands and outputs on this page come from a rehearsal on 13 Nov 2026. Your keys, commit ids, pids and times will differ.