When something looks wrong

Start with mai status on your machine and mai host status on the host. Between them they answer most of the questions below.

mai status says the host is down

Your side keeps working: hooks fail open, your lead carries on, and the channel replays what you missed when the host is back. On the host, check that the mai host terminal is still open (closing it drops the quick tunnel) and that Docker is running. mai host status shows the containers' health. If the host restarted with --tunnel, its address has changed: everyone needs a fresh invite and mai join.

A teammate's edits never arrive

Their hooks must reach a public HTTPS address. Claude Code refuses private addresses, which rules out Tailscale, LAN addresses and anything under 10., 172.16. or 192.168.; only a public hostname works. Use --tunnel or a named Cloudflare tunnel. mai status on their machine shows whether the host answers from where they are.

mai host says the image and the CLI differ

The server image is older or newer than your CLI. Pull the matching one: mai host --image ghcr.io/emaiiii/mai-server:<CLI version>. /health and mai host status show the running build, so a stale image is visible.

The graph never builds

mai host status shows what the server follows. The host fetches origin every 30 seconds and reads the graph from origin/main, so a merge is seen once it is pushed, not when it is committed locally. A repo without TypeScript gets no graph: ownership, claims, announcements and migrations still work, but routing by imports doesn't.

Claude Code prompts about a development channel every start

Expected for now. Telemai's channel isn't on Anthropic's allowlist yet, so Claude Code asks before loading it. Accept the prompt.

mai join refuses the invite

Invites are single-use and expire after 24 hours by default. Ask the host for a new one with mai invite <your email>. If you joined before, join again with a fresh invite: your old tokens stop working at once. If ~/.mai still exists, stop mai start and add --force to replace it.

mai own refuses a path

Another team already owns it, or a parent of it. mai status shows the ownership map. Ask that team to mai disown it, or pick the sub-path that is actually yours. mai disown itself needs the exact path as it was declared.

A worker's edit was denied

The file is held by another team's claim; the denial names the holder. A claim expires two hours after the holder's last edit. mai claims shows every active claim. If the hold is stale, the holding team's lead can release it with its release tool.

My lead keeps asking me the same thing

Answer it in the lead chat and make sure the lead logs the decision: the decision is what stops the next change of the same kind from escalating. mai escalations lists what is still open; mai log --type decision_recorded shows what has been settled.

Reporting a bug

During the private beta, bugs and questions go to the Discord you were invited to, or by email to the address in the telemai package metadata. There is no public issue tracker while the repo is private. Include the output of mai status and, from the host, mai host status.