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.
The agent shell — your agent, the command line, and persistent navigation
three.ws is the platform where every user owns a living, embodied AI agent — and the agent shell makes that agent the way you use the site, not just something you build on it. It has three layers, each usable on every page:
- Your agent, in the first five seconds. Every visitor gets a named agent immediately — no account, no wallet.
- An agentic ⌘K command line. The search palette executes real work in place: generate a 3D model, read the day's news, quote a coin, ask a question.
- A persistent shell. On shell-enabled pages, navigation swaps only the page content — the header, the command line, and your walking agent are never torn down.
1. Your agent (the companion with an identity)
On a first visit, the corner companion summons itself a couple of seconds after the page loads and introduces itself with a generated name ("Turbo Kraken", "Chrome Koi") and a light 3D body. The identity is an ephemeral agent draft stored locally — nothing is created server-side until the visitor claims it.
- The chip under the avatar shows the agent's name. For guests it carries a
Claim → link into
/create-agent, which prefills the wizard from the draft; finishing the wizardPOST /api/agentscreates the real agent (with its wallets) and clears the draft. Signed-in visitors see their canonical agent's name (from src/agents/active-agent.js). - The agent reacts to work done through the ⌘K palette — it waves and comments
when a forge finishes or a digest arrives (
tws:palette-actionDOM events, mirrored onto the agent bus asaction:taken). - Auto-summon is polite: it waits for
load, then for the main thread to go 1.2 seconds without a long task (giving up after 20 seconds rather than landing on a busy page), skips visitors withprefers-reduced-motionorSave-Data, skips full-screen 3D/camera routes (/play,/tour,/scan,/create/selfie, …), and never re-summons after the visitor closes the companion. A page opts out withdata-walk-auto="off"on itshtmlelement. The existing nav "Walk" toggle keeps working exactly as before.
Key modules: src/agents/guest-agent.js (draft store), src/shared/agent-names.js (namer), src/walk-companion-identity.js (chip, introduction, reactions), auto-start gate in public/nav.js.
2. The ⌘K command line
Press ⌘K / Ctrl-K anywhere. Beyond search, the palette parses executable verbs and runs them in place against the real public APIs — no account needed:
| Command | Example | What happens |
|---|---|---|
forge <prompt> (also make, generate, imagine) |
forge a bronze dragon statue |
POST /api/forge on the free text→3D lane, polls to completion, returns open/download/refine links for the real GLB |
digest (also briefing, what happened today) |
digest |
GET /api/news/digest — the last 24h clustered into narratives, rendered as rows |
price <coin> (also quote) or $ticker |
price btc, $sol |
GET /api/coin/markets + /detail, falling back to pump.fun token search |
ask <question> (or any query of ten or more characters ending in ?) |
ask what is x402? |
POST /api/chat: the site agent's answer streamed into the panel; honors the free lane's retry_after backoff when it's at capacity |
Grammar rules: commands are strict verb-first parses — a bare verb (forge)
or a plain search query is never hijacked. A natural question ("how do agents
pay each other?") is offered as an Ask row under the search results, never
auto-run. Esc steps back from a run panel to the results; typing does the
same.
For other surfaces: window.__twsSearch.parseCommand(q) exposes the grammar,
and window.__twsSearch.runCommand(q) opens the palette and executes — both in
public/search.js.
3. The persistent shell
Pages that mark themselves with data-shell on their root html element get
same-document navigation: clicking between two shell pages fetches the
destination, swaps only the main element (plus title/meta), and pushes
history — the header, footer, corner stack, palette, and companion survive
untouched. Back/forward work the same way. Anything unexpected (an unmarked
destination, a fetch error) falls back to a normal full navigation, so the
shell can only ever add continuity.
Page modules opt in through one contract — src/shell/page-lifecycle.js:
import { onPageReady } from './shell/page-lifecycle.js';
onPageReady(({ signal }) => init(), {
match: (path) => path.replace(/\/$/, '') === '/markets',
});
init runs on first load and again on every shell navigation back to a
matching path; the previous run's AbortSignal is aborted first, so intervals
and document listeners registered with { signal } clean themselves up.
Requirements for a shell page:
data-shellon thehtmlelement, andmainas a direct child ofbody(the standard page skeleton).- The page's module initializes via
onPageReadyand its async renderers tolerate their target elements disappearing mid-flight (a navigation can land while a fetch is pending).
Live proof pages (every page carrying data-shell today):
| Route | Page |
|---|---|
/markets |
pages/markets.html |
/coins |
pages/coins.html |
/pocket |
pages/pocket.html |
/markets/robinhood |
pages/markets-robinhood.html |
/markets/robinhood/desk |
pages/hood-desk.html |
/markets/robinhood/portfolios |
pages/hood-portfolios.html |
/markets/robinhood/portfolios/universe |
pages/hood-portfolios-universe.html |
Navigating between any two of them is a content swap, which is what makes the
Robinhood Crypto cluster feel like one terminal rather than four pages. The
swapper lives in
src/view-transitions.js, which is inlined on
every page by the view-transitions plugin in
vite.config.js.
Caution for that inlined file: it must stay dependency-free, keep exactly
one export function, and contain no HTML-looking sequences in comments or
strings — in dev, runtime-fetched fragments would otherwise render its source
as DOM (the plugin also explicitly skips nav.html/footer.html fragments for
this reason).
How the pieces reinforce each other
The shell is one loop, not three features: the visitor lands and meets their agent → the agent points them at ⌘K → a command does real work (a forged model, a digest) → the agent reacts, building the relationship → Claim turns the relationship into an account with a real agent. Ambient discovery routes through the agent too — the old "have you tried…" toast stays out of the corner while the companion is live.
Related: web-component.md (the embeddable agent-3d
avatar), coin-pages.md (the market surfaces the shell
navigates), companion.md (the same corner companion delivering
messages from connected sources in person), feedback.md
(reporting what broke through the companion), STRUCTURE.md
(surface map).