Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

7.1 KB
Raw Blame

three.ws Companion for desktop

A 3D character that lives on your desktop, strolls across the bottom of your screen, and walks over to tell you the things worth interrupting you for.

Not a notification center. Not another window to manage. A small person who knows which of your messages matter, arrives in the body of whoever sent them, and says it out loud.

┌───────────────────────────────────────────────────────────────────┐
│                                                                   │
│   your actual desktop, untouched                                  │
│                                                                   │
│                    ╭───────────────────────────────╮              │
│                    │ SARAH                         │              │
│                    │ Sarah says she is downstairs  │              │
│                    │ and cannot find your door.    │              │
│                    │ 88/100 · saved contact; asks  │              │
│                    │ you for something directly    │              │
│                    │  [ Open ]  [ Got it ]         │              │
│                    ╰───────────────╮───────────────╯              │
│                              🚶 ← walks over, waves, speaks       │
└───────────────────────────────────────────────────────────────────┘

What it does

  • Lives on top of everything, on every workspace, including over full-screen apps, and is click-through everywhere except the character and its bubble. You never have to move it, and it never eats a click meant for your editor.
  • Wanders. It walks to a new spot every half minute or so, facing the way it is going, then idles. It is alive, not a widget.
  • Delivers in person. When something clears your bar (a message from a saved contact, a meeting about to start, a one-time code, an agent that decided you need to know), it walks to the middle of the screen, waves, shows the line and says it aloud in that sender's voice, wearing that sender's avatar.
  • Respects the bar you set. Threshold, quiet hours, per-contact priority and which sources are connected all live at three.ws/companion. This app is a body, not a second set of rules.
  • Pauses from the tray, and can start at login.
  • Menu bar panel. Click the tray icon for a popover with your agent in 3D, its wallet balance, start and stop, pending approvals and a one-line ask box. See docs/desktop-menu-bar-panel.md.

Install and run

cd apps/desktop
npm install
npm start

Then either sign in from the window that opens, or, if you already use the CLI:

npx @three-ws/companion login --token cmp_…

Both read the same file (~/.config/three-ws/companion.json, or ~/Library/Application Support/three-ws/companion.json on macOS), so signing in once signs in everything on that machine. Get the token from three.ws/companion; rotating it there disconnects every device at once.

Local agents

The app also runs agents on your machine, with keys in the OS keychain and paper strategies that work offline from the account. Open Local agents in the console (or the tray). Try the runtime headless:

npm run smoke:runtime

Full guide: docs/desktop-local-runtime.md.

Build an installer

npm run dist          # for the platform you are on
npm run dist:mac      # dmg + zip
npm run dist:win      # nsis
npm run dist:linux    # AppImage + deb

Linux output lands in dist/ (three.ws-Desktop-<version>-linux-x86_64.AppImage and -linux-amd64.deb). The macOS and Windows installers build unsigned until the owner supplies the Apple Developer ID certificate (CSC_LINK, CSC_KEY_PASSWORD) and notarization key (APPLE_API_KEY, APPLE_API_KEY_ID, APPLE_API_ISSUER) and a Windows code-signing certificate. Auto-update only trusts signed releases, so those are the remaining owner steps; npm run release:mac is the one command once they exist.

npm run smoke:runtime reaches the venue's public launch feed. If your network is blocked from it, the smoke prints SKIP for the fill checks and still verifies create, pause, kill and log hygiene.

How it works

three.ws  ──SSE──▶  main process  ──IPC──▶  transparent window
  triage            @three-ws/companion      walk-embed iframe
                    stream + token           postMessage contract
  • src/main.js owns the transparent always-on-top window, the tray menu, the delivery stream (@three-ws/companion), and the OS-level fallbacks (native notification, say on macOS). It hands mouse input back to the OS everywhere the renderer says nothing clickable is.
  • src/preload.cjs is the only bridge into the renderer: context isolation on, node integration off, six calls exposed and nothing else. The renderer embeds remote content, so it gets no filesystem and no process access.
  • src/renderer/ is the stage. The body is the published three.ws walking avatar embed driven over its documented postMessage contract, so this app carries no 3D code of its own and inherits every avatar, rig and animation the platform ships.

Privacy

  • The app holds one credential: your bridge token. No mail password, no bot token, no calendar URL ever reaches it.
  • It makes exactly two kinds of outbound request: the delivery stream, and the voice lane that speaks a line. Both go to the server you configured.
  • If you would rather your own inbox never leave your machine at all, run companion watch-imap --redact from @three-ws/companion: it triages mail locally and sends only the sentence that earned an interruption.

Platform notes

  • macOS: the window is a panel, so it floats over full-screen apps. The dock icon is hidden; the app lives in the menu bar. say is the last-resort voice if the hosted lanes and the built-in speech synthesis both fail.
  • Windows / Linux: always-on-top with click-through. Transparent windows need a compositor; on a bare X11 session without one the window falls back to an opaque strip, and the tray menu still works.
  • Multi-monitor: the stage tracks the primary display's work area and follows resolution changes.

Related

License

Apache-2.0