LIP: the Lets Interaction Protocol v1

The contract between Claude, the host and the window. Everything that crosses a boundary is a JSON message envelope; uniques are static web apps that only ever speak LIP, and the host never executes unique code server-side. That is what makes third-party uniques safe to install from git.

Parties

The protocol is designed for mediums that do not exist yet: a unique can be a graph board today, a 3D scene, a voice ring, a haptic strip or an AR overlay tomorrow. Nothing in LIP assumes a screen, only events the human produced and commands the model issues, both carried as typed, versioned JSON.

1. Envelope

{
  "lip": 1,
  "id": "ev_01J9Q0Z8M3K7X4N2",
  "ts": 1760000000000,
  "dir": "up",
  "from": "unique:graph#w1",
  "type": "graph.node.select",
  "data": { "ids": ["n3"] },
  "re": "cm_01J9Q0Z7...",
  "ttl": 30000
}

Batches: a JSON array of envelopes is accepted anywhere a single envelope is.

2. Domains

Reserved domains cannot be redeclared by a unique. A unique MAY emit shell-domain events through the shell SDK, never by forging envelopes.

3. Core messages

3.1 Protocol

3.1b Session: lifecycle and handoff

Handoff. new in 0.4.0 A unique's manifest names which of its types are the export (the human pressed "Send to Claude"), the snapshot (reply to a state query) and the restore command. When an export event reaches the host it is saved as a session (~/.lets/sessions/<unique>/<id>.json), its data gains session: {id, handoff: true, saved: true, summary} as the first key, and the window receives session.close. Claude then answers in the transcript, not in the window. open {resume: "last" | id} later queues the restore command with the saved payload, so the window comes back as it was sent. Snapshot events update the saved session silently. ~/.lets/config.json "handoff": "stay" keeps windows open instead.

3.2 Entity (the companion)

Events (up):

• entity.summon {x,y,context?}: right click / hotkey; context is whatever the unique attaches (e.g. the node under the cursor).
• entity.dismiss {}
• entity.click {x,y,context?}: the human clicked the companion. The shell shows local quick-suggestions instantly; Claude may add smarter ones with entity.suggest.
• entity.pick {id, label}: the human picked a suggestion.
• entity.profile {pace, clickRate, dwell, regions, idleMs, sessionMs, …}: aggregated interaction stats, emitted at most every 60 s and on close. Never raw mouse moves.
• entity.secret {name} 0.4.0: the human discovered one of the companion's secret moves (once per window per move).

Commands (down):

• entity.say {text, mood?, ttl?}: speech bubble.
• entity.mood {mood}: idle|happy|curious|thinking|busy|proud|sleepy|alert.
• entity.suggest {items:[{id,label,hint?}], replace?}: populate the click menu.
• entity.move {x,y} or {to:"cursor"|"center"|"<selector>"}: the shell eases there; never teleports.
• entity.show {} / entity.hide {}
• entity.persona {name, traits}: applied look and behaviour (speed, distance) from the persisted persona.
• entity.react {name, ms?} 0.4.0: play a short expression (dizzy, whoa, startled, gasp, oops, wink, cheer, blush, boop, yawn, peek, nod, shake-no, wave, spin, dance, disco, sparkle). Most of these the shell also plays by itself from how the human moves; see the companion.

3.3 Chat

• up chat.message {text, attachments?:[{path,mime}]}
• down chat.open {} / chat.close {} / chat.say {text, seq?, done?} (stream with the same re) / chat.typing {on}

3.4 Components (anything the model invents at runtime)

• down component.create {id, type, props, slot?:"dock"|"float"|"panel"|"inline", at?:{x,y}}
• down component.update {id, props} / component.remove {id}
• up component.action {id, action, value?}

Built-in component types every shell MUST provide: note, options, slider, toggle, form, image-drop, progress, code. Unknown types fall back to note with the raw props shown, so a future type never breaks an old shell.

3.5 Media

• up media.image {path, w, h, mime, bytes, source:"paste"|"drop"|"file", componentId?}: the shell POSTs the blob to /lip/upload; the host stores it under ~/.lets/uploads/<unique>/ and the event carries the path, so Claude reads the file with its own tools. Base64 never crosses to the model.

3.6 UI

• down ui.toast {text, level?:"info"|"ok"|"warn"|"error", ttl?}
• down ui.theme {name?, vars?}: CSS variable overrides.

4. Transport & security

Security. Loopback only; a per-host random token is required on every request (query t, header, or the window's URL fragment at open); CSP on served pages is default-src 'self'; uploads are size-capped (default 25 MB) and written only under the uploads dir; manifests are schema-validated before a unique is served. The runner (/lip/run) only runs after the human allowed that unique on that machine.

5. Queues & cursors

The host keeps one ring buffer of up-events (default 2000). Readers hold cursors: claude (the listen tool), hook (the prompt hook), plus any named cursor. listen returns events after its cursor and advances it; it blocks up to wait_ms when nothing is pending. Noise is coalesced before it reaches the buffer: pointer moves never enter it, and repeated graph.changed within 400 ms collapse to the latest.

6. Unique manifest (unique.json)

{
  "lip": 1,
  "name": "graph",
  "version": "0.1.0",
  "title": "Graph — talk in diagrams",
  "description": "Draw flows and ideas; the companion and Claude read them.",
  "entry": "ui/index.html",
  "guide": "GUIDE.md",
  "icon": "icon.svg",
  "domains": ["graph"],
  "capabilities": ["entity", "chat", "components", "media.image", "clipboard"],
  "events": { "graph.node.select": { "summary": "User selected nodes", "schema": "schemas/node.select.json" } },
  "commands": { "graph.node.add": { "summary": "Add a node", "schema": "schemas/node.add.json" } },
  "permissions": { "fs.write": ["uploads"], "net": [], "exec": [] },
  "session": { "export": "graph.export", "snapshot": "graph.snapshot", "restore": "graph.load" },
  "author": { "name": "…", "url": "…" },
  "license": "MIT",
  "repository": "https://github.com/…"
}

Rules the host enforces:

1. name is ^[a-z][a-z0-9-]{1,31}$, unique across registries.
2. entry resolves inside the unique folder; nothing outside it is ever served.
3. domains may not include reserved ones.
4. Every event/command type a unique declares starts with one of its domains.
5. Unknown top-level keys are kept (forward compatibility) but ignored.
6. lip major must match the host's.
7. session (optional, 0.4.0) names the export / snapshot / restore types for handoff (§3.1b); each must start with one of the unique's domains. Without it the host assumes <domain>.export, <domain>.snapshot, <domain>.load.
8. permissions.exec (optional, 0.7.0) lists the languages the unique may ask the host to run, for example ["python", "javascript"]. The host refuses /lip/run for any other language, and for a unique without exec.

7. Guide (GUIDE.md)

Prose for Claude: what each event means and how to react, what commands exist, and the unique's etiquette. The open tool returns it; the lets skill tells Claude to obey it for the window's lifetime. Keep guides under about 1,500 words.

8. Versioning

• lip major bumps only on envelope-incompatible changes.
• New message types are additive and ignorable: a receiver MUST ignore types it does not know (and MAY log them), never fail.
• Uniques pin the minimum host version in engine: ">=0.1.0" (optional).

9. Future mediums

A unique for a medium without a pointer (voice, gesture, AR, neural) still emits entity.summon, component.action, media.*: the meaning of an act, not its mechanics. New domains are free to add; shells for new mediums implement §3 semantics in whatever way the medium affords. The envelope never changes shape.

Source of truth: protocol/LIP.md and the JSON schemas next to it in the lets repo.