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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// three.ws Desktop: the main process.
//
// One app, two faces:
//
// - The console: a window for operating your agents. Sign in once through
// the browser (OAuth 2.1 + PKCE on a loopback port), then see your agents,
// chat with them and watch their tools work, follow runs step by step,
// check wallets and approve or cancel what an agent wants to spend,
// receive account notifications as native OS notifications, and wire
// three.ws into every coding client on the machine in one click.
// - Companion mode (src/main/companion.js): the 3D character that walks the
// desktop and delivers what matters in person. Toggle it from the tray or
// from Settings.
//
// Security posture: the console renderer is sandboxed, context-isolated, has
// no network access of its own (its CSP allows no connections), and never sees
// a token. Every request goes through this process, which attaches the bearer.
// Anything that moves money goes through src/main/previews.js: a single-use
// preview id, then a native confirmation built from the stored request.
import { app, BrowserWindow, Tray, Menu, ipcMain, shell, Notification, nativeImage, dialog, safeStorage, crashReporter } from 'electron';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
import { homedir } from 'node:os';
import { execFile } from 'node:child_process';
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import { createSecureStore } from './main/secure-store.js';
import { createSession } from './main/session.js';
import { createConsoleApi } from './main/console-api.js';
import { createPreviewRegistry, isGuardedPath } from './main/previews.js';
import { createNotifier } from './main/notifier.js';
import { createUpdater } from './main/updater.js';
import { createCompanion } from './main/companion.js';
import { createLocalRuntimeService } from './main/local-runtime.js';
import { createPanel } from './main/panel.js';
import { trayTitle, trayTooltip } from './panel/model.js';
import { detectEditors, connectEditor, disconnectEditor, mcpServers } from './main/editors.js';
const SRC = dirname(fileURLToPath(import.meta.url));
// Electron 44 removed openAsHidden / wasOpenedAsHidden. Windows now carries
// --hidden as a login-item argument (the same args must be passed when reading
// the setting back); macOS reports a login launch through wasOpenedAtLogin.
const LOGIN_ARGS = ['--hidden'];
const loginQuery = () => (process.platform === 'win32' ? { args: LOGIN_ARGS } : {});
const launchAtLogin = () => app.getLoginItemSettings(loginQuery()).openAtLogin;
function setLaunchAtLogin(enabled) {
app.setLoginItemSettings({ openAtLogin: Boolean(enabled), ...loginQuery() });
}
const launchedAtLogin = () => process.platform === 'darwin' && app.getLoginItemSettings().wasOpenedAtLogin === true;
const ASSETS = join(SRC, '..', 'assets');
// ── Settings (non-secret preferences) ────────────────────────────────────────
const settingsFile = () => join(app.getPath('userData'), 'settings.json');
function readSettings() {
try {
return JSON.parse(readFileSync(settingsFile(), 'utf8'));
} catch {
return {};
}
}
function writeSettings(patch) {
const next = { ...readSettings(), ...patch };
mkdirSync(dirname(settingsFile()), { recursive: true });
writeFileSync(settingsFile(), JSON.stringify(next, null, 2));
return next;
}
// ── State ────────────────────────────────────────────────────────────────────
const state = {
console: null,
tray: null,
unread: 0,
chats: new Map(),
runWatches: new Map(),
};
let session;
let api;
let previews;
let notifier;
let updater;
let companion;
let localRuntime;
let panel;
let trayMenu = null;
let store;
function sendToConsole(channel, payload) {
const win = state.console;
if (win && !win.isDestroyed()) win.webContents.send(channel, payload);
}
// ── Console window ───────────────────────────────────────────────────────────
function openConsole(view) {
if (state.console && !state.console.isDestroyed()) {
if (state.console.isMinimized()) state.console.restore();
state.console.show();
state.console.focus();
if (view) sendToConsole('app:navigate', view);
return state.console;
}
if (process.platform === 'darwin') app.dock?.show();
const win = new BrowserWindow({
width: 1180,
height: 780,
minWidth: 860,
minHeight: 560,
show: false,
title: 'three.ws',
backgroundColor: '#0d0d10',
...(process.platform === 'darwin' ? { titleBarStyle: 'hiddenInset', trafficLightPosition: { x: 16, y: 18 } } : {}),
icon: join(ASSETS, 'icon.png'),
webPreferences: {
preload: join(SRC, 'console-preload.cjs'),
contextIsolation: true,
nodeIntegration: false,
sandbox: true,
spellcheck: true,
},
});
win.loadFile(join(SRC, 'console', 'index.html'), view ? { hash: view } : undefined);
win.once('ready-to-show', () => win.show());
win.on('focus', () => notifier?.setFocused(true));
win.on('blur', () => notifier?.setFocused(false));
win.on('closed', () => {
state.console = null;
notifier?.setFocused(false);
for (const c of state.chats.values()) c.abort();
state.chats.clear();
for (const w of state.runWatches.values()) w.abort();
state.runWatches.clear();
if (process.platform === 'darwin') app.dock?.hide();
});
if (process.argv.includes('--dev')) win.webContents.openDevTools({ mode: 'detach' });
state.console = win;
return win;
}
// Links out of the app: https anywhere, and site-relative paths on the server
// the person signed in to. Everything else is dropped.
function openExternal(url) {
const target = String(url || '');
if (/^https:\/\//i.test(target)) return shell.openExternal(target).then(() => true);
if (/^\/(?!\/)/.test(target)) return shell.openExternal(`${session.apiBase()}${target}`).then(() => true);
if (/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?\//i.test(target)) return shell.openExternal(target).then(() => true);
return Promise.resolve(false);
}
// ── Tray / menu bar ──────────────────────────────────────────────────────────
function trayIcon() {
const img = nativeImage.createFromPath(join(ASSETS, process.platform === 'darwin' ? 'trayTemplate.png' : 'tray-icon.png'));
if (img.isEmpty()) return nativeImage.createEmpty();
if (process.platform === 'darwin') img.setTemplateImage(true);
return img;
}
function updateTrayTitle(snapshot) {
if (!state.tray) return;
const view = { signedIn: snapshot.signedIn, name: snapshot.user?.name, pendingApprovals: snapshot.pending.length, unread: snapshot.unread };
state.tray.setToolTip(trayTooltip(view));
if (process.platform === 'darwin') state.tray.setTitle(trayTitle(view));
}
function refreshTray() {
if (!state.tray) return;
const s = session.status();
const c = companion.status();
const u = updater.state();
const who = s.signedIn ? (s.user?.name || 'Signed in') : 'Not signed in';
panel?.touch();
const template = [
{ label: `three.ws Desktop · ${who}`, enabled: false },
{ label: 'Show panel', click: () => panel.show() },
{ label: 'Open console', accelerator: 'CommandOrControl+Shift+Space', click: () => openConsole() },
...(s.signedIn ? [
{ label: state.unread ? `Notifications (${state.unread} unread)` : 'Notifications', click: () => openConsole('notifications') },
{ label: 'Chat', click: () => openConsole('chat') },
{ label: 'Wallet and approvals', click: () => openConsole('wallet') },
] : [
{ label: 'Sign in…', click: () => openConsole() },
]),
{ type: 'separator' },
...(localRuntime ? localRuntime.trayItems() : []),
{ label: 'Local agents…', click: () => openConsole('local') },
{ type: 'separator' },
{ label: 'Companion mode', type: 'checkbox', checked: c.enabled, click: (item) => setCompanionMode(item.checked) },
...(c.enabled ? [
{ label: c.paused ? 'Resume deliveries' : 'Pause deliveries', click: () => companion.togglePause() },
{ label: 'Say the last one again', enabled: c.hasLastDelivery, click: () => companion.replayLast() },
{ label: c.signedIn ? 'Change bridge token…' : 'Connect companion…', click: () => companion.openSignIn() },
] : []),
{ type: 'separator' },
u.status === 'ready'
? { label: `Restart to update to ${u.available}`, click: () => updater.installNow() }
: { label: u.status === 'checking' ? 'Checking for updates…' : u.status === 'downloading' ? `Downloading update${u.progress != null ? ` (${u.progress}%)` : ''}…` : 'Check for updates', enabled: app.isPackaged && !['checking', 'downloading'].includes(u.status), click: () => updater.check() },
{
label: 'Start at login',
type: 'checkbox',
checked: launchAtLogin(),
click: (item) => setLaunchAtLogin(item.checked),
},
{ type: 'separator' },
{ label: 'Quit three.ws', role: 'quit' },
];
trayMenu = Menu.buildFromTemplate(template);
// Linux indicators often deliver no click events, so the menu stays attached
// there. Elsewhere a left click opens the panel and a right click the menu.
if (process.platform === 'linux') state.tray.setContextMenu(trayMenu);
}
function setCompanionMode(enabled) {
writeSettings({ companionMode: Boolean(enabled) });
const s = enabled ? companion.enable() : companion.disable();
sendToConsole('app:companion', s);
refreshTray();
return s;
}
// ── Native notifications ─────────────────────────────────────────────────────
function showNativeNotification(n) {
if (!Notification.isSupported()) return;
const toast = new Notification({ title: n.title, body: n.text, silent: false });
toast.on('click', () => {
openConsole('notifications');
api.markRead(n.id).catch(() => {});
});
toast.show();
}
// The last gate before real funds move. Built from the summary the main
// process stored with the preview, never from anything the renderer sent.
async function confirmFinancial(summary) {
const lines = [
`Recipient: ${summary.recipient || 'unknown'}`,
`Amount: ${summary.amount ?? 'unknown'} ${summary.token || ''}`.trim(),
`Chain: ${summary.chain || 'Solana'}`,
summary.usd != null ? `Value: about $${Number(summary.usd).toFixed(2)}` : null,
'',
'This moves real funds and cannot be undone.',
].filter((l) => l !== null);
const parent = state.console && !state.console.isDestroyed() ? state.console : undefined;
const { response } = await dialog.showMessageBox(parent, {
type: 'warning',
buttons: ['Cancel', 'Send'],
defaultId: 0,
cancelId: 0,
noLink: true,
title: 'Confirm send',
message: `Send ${summary.amount ?? ''} ${summary.token || ''} to ${summary.recipient || 'this address'}?`.replace(/\s+/g, ' '),
detail: lines.join('\n'),
});
return response === 1;
}
// ── IPC ──────────────────────────────────────────────────────────────────────
// Every console call answers { ok, data } or { ok: false, error }, because a
// rejected ipcMain.handle loses everything but the message, and the renderer
// needs the code (signed_out, preview_expired, ...) to pick the right state.
function handle(channel, fn) {
ipcMain.handle(channel, async (event, ...args) => {
if (!state.console || event.sender !== state.console.webContents) return { ok: false, error: { message: 'Not allowed from this window', code: 'forbidden' } };
try {
return { ok: true, data: await fn(...args) };
} catch (err) {
return { ok: false, error: { message: err?.message || String(err), code: err?.code || null, status: err?.status || null } };
}
});
}
function editorContext() {
return {
home: homedir(),
platform: process.platform,
env: process.env,
claudeCli: (args) => new Promise((resolve, reject) => {
execFile('claude', args, { timeout: 20_000, shell: process.platform === 'win32' }, (err, stdout) => (err ? reject(err) : resolve(stdout)));
}),
};
}
function appInfo() {
return {
version: app.getVersion(),
platform: process.platform,
arch: process.arch,
packaged: app.isPackaged,
update: updater.state(),
companion: companion.status(),
encryptedStore: store.encrypted(),
launchAtLogin: launchAtLogin(),
mcpServers: mcpServers(session.apiBase()),
};
}
// Copies only the named keys of a renderer-supplied object, so an unexpected
// field can never reach the runtime.
function pickObject(value, keys) {
const out = {};
if (value && typeof value === 'object') for (const k of keys) if (value[k] !== undefined) out[k] = value[k];
return out;
}
function registerIpc() {
handle('session:status', () => session.status());
handle('session:signIn', (opts) => session.signIn(opts || {}));
handle('session:cancelSignIn', () => session.cancelSignIn());
handle('session:signOut', async () => {
notifier.stop();
api.resetCapabilities();
return session.signOut();
});
handle('session:refreshUser', () => session.refreshUser());
// Local agent runtime. The renderer can read, create, pause, resume, kill and
// deny. It has no approve channel: approving goes through runtime:review, which
// opens a native dialog built in this process from the stored approval, so what
// is approved is what was shown and the hash never comes from the renderer.
handle('runtime:list', () => ({ agents: localRuntime.runtime.listAgents(), face: localRuntime.runtime.face(), keychain: localRuntime.keysEncrypted() }));
handle('runtime:create', (input) => localRuntime.runtime.createAgent(pickObject(input, ['name', 'mode', 'network', 'strategy'])));
handle('runtime:pause', (id) => localRuntime.runtime.pause(String(id)));
handle('runtime:resume', (id) => localRuntime.runtime.resume(String(id)));
handle('runtime:kill', (id) => localRuntime.runtime.kill(String(id)));
handle('runtime:remove', (id) => localRuntime.runtime.remove(String(id)));
handle('runtime:addOrder', (id, order) => localRuntime.runtime.addOrder(String(id), pickObject(order, ['mint', 'side', 'amount_sol', 'trigger'])));
handle('runtime:removeOrder', (id, orderId) => localRuntime.runtime.removeOrder(String(id), String(orderId)));
handle('runtime:addAutomation', (id, auto) => localRuntime.runtime.addAutomation(String(id), pickObject(auto, ['action', 'every_minutes'])));
handle('runtime:approvals', (filter) => localRuntime.runtime.listApprovals({ status: filter?.status || null, agentId: filter?.agentId || null }));
handle('runtime:review', (approvalId) => localRuntime.decideThroughDialog(String(approvalId)));
handle('runtime:deny', (approvalId) => {
const ap = localRuntime.runtime.listApprovals().find((a) => a.id === String(approvalId));
return localRuntime.runtime.decide(String(approvalId), { decision: 'deny', hash: ap?.hash, via: 'desktop' });
});
handle('runtime:receipts', (filter) => localRuntime.runtime.receipts({ agentId: filter?.agentId || null, limit: 200 }));
handle('runtime:positions', (filter) => localRuntime.runtime.positions({ agentId: filter?.agentId || null }));
handle('runtime:tick', () => localRuntime.runtime.tick().then(() => localRuntime.runtime.listAgents()));
handle('capabilities', () => api.capabilities());
handle('agents:list', () => api.listAgents());
handle('agents:setStatus', (agentId, running) => api.setAgentStatus(agentId, running));
handle('chat:history', (agentId) => api.chatHistory(agentId));
handle('chat:send', ({ agentId, message, history }) => {
const requestId = randomUUID();
const controller = new AbortController();
state.chats.set(requestId, controller);
api.sendChat({ agentId, message, history, signal: controller.signal }, (evt) => sendToConsole('chat:event', { requestId, ...evt }))
.catch((err) => {
if (controller.signal.aborted) sendToConsole('chat:event', { requestId, type: 'aborted' });
else sendToConsole('chat:event', { requestId, type: 'error', message: err.message, code: err.code || null });
})
.finally(() => {
state.chats.delete(requestId);
sendToConsole('chat:event', { requestId, type: 'end' });
});
return { requestId };
});
handle('chat:abort', (requestId) => {
state.chats.get(requestId)?.abort();
return true;
});
handle('runs:list', (agentId) => api.listRuns(agentId));
handle('runs:detail', (runId) => api.runDetail(runId));
handle('runs:create', (agentId, input) => api.createRun(agentId, input));
handle('runs:cancel', (runId) => api.cancelRun(runId));
handle('runs:watch', (runId) => {
state.runWatches.get(runId)?.abort();
const controller = new AbortController();
state.runWatches.set(runId, controller);
api.streamRun(runId, (evt) => sendToConsole('runs:event', { runId, ...evt }), controller.signal)
.catch((err) => {
if (!controller.signal.aborted) sendToConsole('runs:event', { runId, type: 'error', message: err.message });
})
.finally(() => {
if (state.runWatches.get(runId) === controller) state.runWatches.delete(runId);
sendToConsole('runs:event', { runId, type: 'end' });
});
return true;
});
handle('runs:unwatch', (runId) => {
state.runWatches.get(runId)?.abort();
state.runWatches.delete(runId);
return true;
});
handle('wallet:get', (agentId) => api.wallet(agentId));
handle('preview:create', (kind, input) => previews.create(kind, input));
handle('preview:approve', (previewId) => previews.approve(previewId));
handle('preview:cancel', (previewId) => previews.cancel(previewId));
handle('proposal:dismiss', (agentId, proposalId) => api.dismissProposal(agentId, proposalId));
handle('notifications:list', (opts) => api.notifications(opts || {}));
handle('notifications:read', async (id) => {
await api.markRead(id);
return notifier.poll();
});
handle('notifications:readAll', async () => {
await api.markAllRead();
return notifier.poll();
});
handle('editors:detect', () => detectEditors(editorContext(), session.apiBase()));
handle('editors:connect', (id) => connectEditor(editorContext(), id, session.apiBase()));
handle('editors:disconnect', (id) => disconnectEditor(editorContext(), id, session.apiBase()));
handle('app:info', () => appInfo());
handle('app:setCompanion', (enabled) => setCompanionMode(enabled));
handle('app:companionSignIn', () => companion.openSignIn());
handle('app:checkUpdates', () => updater.check());
handle('app:installUpdate', () => updater.installNow());
handle('app:setLaunchAtLogin', (enabled) => {
setLaunchAtLogin(enabled);
refreshTray();
return launchAtLogin();
});
handle('app:openExternal', (url) => openExternal(url));
// A generic read for views that need a route not wrapped above. Reads only:
// every write has its own typed channel, and money has none but previews.
handle('api:get', (path) => {
if (isGuardedPath(path, 'GET')) throw new Error('Not allowed');
return session.request(String(path));
});
}
// ── Lifecycle ────────────────────────────────────────────────────────────────
function lockDownNavigation() {
app.on('web-contents-created', (_event, contents) => {
contents.setWindowOpenHandler(({ url }) => {
openExternal(url);
return { action: 'deny' };
});
contents.on('will-navigate', (event, url) => {
if (!url.startsWith('file://')) {
event.preventDefault();
openExternal(url);
}
});
});
}
function boot() {
store = createSecureStore({ file: join(app.getPath('userData'), 'session.bin'), safeStorage });
session = createSession({
store,
version: app.getVersion(),
openBrowser: (url) => shell.openExternal(url),
onChange: (status) => {
sendToConsole('session:changed', status);
if (status.signedIn) {
notifier?.start();
panel?.sync();
} else notifier?.stop();
refreshTray();
},
});
api = createConsoleApi({ session });
previews = createPreviewRegistry({ request: (path, init) => session.request(path, init), confirm: confirmFinancial });
notifier = createNotifier({
api,
onNew: showNativeNotification,
onUnread: (count) => {
state.unread = count;
sendToConsole('notifications:unread', count);
if (process.platform !== 'win32') app.setBadgeCount(count);
refreshTray();
},
});
updater = createUpdater({
app,
onState: (s) => {
sendToConsole('updater:state', s);
refreshTray();
},
});
companion = createCompanion({ srcDir: SRC, onChange: (s) => { sendToConsole('app:companion', s); refreshTray(); } });
localRuntime = createLocalRuntimeService({
app,
safeStorage,
session,
getConsole: () => state.console,
onChange: refreshTray,
onFace: (face) => companion.setFace(face),
});
panel = createPanel({
srcDir: SRC,
session,
api,
runtime: localRuntime.runtime,
companion,
getUnread: () => state.unread,
readSettings,
writeSettings,
openConsole,
setCompanionMode,
openExternal,
onChange: updateTrayTitle,
});
panel.setReview((id) => localRuntime.decideThroughDialog(id));
registerIpc();
panel.register();
state.tray = new Tray(trayIcon());
state.tray.on('click', () => panel.toggle());
state.tray.on('right-click', () => trayMenu && state.tray.popUpContextMenu(trayMenu));
panel.attachTray(state.tray);
refreshTray();
if (readSettings().companionMode) companion.enable();
if (session.status().signedIn) notifier.start();
updater.start();
localRuntime.runtime.start();
companion.setFace(localRuntime.runtime.face());
// Launched at login stays in the tray; launched by hand opens the console.
const hidden = launchedAtLogin() || process.argv.includes('--hidden');
if (!hidden) openConsole();
}
// Crash dumps stay on this machine. They can hold process memory, and the
// signing keys are decrypted in memory while the runtime signs, so nothing is
// ever uploaded and nothing is sent to a collection server.
crashReporter.start({ uploadToServer: false, compress: true, submitURL: '' });
// One instance only: two consoles would double every notification.
if (!app.requestSingleInstanceLock()) {
app.quit();
} else {
app.setAppUserModelId('ws.three.desktop');
lockDownNavigation();
app.on('second-instance', () => openConsole());
app.on('activate', () => openConsole());
app.whenReady().then(boot);
// Closing the console leaves the app in the tray; Quit lives in the tray menu.
app.on('window-all-closed', () => {});
app.on('before-quit', () => {
panel?.stop();
companion?.stop();
notifier?.stop();
localRuntime?.runtime.stop();
});
}