@three-ws/tty-avatar

A live 3D avatar in your terminal. Any GLB, or any three.ws avatar or agent by id, rendered by a software rasterizer to truecolor half-blocks or braille, animated with moods, and wired to Claude Code hooks so your coding agent has a face that thinks while it reads, works while it edits, and celebrates when it stops.

npx @three-ws/tty-avatar 81a076b6-55ff-49a2-b007-1d88e7dce2aa

No GPU, no browser, no account. Node 18+ and a terminal that can show colour.

                        ahd0w
                        bp00
                       h0mYow#
                       hJQpbh**d
                     oo####*ahdod
                     hhohaadwCkaw
                    #abQhaoZZao*om
                    *dwOo*bqO*#wUu
                   #*qk**aU0#*qJ
                  MqUo**hQw*#OL
                 Mp  o*omh##mqL
                #w  o*ooo**hba0
                L#   hhkqcZpZpO
                     bqmU ZpbdC
                      qmU  pdbC
                      qqU   qbQ
                      bU0   LO0

That is the ascii mode of a real three.ws agent body (tty-avatar snapshot agent:bd1b56b0-5494-47e2-ad78-04ef4c43ae5b --mode ascii), which is what you get when stdout is not a TTY. In a terminal you get colour and 24 frames a second.

Install

npm i -g @three-ws/tty-avatar     # or: npx @three-ws/tty-avatar …

Run

tty-avatar ./hero.glb                                   # a local model
tty-avatar https://example.com/robot.glb                # a URL
tty-avatar 81a076b6-55ff-49a2-b007-1d88e7dce2aa         # a three.ws avatar id
tty-avatar agent:bd1b56b0-5494-47e2-ad78-04ef4c43ae5b   # a three.ws agent (its 3D body)
tty-avatar https://three.ws/avatars/81a076b6-55ff-49a2-b007-1d88e7dce2aa   # a page URL

Options:

| Flag | Meaning | |---|---| | --mode blocks\|braille\|ascii | Glyph set. blocks (default on a TTY) is 1x2 truecolor half-blocks. braille is 2x4 dots per cell, four times the vertical detail. ascii is a luminance ramp with no escapes, the default when piped. | | --mood <name> | Starting mood (tty-avatar moods lists them). | | --fps <n> | Frame rate, default 24. | | --columns <n> --rows <n> | Override the terminal size. | | --yaw <deg> --pitch <deg> | Base rotation added to the mood's motion. | | --zoom <x> | 1 fits the whole model; 1.4 fills the frame with the upper body. | | --frames <n> | Exit after n frames (recording, CI). | | --no-caption | Hide the name and mood line. | | --no-alt | Draw inline instead of on the alternate screen. | | --max-triangles <n> | Decimate by stride above this many triangles (default 240000). A 20k-triangle avatar renders in under 5 ms per frame at 160x96 subpixels. | | --origin <url> | three.ws origin for id lookups. | | --state-dir <dir> | Where mood and hook files live (default ~/.three-ws/tty-avatar, or $TTY_AVATAR_DIR). | | --no-state | Ignore the state directory. |

Moods

A mood is procedural whole-body motion: no rig needed, so it works on any GLB, a prop included.

| Mood | Reads as | |---|---| | idle | slow sway, breathing | | spin | turntable | | think | tilted, looking up, slow sway | | work | small quick nods, like typing | | talk | bobbing on a speech rhythm | | happy | bouncing | | attention | pulsing, asking for you | | error | a fast shake | | sleep | head down, slow breathing |

Change the mood of a running viewer from any other shell:

tty-avatar mood happy --say "deploy landed" --ttl 5000   # back to idle after 5 s
tty-avatar say "running the migration"

Give your coding agent a face

Claude Code emits a hook event for every prompt, tool call, notification and stop. Wire them to the viewer once:

tty-avatar install-hooks --write        # merges into ~/.claude/settings.json

Then run a viewer in a split pane (tty-avatar <avatar id>) and start Claude Code in another. The avatar now:

| Claude Code event | Mood | Caption | |---|---|---| | SessionStart | happy | session started | | UserPromptSubmit | think | reading your prompt | | PreToolUse | work | editing index.js, $ npm test, searching, browsing, delegating | | PostToolUse | think, or error when the tool reported failure | Bash done | | Notification | attention (30 s) | the notification text | | Stop / SubagentStop | happy (4 s) | done | | PreCompact | think | compacting memory | | SessionEnd | sleep | session ended |

