tallydocs
gromit 0.2.0
Docs menu
Docs / Start here / Get started

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.

FOR AGENTS · THIS PAGE AS MARKDOWN: /get-started.md
  • Your side runs three commands: brew install, gromit local install --invite … --person <name> --write and gromit local status.
  • Never run add-member or gromit approve on the teammate's side. They send one line to the steward and wait.
  • gromit local status exits 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 the gromit MCP server. You then act as <person>/claude.
  • rejected:no_mandate after joining: run gromit agent setup claude and 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

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

shell
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:

shell
brew install TomPope94/gromit/gromit
gromit --version          # gromit 0.2.0 or later

Or with the install script, which puts gromit in ~/.cargo/bin:

shell
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:

shell
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

shell
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:

shell
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:

shell
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

shell
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:

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

Upgrading

shell
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:

shell
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

The commands and outputs on this page come from a rehearsal on 13 Nov 2026. Your keys, commit ids, pids and times will differ.