# 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.

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](concepts.md) 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

```sh
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:

```sh
brew install TomPope94/gromit/gromit
gromit --version          # gromit 0.2.0 or later
```

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

```sh
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:

```sh
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

```sh
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:

```sh
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:

```sh
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

```sh
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:7780` when 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 line `adapter not installed` then becomes the
  adapter's last pass.
- **Anything else** joins through an adapter. See
  [Writing an adapter](writing-an-adapter.md).

## Upgrading

```sh
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:

```sh
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](concepts.md): what each part is and how they connect.
- [Writing an adapter](writing-an-adapter.md): connect a tool of your own.
- [For agents](for-agents.md): 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.
