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.

docs(tty): document the terminal renderer and link it from the docs nav

nirholasb3b76c7d3726
diff --git a/docs/nav.json b/docs/nav.json
index 3360b3ead..e69e6fa9a 100644
--- a/docs/nav.json
+++ b/docs/nav.json
@@ -917,6 +917,10 @@
{
"label": "Shared utilities",
"path": "shared-utilities"
+ },
+ {
+ "label": "Terminal renderer",
+ "path": "tty"
}
]
},
diff --git a/docs/tty.md b/docs/tty.md
new file mode 100644
index 000000000..662822c7e
--- /dev/null
+++ b/docs/tty.md
@@ -0,0 +1,137 @@
+# Terminal renderer
+
+`curl three.ws/tty` and a rigged 3D agent walks in your terminal.
+
+No GPU is involved, on either side. There is no WebGL, no browser, and nothing to
+install. A software rasterizer decodes the model, evaluates its animation, blends
+the joint matrices per vertex on the CPU, and rasterizes triangles into a buffer
+the size of your terminal. Then it writes the result as coloured text.
+
+```bash
+curl three.ws/tty
+```
+
+Press Ctrl-C to stop it. It works in any terminal that renders colour: macOS
+Terminal, iTerm2, Windows Terminal, GNOME Terminal, Alacritty, WezTerm, tmux, a
+VS Code terminal, an SSH session on a box with no display.
+
+## Why it exists
+
+three.ws gives AI agents a body. AI agents increasingly live in a terminal. This
+closes the gap: the same avatar that renders in WebGL on a web page renders in
+the shell where the agent actually runs, with no client to install and no
+graphics stack to negotiate.
+
+It is also useful on its own. A rigged character, animating, is a good way to
+check what a GLB actually contains before you wire it into anything.
+
+## The endpoint
+
+`GET /api/tty` streams frames as `text/plain`, paced in real time, so the
+response body *is* the animation. It starts drawing before the model has finished
+loading. Every parameter is optional.
+
+| Parameter | Meaning | Default |
+| --- | --- | --- |
+| `avatar` | A public three.ws avatar id. The path form `/tty/<id>` sets this. | the default model |
+| `src` | Any public GLB URL. | none |
+| `w`, `h` | Columns and rows. One row is two vertical pixels. | 76 x 30 |
+| `frames` | How many frames to send. `1` gives a still image. | 8 seconds worth |
+| `fps` | Frames per second, 4 to 30. | 18 |
+| `t` | Where in the clip to start, in seconds. | 0 |
+| `spin` | Turntable speed in radians per second. `0` holds still. | 0.9 |
+| `clip` | Animation name to play. | the first clip |
+| `color` | `truecolor`, `ansi256`, or `mono`. | `ansi256` |
+| `zoom` | 1 fits the model, higher moves closer. | 1 |
+| `pitch` | Camera elevation in radians. | 0.08 |
+
+```bash
+# a specific avatar, wider, held still instead of spinning
+curl 'three.ws/tty/8f2c1a90-1c4e-4b2b-9d77-3f0a1b2c3d4e?w=110&spin=0'
+
+# any public GLB
+curl 'three.ws/tty?src=https://example.com/robot.glb&frames=120'
+
+# one frame of plain ASCII, for a README, a commit hook, or a motd
+curl 'three.ws/tty?frames=1&color=mono&w=60'
+```
+
+Colour defaults to 256 rather than truecolor on purpose. `curl` forwards neither
+`COLORTERM` nor `TERM`, so the server cannot know what you are running, and
+guessing truecolor wrong sprays literal escape sequences across your screen.
+Pass `color=truecolor` if you know your terminal handles it.
+
+A browser asking for `/tty` gets [the page](https://three.ws/tty) instead of the
+stream, because a browser renders escape codes as literal garbage. Add `?raw=1`
+to see the bytes anyway.
+
+### Limits
+
+40 streams per IP per 10 minutes, in their own bucket so a terminal stream and a
+browser render never starve each other. A single stream is capped at 600 frames
+or 45 seconds. Private avatars never render: the endpoint is unauthenticated, so
+it only serves models that are already public.
+
+## Running it locally
+
+The renderer is published as [`@three-ws/tty-3d`](https://www.npmjs.com/package/@three-ws/tty-3d).
+
+```bash
+# a local file
+npx @three-ws/tty-3d ./avatar.glb
+
+# anything on the web
+npx @three-ws/tty-3d https://three.ws/avatars/default.glb --spin 1.4
+
+# a still frame, piped somewhere
+npx @three-ws/tty-3d avatar.glb --once --width 80 --color mono > frame.txt
+```
+
+Arrow keys orbit, `w`/`s` tilt, `+`/`-` zoom, space pauses, `q` quits.
+
+Piping is safe: when stdout is not a terminal the default is a single frame, not
+an infinite animation, so redirecting to a file terminates.
+
+### As a library
+
+```js
+import { loadModel, createRenderer } from '@three-ws/tty-3d';
+
+const model = await loadModel('./avatar.glb'); // path, https URL, or bytes
+const renderer = createRenderer(model, { width: 80, height: 40 });
+
+process.stdout.write(renderer.frame(1.25)); // one string per frame
+```
+
+`frame(time)` is pure: the same time always renders the same string. Full API in
+the [package README](https://github.com/nirholas/three.ws/tree/main/packages/tty-3d).
+
+## How it works
+
+**Half blocks, not ASCII art.** Each cell is a `▀` with its own foreground and
+background colour, so one character carries two independently coloured pixels.
+That doubles vertical resolution and makes pixels square, because terminal cells
+are roughly 1:2. It is why a sphere comes out round rather than squashed.
+
+**Real skinning.** Joint matrices are evaluated per frame from the glTF animation
+samplers and blended per vertex, so a rigged avatar moves its limbs. It is not a
+spinning static mesh. `EXT_meshopt_compression` is decoded on the way in, because
+most three.ws avatars ship compressed and a reader that skips the decoder reads
+garbage vertex data rather than failing.
+
+**Framing that holds still.** The camera radius is fixed from the widest frame of
+the clip while the centre tracks the current pose. Fitting each frame alone makes
+the camera breathe as the silhouette changes; fitting the union of every frame is
+worse on anything with root motion, because the union is a corridor as long as
+the character walks.
+
+**Silhouette-first shading.** A key light, a fill light, and a rim term. At this
+resolution the outline carries the shape, so faces turning away from the camera
+are lifted rather than crushed to black.
+
+## Related
+
+- [Widget types](/docs/widgets) puts a live WebGL agent on a web page.
+- [Avatars](/avatars) is where the models come from.
+- The [roadmap](https://github.com/nirholas/three.ws#roadmap) covers native
+ home-screen widgets, the other surface where an agent shows up outside a browser.
diff --git a/extensions/checkout-companion/avatar.svg b/extensions/checkout-companion/avatar.svg
new file mode 100644
index 000000000..8073b4cbc
--- /dev/null
+++ b/extensions/checkout-companion/avatar.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="three.ws checkout companion">
+ <defs>
+ <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+ <stop offset="0" stop-color="#6D5CFF"/>
+ <stop offset="1" stop-color="#21D4C2"/>
+ </linearGradient>
+ </defs>
+ <rect width="128" height="128" rx="28" fill="url(#g)"/>
+ <path d="M36 40h56a6 6 0 0 1 6 6v40a6 6 0 0 1-6 6H36a6 6 0 0 1-6-6V46a6 6 0 0 1 6-6Z" fill="#ffffff" opacity=".94"/>
+ <path d="M30 58h68" stroke="#6D5CFF" stroke-width="7" stroke-linecap="round" opacity=".55"/>
+ <circle cx="86" cy="76" r="17" fill="#16181D"/>
+ <path d="M79 76.5l5 5 10-11" stroke="#21D4C2" stroke-width="5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+</svg>
diff --git a/extensions/checkout-companion/icons/icon-128.png b/extensions/checkout-companion/icons/icon-128.png
new file mode 100644
index 000000000..a32f1b2b8
Binary files /dev/null and b/extensions/checkout-companion/icons/icon-128.png differ
diff --git a/extensions/checkout-companion/icons/icon-16.png b/extensions/checkout-companion/icons/icon-16.png
new file mode 100644
index 000000000..7b254bead
Binary files /dev/null and b/extensions/checkout-companion/icons/icon-16.png differ
diff --git a/extensions/checkout-companion/icons/icon-32.png b/extensions/checkout-companion/icons/icon-32.png
new file mode 100644
index 000000000..d01629581
Binary files /dev/null and b/extensions/checkout-companion/icons/icon-32.png differ
diff --git a/extensions/checkout-companion/icons/icon-48.png b/extensions/checkout-companion/icons/icon-48.png
new file mode 100644
index 000000000..cfe879176
Binary files /dev/null and b/extensions/checkout-companion/icons/icon-48.png differ