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.
Contributing to three.ws
Thanks for your interest in contributing! This guide covers everything you need to get started.
Community
| Where | For what |
|---|---|
| GitHub Discussions | Design questions, ideas, show and tell |
| Telegram community | Real-time chat and quick help |
| X community | Demos and avatars people built |
| IBM Community group | Enterprise and integration discussion |
| Release channel | Every user-visible change, pushed on deploy |
Full list with guidance on which room fits which question: docs/community.md.
New here? Your first contribution takes you from clone to open pull request in about 15 minutes, with a complete worked example. How we sort and respond to incoming work, including our response targets, is documented in Triage.
Quick Start
git clone https://github.com/nirholas/three.ws.git
cd three.ws
npm install
npm run setup
npm run dev
Open http://localhost:3000 and verify the default model loads.
npm run setup finishes what npm install can't: it builds the local
solana-agent-sdk (linked as a file: dependency, ships no prebuilt dist/)
and generates the gitignored data/_generated/* artifacts that the app,
sitemap, and test suite read. It also installs the repo's pre-push hook into
.git/hooks, which checks the commits you are pushing (and only those) against
the hard rules in CLAUDE.md and refuses to push credential material or a
generic commit subject. It is idempotent: re-running it skips anything already
up to date.
How to Contribute
Report a Bug
- Check existing issues to avoid duplicates
- Open a new issue with:
- Browser and OS
- Steps to reproduce
- Expected vs. actual behavior
- Console errors (if any)
- The model file (if possible) or a link to a public glTF sample that triggers the issue
Suggest a Feature
Open an issue with the Feature Request label. Describe:
- The use case (what problem does it solve?)
- Proposed behavior
- Any UI mockups or examples from other tools
Submit a Pull Request
- Fork the repository
- Create a feature branch from
main:git checkout -b feat/my-feature - Make your changes
- Format your code:
npx prettier --write . - Test locally with
npm run dev - Commit with a clear message:
git commit -m "feat: add opacity slider to display controls" - Push and open a PR against
main
Commit Messages
Use clear, descriptive commit messages. Conventional format is preferred:
| Prefix | Use |
|---|---|
feat: |
New feature |
fix: |
Bug fix |
docs: |
Documentation only |
style: |
Formatting, no logic change |
refactor: |
Code restructuring |
perf: |
Performance improvement |
chore: |
Build, tooling, dependency updates |
Code Guidelines
- Formatting: Run
npx prettier --write .before committing - No new dependencies without discussion — keep the bundle small
- Browser compatibility: Must work in Chrome, Firefox, and Edge. Safari support is best-effort
- Keep viewer/UI code client-side — the frontend viewer must run entirely in the browser; server logic belongs in the
api/handlers (served in production by the Cloud Run container inserver/), never bundled into the browser app - Dispose resources — any new Three.js objects (geometries, materials, textures) must be disposed in
Viewer.clear() - Blob URL cleanup — any
URL.createObjectURL()must have a correspondingURL.revokeObjectURL()
Project Structure
src/
├── app.js # App controller (touch this for new URL params or dropzone changes)
├── viewer.js # 3D renderer (touch this for scene, GUI, or display changes)
├── validator.js # glTF validation (touch this for validation pipeline changes)
├── environments.js # Environment map list (touch this to add HDR maps)
└── components/ # vhtml JSX components (string-based, no virtual DOM)
See docs/architecture.md for a deep dive.
Testing Your Changes
Automated tests
npm run typecheck # tsc over the @ts-check'd files — also gates every deploy
npm run test:core # vitest unit suite
npm test # vitest + playwright e2e
npm run audit:docs # documentation integrity: dead links, dead routes, dead scripts
If unit tests fail on a fresh clone with module-resolution or missing-file
errors, run npm run setup first.
audit:docs is the guard against documentation rot. It walks every Markdown
file in the repo and reports four things: relative links that point at files
which do not exist, site links (/create, /docs/x) that match no route in
data/pages.json, vercel.json, pages/, or public/, commands naming an
npm script or scripts/*.mjs file that is gone, and packages/* or workers/*
directories missing a README. Run it after any change that renames, moves, or
deletes a file, and after adding docs. Fenced code blocks, inline code spans,
external URLs, generated aggregates, and the internal work-order packs under
prompts/ and tasks/ are excluded by design; pass an explicit path to audit
one of those anyway. Add --advisory to report without a non-zero exit.
It also runs inside npm run gate alongside the other audits, and the tree is
currently clean, so anything it reports is something your change introduced. It
is deliberately kept off the deploy path so documentation rot can never block an
urgent production fix.
Manual Testing Checklist
Before submitting a PR, verify:
- Default model (
cz.glb) loads on page open - Drag-and-drop works with a
.glbfile - Drag-and-drop works with a multi-file
.gltf(separate.bin+ textures) - URL loading works:
http://localhost:3000/#model=<url> - All GUI controls respond (display, lighting, animation if applicable)
- Validation toggle appears and clicking it opens a report
- Responsive layout works on a narrow viewport (≤ 700 px)
- No console errors after loading a model
-
window.VIEWERdebugging API still works
Test Models
Use the Khronos glTF Sample Assets:
| Model | Tests |
|---|---|
| Damaged Helmet | PBR materials, environment mapping |
| Fox | Skinned mesh, animation |
| Flight Helmet | Multi-texture, display controls |
| Box | Minimal model, basic rendering |
| Animated Cube | Animation playback |
Areas for Contribution
Looking for something to work on? Here are areas that welcome contributions:
Start here: good first issue is curated, not a dumping ground. Every issue on that list names the file to change and the command that proves the change worked. Comment on one to claim it.
The areas that most need help:
- Rig support: teach
src/glb-canonicalize.jsa bone-naming convention it does not know yet, so more uploaded avatars animate instead of falling back to a default body. The single highest-leverage self-contained change in the repo. Walked through step by step in Your first contribution. - Animation quality: new clips for the shared library, or better retargeting in
src/animation-retarget.js - Bug fixes — check the issues page
- New environment maps — add more HDR options
- Accessibility — improve keyboard navigation and screen reader support
- Performance — reduce re-renders, optimize disposal, add lazy loading
- Safari fixes — improve drag-and-drop compatibility
- Documentation — improve guides, add tutorials, fix typos
License
By contributing, you agree that your contributions will be licensed under the Apache License 2.0.