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.
20. Local agent runtime and terminal UI: three-ws agent
Read docs/prompts/README.md first.
The problem
Everything an agent does today runs on our servers. There is no way to run a three.ws agent on your own machine or VPS with a real terminal interface, talk to it, let it work on local files and long tasks, and still use the platform's wallet, tools and marketplace through the API. The three-ws-tty and tty-avatar bins under packages/ render an avatar in a terminal; @three-ws/agent-runtime is the loop the server uses. The strongest open agents ship exactly this: a TUI, sessions, slash commands, subagents, cron, and a gateway process, installable anywhere.
Build
A new package packages/agent-cli/ published as @three-ws/agent, reachable as three-ws agent from the CLI in prompt 01 and as npx @three-ws/agent.
- Runtime: wraps
@three-ws/agent-runtimefor local execution with the unified MCP endpoint from prompt 17 as its tool source (plus local tools: file read and write, shell in the sandbox from prompt 25, web fetch from the tool gateway in prompt 26). Model access through the account's credits (prompt 16) or any OpenAI-compatible base URL the user sets. - TUI: multiline editor, slash-command autocomplete (
/model,/agent,/wallet,/skills,/runs,/new,/sessions,/cron,/subagent,/help), streaming tool output, interrupt and redirect, the terminal avatar fromtty-avataroptional in a pane. Useinkor the terminal library already inpackages/; do not hand-roll a renderer. - Sessions: local SQLite with full-text search over past conversations (
/search), resume by id, export to JSON. - Subagents:
/subagent <goal>spawns an isolated child run with its own context and budget, reporting back into the parent. - Cron:
/cron "every weekday 9am" "post the portfolio summary to Telegram"stores natural-language schedules parsed with a maintained cron-parsing package, executed by a local scheduler or, when the machine is off, by prompt 05 automations on the server (the user picks). - Gateway mode:
three-ws agent gatewayruns the local agent as the backend for the chat gateways in prompts 13 and 24, so messages from Telegram reach the machine the user chose. - Install breadth: Linux, macOS, Windows native (PowerShell installer), WSL, Termux, and a Nix flake; Docker image with a
docker-compose.yml; a $5 VPS guide. - Docs:
docs/agent-cli.md,packages/agent-cli/README.md,STRUCTURE.mdrow, changelog entry taggedfeature, sdk.
Acceptance
- On a clean VPS: install,
three-ws agent, ask the agent to check its wallet balance and to write a file; both happen. /subagentruns in parallel with the main session and reports back.- A cron fires on schedule with the machine on, and hands off to the server when the user picks server mode.
npm testgreen with TUI component tests and session search tests.