From zero to two leads talking

telemai connects each engineer's Claude Code agent team into one project. Every engineer runs a lead agent in Claude Code; the leads share one small server, so a change that affects another engineer's work reaches their agents within seconds, without anyone relaying it. This page takes a team from nothing to a working setup.

What you need

• Node 22 or newer, on every machine.
• Claude Code 2.1.300 or newer, on every machine, with agent teams available.
• On the host machine only: Docker (Desktop or Engine) and, for teammates on other machines, cloudflared (winget install Cloudflare.cloudflared on Windows, brew install cloudflared on macOS).
• A git repository with a main branch. TypeScript projects get the dependency graph; other languages get everything else.

Two roles

One engineer is the host: their machine runs the server for the project. Everyone, host included, is an engineer with their own lead agent. The host steps happen once per project; the engineer steps happen once per person.

Host: once per project

1. Start the server

   $ cd <your repo>
   $ npx telemai host --tunnel

   This starts Postgres and the telemai server in Docker, opens a Cloudflare quick tunnel so teammates' Claude Code hooks can reach it, and prints the public address. Keep this terminal open. Closing it stops the tunnel; the containers keep running, and mai host stop stops them.

   The quick tunnel's address changes on every start, so teammates need a fresh invite after a restart. For a stable address, use your own Cloudflare tunnel: mai host --cloudflare-token <token> --public-url https://mai.example.com. To try telemai alone on one machine first, run mai host without a tunnel flag; the server is then reachable only from that machine.

2. Invite each engineer, yourself included

   $ npx telemai invite you@example.com
   $ npx telemai invite teammate@example.com

   Each invite is a single-use mai://… string that is good for 24 hours. Send it to that person however you like. A used or expired invite is refused; mint a new one.

Every engineer: once per person

1. Install the CLI

   $ npm install -g telemai     # or keep using npx

2. Redeem your invite

   $ cd <your clone of the repo>
   $ mai join mai://…#… --team <your-team-name>

   The team name groups engineers whose agents work as one unit; it is set on the first join and kept on re-joins. Your tokens land in ~/.mai and never leave your machine.

3. Declare your area

   $ mai own packages/billing docs/billing

   These are the paths your team is responsible for. The longest matching prefix wins, a path another team already owns is refused, and every other lead is told. Change your mind later with mai disown.

4. Start your lead

   $ mai start

   This launches Claude Code at the repo root with the telemai plugin, your lead agent and the channel that delivers other leads' messages. Claude Code asks at every start whether to load a development channel; accept it. telemai's channel isn't on Anthropic's allowlist yet, which is the only reason for the prompt.

   Talk to your lead as you would to Claude Code. It delegates to its worker teammates, and it tells you when another team's change touches your area or when a decision is needed from you.

Check that it works

$ mai status

You should see Host: up, the server's build, your team, your areas and the claims that touch you. Then have a teammate on another team edit a file inside your area: your lead gets a message naming the file within a few seconds, and mai log --since 10m shows the edit and the claim.

Day to day

mai status          is the host up, what build, your areas, the claims that touch you
mai log --since 2h  what happened across every team
mai claims          who is working on which files right now
mai escalations     what your lead is waiting on you to decide (answer in the lead chat)
mai disown <paths>  give an area up again
mai host status     (host machine) the server's health, build and tunnel
mai revoke <email>  (host machine) cut an engineer off; a new invite lets them back in

Every flag is in the command reference.

When the host is down

Nothing breaks on your side. Hooks fail open, your lead keeps working, and the channel replays what you missed once the host is back. mai status says plainly when that is the case and exits with status 1, so a script can tell too.