The installed hook command is mkdir -p … && cat > ~/.three-ws/tty-avatar/event.json. It is not a Node process, so it adds nothing measurable to a tool call; the viewer polls the file and does the mapping. tty-avatar install-hooks without --write prints the JSON fragment instead, and --json prints just the hooks object for another tool to merge.

Any other runtime can drive it the same way: write a Claude-Code-shaped payload to event.json, or call tty-avatar mood / tty-avatar say from a script.

Snapshot

tty-avatar snapshot ./hero.glb --mode braille --columns 80 --rows 40 --yaw 30
tty-avatar snapshot 81a076b6-55ff-49a2-b007-1d88e7dce2aa --plain > avatar.txt

One frame, then exit. --mood and --yaw/--pitch pose it.

Library

import { resolveSource, parseGlb, TtyAvatar, snapshot } from '@three-ws/tty-avatar';

const { bytes, name } = await resolveSource('81a076b6-55ff-49a2-b007-1d88e7dce2aa');
const mesh = await parseGlb(bytes);

// A viewer that owns the terminal until stop():
const viewer = new TtyAvatar(mesh, { name, mode: 'blocks', fps: 24 });
viewer.on('mood', ({ mood, say }) => console.error(mood, say));
setTimeout(() => viewer.setMood('happy', { say: 'tests green', ttlMs: 3000 }), 2000);
await viewer.start();

// Or one frame as a string, no terminal involved:
console.log(snapshot(mesh, { mode: 'ascii', columns: 60, rows: 30, yaw: 0.5 }));

Exports:

| Export | What | |---|---| | resolveSource(input, { origin }) | file path, URL, avatar id, agent:<id>, or three.ws page URL → { bytes, name, source, url, page } | | parseGlb(bytes, { maxTriangles }), loadGlbFile(path) | GLB → { positions, normals, tints, count, bounds } (unit sphere, Y-up, node transforms baked, meshopt and Draco decoded) | | createFrame(w, h), render(mesh, frame, pose, camera) | the rasterizer: z-buffered scanline fill, back-face culling, key + fill + rim lighting | | encode(frame, { mode }), encodeBlocks, encodeBraille, encodeAscii, stripAnsi, MODES | frame → lines | | MOODS, MOOD_NAMES, isMood, poseAt(current, previous, now) | motion functions and the cross-fade between them | | TtyAvatar | the frame loop: start({ frames }), stop(), setMood(name, { say, ttlMs }), setCaption(text), renderLines(), events frame, mood, stop | | snapshot(mesh, opts) | one frame as a string | | writeState, writeEvent, pollState, moodForHookEvent, defaultStateDir, statePaths | the file bridge | | claudeHooksConfig(dir), installClaudeHooks({ settingsPath, dir }), hookCommand(dir) | Claude Code wiring |

How it draws

The terminal is the framebuffer. Each character cell is split into subpixels (1x2 for half-blocks, 2x4 for braille), the mesh is projected with a perspective camera onto that grid, and a z-buffered scanline fill writes one lit colour per subpixel. Shading is per face: a key light, a fill light, an ambient floor, and a rim term so silhouettes stay readable on dark and light backgrounds. Colour comes from each primitive's material baseColorFactor (and COLOR_0 when present); textures are not sampled, because a cell is far coarser than a texel and a flat tint under lighting reads better at 80 columns.

Half-block mode packs two colours into one cell (foreground on ▀, background behind it), so a 100x40 terminal is a 100x80 colour image. Braille mode packs eight coverage bits per cell with one colour, so the same terminal is a 200x160 monochrome-per-cell image.

Tests

npm test

Builds a real GLB in memory with @gltf-transform/core, runs it through the loader, rasterizer, every encoder, the mood blender, the state bridge, the hook installer, and the CLI end to end.

Links

• Docs: https://three.ws/docs/tty-avatar
• Pick an avatar: https://three.ws/gallery (every avatar page's Embed tab has the npx line)
• Source: https://github.com/nirholas/three.ws/tree/main/packages/tty-avatar

Apache-2.0.