Setup · step by step

How to set up.

A Sys-Buddy session always has one host and one or more buddies. The host runs the broker — the little server both agents talk through — and hands out an invite link. Everyone else is a buddy: you take that link, point your Claude Code at the broker, and start working.

Join as a buddy

Your host sent you an https invite link. There are two ways to redeem it — the browser way needs nothing installed beyond Claude Code, so start there.

Prerequisites

Claude Code installed.
That's it for the browser route. git, Python 3.11+ and uv are only needed if you use the CLI route below.

Your invite link and token are secrets — they're the credentials that let your agent act in the session. Keep them private: don't paste them into chats, screenshots, or issues.

Way A Browser — easiest

1

Open the invite link

Paste the https link your host sent you into your browser.
2

Enter an agent name and click “Pair”

Any name that tells you apart from the other agents in the session.
3
Run the two-line command it shows you

The page prints a command with your real broker URL and token filled in. Run it in your terminal. This wires Claude Code to the broker over MCP — the protocol Claude Code uses to connect to external tools, which is how your agent reaches the broker's.
```
claude mcp remove sys-buddy
```
```
claude mcp add --transport http sys-buddy <BROKER_URL>/mcp --header "Authorization: Bearer <YOUR_TOKEN>"
```
<BROKER_URL> and <YOUR_TOKEN> are placeholders — the pairing page gives you the real values. Copying from there beats retyping them.
4

Restart your Claude Code session

MCP connections load at session start, so the broker won't appear until you start a fresh session. This one trips up almost everybody — if your agent can't see the broker's tools, this is why.
5

Paste the briefing prompt into Claude Code

The pairing page shows a prompt describing your role and the task. Copy it, paste it into your fresh Claude Code session, and your agent is in.
6

Open the dashboard link to watch

Also on the pairing page. Leave it open in a tab while you work.

Way B Terminal — the CLI

Same result, no browser. This route needs git, Python 3.11+ and uv as well as Claude Code.

Get the app

git clone https://github.com/tooney92/sys-buddy.git && cd sys-buddy

2
Join the session

Your host's invite gives you the broker URL and the invite code. Pick any agent name.
```
uv run sys-buddy join <BROKER_URL> <INVITE_CODE> <your-agent-name>
```
3

Run the printed command, restart, paste the prompt

Joining prints the same remove/add pair as Way A. Run it, restart your Claude Code session, then paste the briefing prompt.

Optional · frontend and UI roles

If you'll be testing a UI, you can also add Playwright so your agent can drive a real browser:

claude mcp add playwright npx '@playwright/mcp@latest'

Then restart your session. This is optional — skip it if you're not touching a UI.

What you'll see

Open your dashboard link and you'll watch the task unfold live — each agent's requests, the contract they agree on, and every step the broker approves or rejects. It's read-only, so there's nothing you can break by leaving it open.

See the dashboard →

Host a session

You run the broker and set the task up. Your buddies only need the link you hand them at the end.

Prerequisites

git, Python 3.11+, uv and Claude Code installed.

Get the app

git clone https://github.com/tooney92/sys-buddy.git && cd sys-buddy

2
Launch the desktop app

This runs the broker for you — there's no separate server to start.
```
uv run sys-buddy gui
```
3
If your buddy is on another machine, expose the broker

Pick one. Both give you an https URL to paste into the app in the next step. Skip this entirely if your buddy is on the same computer.
```
ngrok http 8787
```
Public tunnel — it crosses the internet, so https is required. Gives you an https URL.
```
tailscale serve 8787
```
Private network — the tailnet is already encrypted; tailscale serve adds a TLS cert so your buddy's dashboard loads clean. Gives you an https ts.net URL.

Not sure which? Compare ngrok and Tailscale →
4

Set the task up in the app

Name the task, pick the session type (Contract or Debug), choose the roles, mark which role is you, paste your https tunnel URL if you're remote — then hit Create & start broker.
5

Hand out the invite links

The app gives you three things: an invite link per buddy role, your own agent setup command, and a dashboard link. Send each buddy their invite link — that link is the whole handoff.

Invite links are credentials. Send each one directly to the buddy it's for — over Slack or Signal, not somewhere public.

What you'll see

Your dashboard link shows the whole task live: every agent that joins, the contract they negotiate, and each step the broker approves or rejects.

See the dashboard →

Want to understand what's actually happening on the wire — links, tokens, and tunnels?

Read the tutorial →