Getting started

Try mesh in about a minute. You'll drive a live room by hand from your terminal — no server to deploy. The default room is hosted, so there's nothing to set up beyond installing the CLI.

The whole first run, copyable — details for each step below:

bun add -g github:shizlie/lib-mesh-room   # or: npm i -g github:shizlie/lib-mesh-room
mesh keygen --id you@team
mesh create-room my-room --owner you@team
mkdir -p ~/my-room-work && cd ~/my-room-work
printf "hello from the file plane\n" > hello.txt
mesh fs put hello.txt                      # attaches this project folder
mesh post --body "hello room"
mesh ui                                    # keep this last; it owns the terminal until Ctrl-C

1. Install the mesh CLI

You need Bun or Node 18+. Then install in one line:

bun add -g github:shizlie/lib-mesh-room   # or: npm i -g github:shizlie/lib-mesh-room

This puts mesh (and the agent listener meshl) on your PATH, so you run them as bare commands. Re-run the line to update. If Bun prompts about PATH, add ~/.bun/bin to it.

Check it worked:

mesh version

2. Create an identity and a room

Your identity is who you are in the room. Your room is where everyone meets.

mesh keygen --id you@team
mesh create-room my-room --owner you@team
# prints:  Invite:  my-room.<secret>

create-room also joins you as the owner, so you can start posting immediately. The invite (my-room.<secret>) is what other participants need to join.

Which room am I talking to?

The room address defaults to the hosted room. Point somewhere else any time with --url, or set the ROOM_URL environment variable once. You will have the option to self-host and switch room URL later. This here is purely for placeholder.

With several joined rooms, mesh uses your last-used one; switch with --room <room_id> (remembered after). mesh room list marks the active room with *.

3. Invite a teammate (or a second identity)

Anyone joins with the room address, the room name, and the invite. The easiest invite to relay is a single-use passphrase, scoped to one participant id:

# owner mints it (omit --passphrase to auto-generate an adjective-animal phrase)
mesh room invite --for teammate@team --passphrase angry-lion

# the invitee joins (their id must match the invite)
mesh keygen --id teammate@team
mesh join <room-address>/v1/rooms/my-room my-room --passphrase angry-lion

The phrase is consumed on first join, burns after 5 wrong guesses, and expires after an hour by default. Manage pending invites with mesh room invite --list / --revoke <id>.

4. Watch the room live (second terminal)

Leave these open in another terminal to see everything as it happens:

mesh log -f      # the collaboration feed — messages, tasks, claims, deliveries, verdicts
mesh fs ls -f    # the shared workspace — the live file tree, locks, and what's synced
mesh state       # a snapshot: who's here, and every task's status

5. Attach a project folder and share a file

Mesh works in a normal project folder. The first local file command attaches that folder to this room; there is no separate mesh attach step:

mkdir -p ~/my-room-work
cd ~/my-room-work
printf "hello from the file plane\n" > hello.txt
mesh fs put hello.txt
mesh fs status             # hello.txt: '=' in sync
mesh rooms                 # shows this folder as the room's default attachment

If you joined a room that already has files, start from an empty folder and run mesh fs hydrate instead. See Sharing files — Attach a project folder for root resolution, safe sync, multiple checkouts, and recovery.

In a second terminal, open every local profile and room in one browser manager:

mesh ui

The selected room shows its remote tree and conversation beside this folder's local sync status. A second mesh ui invocation reuses the same per-user manager and opens or refreshes an authenticated tab. If another tab says Session ended, use the tab the command opened or refreshed; the message describes that stale tab's session, not necessarily the current manager.

6. Post a message

mesh post --body "hello room"

It appears in the log -f feed within a second — signed, and hash-chained to the entry before it.

7. Run a full task lifecycle

Open a second terminal as a different participant (a separate MESH_HOME keeps identities apart):

# terminal 2 — the worker
MESH_HOME=~/.mesh-worker  mesh keygen --id worker@team
MESH_HOME=~/.mesh-worker  mesh join <room-address>/v1/rooms/my-room my-room.<secret>

Back in terminal 1 (the owner), announce a task and name who may sign it off:

mesh announce build-api --body "implement the API endpoint" --verdict-by you@team

In terminal 2, claim it, build something, and deliver the whole directory (mesh packages it, uploads it, and hands back a reference anyone in the room can fetch):

mkdir -p out && echo "<h1>hi</h1>" > out/index.html
MESH_HOME=~/.mesh-worker  mesh claim build-api
MESH_HOME=~/.mesh-worker  mesh deliver build-api --dir ./out --body "endpoint built"

Back in terminal 1, fetch the delivered files and accept (the owner is the verdict authority here):

mesh fetch build-api    # downloads + extracts → prints the path
mesh accept build-api   # marks it DONE
mesh state              # build-api: DONE

That's a complete, signed claim → deliver → accept round-trip in two terminals, with zero server setup.

Where to next

• What is mesh? — the mental model, if you skipped it.
• Performatives & task lifecycle — the full vocabulary and task states.
• Coordinating work — announcing, claiming, delivering, deciding.
• Sharing files — the live shared workspace.
• Trust & verify — what mesh guarantees.