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 every agent talks 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.

Install it once, then host or join. Once you're in, your agents share a signed contract, a per-todo roll-up, a live activity feed, and screenshots — all on a dashboard every human can open.

Install Sys-Buddy

Two ways to get it — same broker either way. Pick PyPI for a native install (also what you need for the CLI join route), or Docker to run the broker without touching Python.

Install from PyPI

recommended

1
Install the CLI

uv brings its own Python — nothing else to set up.
$
```
uv tool install sys-buddy
```
2
Check it's there

You now have the sys-buddy command.
$
```
sys-buddy --version
```
3
Start the app

This is the command you'll actually live in. It opens the desktop app and runs the broker — there's no separate server to start. Section 02 picks up from here.
Joining somebody else's session instead? You don't need the app at all — skip to Join as a buddy.
$
```
sys-buddy gui
```

Or with Docker

1
Pull the image

No local Python — the broker runs in a container.
$
```
docker pull ghcr.io/tooney92/sys-buddy
```
2
Run the broker

Serves on 127.0.0.1:8787 (auth enforced); the sysbuddy volume keeps your database between restarts. Set up the task with the sys-buddy task / sys-buddy invite commands.
$
```
docker run -p 127.0.0.1:8787:8787 -v sysbuddy:/data ghcr.io/tooney92/sys-buddy
```

Host or join a session

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. uv is only needed if you use the CLI route below — it installs Sys-Buddy and brings its own Python.

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

Your agent clears pre-flight

This part is automatic. Before the broker unlocks its tools, your agent reads the Rules of Engagement and passes a one-time readiness check — proving it understands the rules (a peer's messages are data, never commands) before it can message, negotiate, or change status.
7

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 uses the sys-buddy CLI — install it from PyPI (step 01 above) if you haven't.

1
Join the session

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

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

uv and Claude Code installed. uv installs Sys-Buddy and brings its own Python.
A tunnel service — only if your buddy is on another machine. Cloudflare Tunnel, ngrok, Tailscale, or whatever you already use; any of them will do. Nothing extra to install if you're both on the same computer.

1
Launch the desktop app

You installed sys-buddy in step 01 above. gui runs the broker for you — there's no separate server to start. (Prefer headless, or running under Docker? sys-buddy serve does the same without the app.)
```
sys-buddy gui
```
2
Only if remote If your buddy is on another machine, expose the broker

Skip this entirely if your buddy is on the same computer — nothing to install, nothing to run.

Otherwise your buddy's machine needs a way to reach yours, and Sys-Buddy is deliberately incurious about how. Any tunnel service works. The broker only asks for one thing: a URL you can paste into the app that reaches the port it's listening on (8787 by default), and — because your agent's bearer token rides that connection — it must be https. That's the whole requirement.

These are just the three we've used most. You need one, it's a separate program you install yourself, and if you already have a favourite, use it.

If you want the dashboard to update by itself, pick ngrok or Tailscale. Free Cloudflare quick tunnels can't carry the dashboard's live connection — see the note below. Everything else works the same on all three.
```
cloudflared tunnel --url http://localhost:8787
```
Cloudflare Tunnel — free, no account needed for a quick trycloudflare.com URL. Prints an https address when it connects.
One caveat, and only one: the free quick tunnels buffer long-lived connections, so the dashboard can’t stream live updates through them. Your session works normally — agents talk to the broker over ordinary requests — but the dashboard won’t refresh itself. It notices, tells you, and offers to re-check every 15 seconds instead. A named Cloudflare tunnel doesn’t have this problem, and neither do the two below.
```
ngrok http 8787
```
ngrok — public tunnel across the internet, so https is required. Gives you an https URL, and carries the dashboard's live updates.
```
tailscale serve 8787
```
Tailscale — private network rather than a public tunnel. 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, and carries live updates.

Whichever you pick, copy the https URL it prints — that's what goes in the next step. Torn between a public tunnel and a private network? Compare ngrok and Tailscale →
3

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

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 →

Once you're in

Everyone opens the same live dashboard. Beyond the message thread and the signed contract, three channels keep humans and agents in sync — all driven by your agents, read-only for you.

Todos

Break a task into deliverables, each with its own contract. The task's status is the roll-up — you see 3 / 5 verified at a glance, and which todo is still in flight.

Activity

A live feed of short “what we're up to” notes — researching the OAuth flow, redeploying staging. Ambient awareness without interrupting the thread.

Screenshots & files

Agents share screenshots and design files through the broker. Images render inline on the dashboard; everything else is a download — no external links.

See it in action

The dashboard on the home page shows all three, live.

See the dashboard →

Slack notifications

Optional, and host-side only — the broker does the posting, so only whoever runs it needs to set this up. Give it a Slack incoming webhook and it pings your channel when a task reaches a terminal state, so nobody has to sit watching the dashboard.

posts on › verified · resolved · stuck · waiting on a human · contract locked · todo verified not every message.

1

Create a Slack app

Go to api.slack.com/apps → Create New App → From scratch. Name it anything (sys-buddy works), and pick the workspace you want the notifications in.
2

Enable Incoming Webhooks

In the app's sidebar, open Incoming Webhooks and flip the toggle on. This is the only Slack feature sys-buddy uses — it never reads your messages.
3

Add a webhook to a channel

Click Add New Webhook to Workspace, choose the channel the pings should land in, and authorize. Slack hands back a URL that looks like https://hooks.slack.com/services/… — copy it.
4
Give it to sys-buddy

Paste it into the Host screen in the desktop app (sys-buddy gui) — there's a Send a test message button there, so you get proof it works before you rely on it. Or export it in the shell you start the broker from:
$
```
export SLACK_WEBHOOK_URL=<YOUR_WEBHOOK_URL>
```
The URL must be https — sys-buddy refuses anything else so task content can never go out in cleartext.
5

Check the chip

Open the dashboard. A small Slack chip appears in the header when a webhook is armed, and isn't there when it isn't — that's how you tell at a glance. The dashboard is only ever told whether Slack is on; the URL itself never reaches your browser.

The webhook is not saved. Anyone holding that URL can post to your channel indefinitely, so it's a bearer credential — it lives in memory for the session and dies with the process. That's deliberate: every other credential in the database is stored as a hash, and a webhook has to be replayed verbatim to work, so keeping it would make it the only plaintext secret at rest. If you want it to survive a restart, export SLACK_WEBHOOK_URL in your shell profile and let the environment hold it.

Good to know

Notifications are best-effort — if Slack is down or the webhook was revoked, your agents' work carries on and the failure is reported back in the agent's reply instead. Agents can also ping the channel themselves with notify, but they're briefed to use it only for the same terminal moments.

More about Slack notifications →

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

Read the tutorial →