Skip to main content
Glama

three.js ships a release almost every month and removes old APIs. Coding agents learned it from years of code that used THREE.Geometry, outputEncoding, three/examples/js and import paths that no longer exist, and they cannot see the canvas they draw on. Threesmith is the check between the agent and your project: the API of the three version you have installed, a scored review, the assets and decoders the code needs, the live scene in headless Chromium, and safe, undoable edits. Everything runs locally; nothing leaves the machine.

Without and with

Your agent...

On its own

With Threesmith

writes three.js

Geometry, outputEncoding, BoxBufferGeometry, examples/js: old habits

98 rules pinned to the installed release flag each line with the fix; fix does the 23 pure renames

calls an API

guesses a name or an import path from memory

three_api reads node_modules/three: signature, deprecation and the right three/addons/... path

writes a shader

#include <encodings_fragment>, gl_FragColor with GLSL3, a .replace() on a chunk that is gone

includes checked against the installed ShaderChunk, patches that silently do nothing found, renames fixed

loads a model

/models/Car.glb that is a 404 on Linux, Draco without a decoder

three_assets resolves every path like the server does and names the missing decoder setup

says "it works"

never opened the page

three_check opens it headless: errors with causes, blank frames, a screenshot, baselines

gets a black screen

guesses: more light? move the camera?

three_inspect reads the live scene and says why each object is not visible

fixes a bug

cannot show it was there, or that it is gone

three_play runs steps and judges claims frame by frame; three_scenario keeps it as a regression test

makes it fast

changes things and hopes

three_perf counts draw calls, triangles and programs against a budget and the last run; three_leaks names what is never disposed

ships it

builds once, deploys, sees a 404

three_build builds, finds two copies of three, missing assets and sub-path URLs, then opens the built page

needs a 3D model

needs Blender or a placeholder cube

three_model_build makes a clean .glb from one of 110 kinds, then shows it as text views and lints it

does not know the project

reads twenty files

three_scan and three_doctor give the map and the order to fix things in one call

Related MCP server: threejs-devtools-mcp

Quickstart

1. See what is wrong. Nothing to install but the package:

npx -y threesmith doctor          # what is wrong, grouped by cause, most urgent first, with next steps
npx -y threesmith review          # score 0-100, `file:line severity [rule] message Fix: ...`
npx -y threesmith check .         # open the page headless, errors and a screenshot

2. Give it to your agent. In Claude Code:

/plugin marketplace add laaielichter/Threesmith
/plugin install threesmith@threesmith

3. Ask for something. "Find out why the scene is black and fix it." Every three.js file Claude edits is reviewed right after the edit, its errors and broken asset paths go straight back to Claude, and the session starts with a brief of the project.

Install in your agent

Client

How

Claude Code

/plugin install threesmith@threesmith after /plugin marketplace add laaielichter/Threesmith (MCP server, hooks incl. protected paths, 8 skills, 2 subagents, settings for tool sets and read-only)

Claude Code, MCP only

claude mcp add threesmith -- npx -y threesmith mcp

Codex

codex mcp add threesmith -- npx -y threesmith mcp --tier premium

Cursor, VS Code

the buttons at the top

Gemini CLI

gemini extensions install https://github.com/laaielichter/Threesmith

Cline and others

llms-install.md, or { "mcpServers": { "threesmith": { "command": "npx", "args": ["-y", "threesmith", "mcp"] } } }

Docker

Dockerfile

Run the agent from the project folder, or pass --project <path>. Needs Node.js 22.12+ and three installed in the project. The browser tools need playwright-core and a Chromium (npx playwright-core install chromium); threesmith doctor --env shows what is missing.

Made for agents: cheap calls, exact answers

  • Two profiles. --tier cheap (the default) gives short, capped output and numbered step-by-step instructions, so small models follow the right order; --tier premium gives full detail for large models.

  • Tool sets. --tools core loads 14 tools; add run, live, build, model when you need them, or name single tools. A tool list the client pays for in every turn stays small. The server instructions only ever name tools that are loaded.

  • Fix loops that cost less. three_review with only_new: true shows new findings in full, the ones the agent already saw as one short line, and how many are fixed. code + file reviews code before it is saved.

  • Structured results. Review, check and doctor return structuredContent with an output schema next to the text.

  • One line per finding. file:line severity [rule] message Fix: ..., the same in the CLI (--compact), MCP and hooks.

  • Safe writes. Every write (fix, model build, scenario save) is one journal entry that three_undo takes back; a file changed by hand since is left alone. "protect" in threesmith.json (or THREESMITH_PROTECT) names folders no write may touch. --read-only leaves out the tools that always write and refuses write options.

  • It learns, locally. A finding marked as a false alarm with three_feedback is hidden from then on; lessons kept with three_lesson_add come back under the same error. Only hashes, counters and scrubbed text, on this machine.

The 31 tools

Set

Tool

What it does

core

three_doctor

Start here when something is broken: versions and imports, why the scene shows nothing, assets that will not load, removed APIs, colour, performance and cleanup, grouped by cause, most urgent first, with what three_fix does and numbered next steps

core

three_scan

Map the project: bundler and framework, three vs @types/three vs package.json, the libraries around it, pages and import maps, every file that uses three with what it creates and where its loop is, renderer settings, assets

core

three_api

Exact API of a class, member or constant in the installed three: signature, deprecation, import path; did-you-mean for unknown names

core

three_search

Find classes, constants and members by part of a name

core

three_review

Scored review (0-100) with 98 rules pinned to the installed release; code + file for unsaved code, only_new in a fix loop, files to focus

core

three_types

The project's own tsc --noEmit, with each three.js type error answered from the installed release (the member that exists, the real import path)

core

three_fix

The renames that mean exactly the same, dry run first, undoable

core

three_explain

Cause and fix of a console, build or test message (35 kinds), with the right import path for the installed release

core

three_lessons

100 lessons from real three.js and react-three-fiber projects (symptom, cause, fix, test) by error message, words, rule or topic

core

three_lesson_add

Keep a lesson learned here, scrubbed of names, paths and code; it comes back under the same error

core

three_rules

Every review rule with its category, release gating and fix

core

three_feedback

Mark a finding as a false alarm (hidden from then on) or right

core

three_undo

Undo the last Threesmith writes, newest first

core

three_version

Which three release is installed

run

three_check

Headless Chromium (software WebGL 2): console and page errors with causes, shader errors at your file and line, failed requests, no context, lost context, blank frames, screenshot, baselines with a diff, interaction steps

run

three_inspect

The live scene graph, camera, draw calls, GPU memory growth, and why each object is not visible

run

three_play

Steps (click, press, hold, drag, wheel, frames, eval, until), watched values per frame and step, claims judged at the end, any moment or every frame

run

three_scenario

Keep a passing play run as a regression test in .threesmith/scenarios/; ci runs them and writes JUnit

run

three_perf

Draw calls, triangles, programs, geometries, textures (exact) and frame-time percentiles with the slowest frames and their cause, against a budget and the last run

run

three_leaks

Repeat a cycle of steps with garbage collection and report what grows per cycle, down to the GPU resources never disposed, by type

live

three_session

Keep a headless page open between calls (start, status, stop)

live

three_page

Drive that page without reloading: eval JS against the live scene, steps, frames, until, screenshot, inspect, reload, new errors after every answer

build

three_assets

Every asset path resolved like the dev server and a static host: missing files, wrong capitals, decoder folders, glTF decoders the code never sets up, huge textures, unused files

build

three_build

Run the build, check the output (copies of three, missing assets, sub-path URLs, decoders) and open the built page headless

model

three_model_brief

One page before you build a model: the nearest ready-made kind, parts, real size, rules, the order of tools

model

three_model_identify

What a thing is (English or Dutch): parts, pivots, typical size, variants, usual mistakes

model

three_model_spec

The JSON model spec, an example, and the 110 ready-made kinds

model

three_model_build

Build a clean, deterministic .glb from a kind or a spec, and lint it

model

three_model_view

A .glb as text: front, side and top views, parts with sizes, parts that do not touch

model

three_model_lint

Score a .glb for the web (geometry, materials, triangles, draw calls, texture memory, loading), and against what it should be

model

three_model_inspect

What is in a .glb and which loaders and decoders three.js needs, with the setup code, checked against the project's code

CLI: threesmith doctor | scan | api | search | review | types | fix | rules | undo | lessons | assets | check | inspect | play | scenario | perf | leaks | build | model <inspect|needs|view|lint|identify|brief|spec|kinds|recipes|build> | explain | ci | hook | mcp. threesmith <command> --help lists the options.

The review

Rules are pinned to the installed release: a removed API is an error on a release that removed it and a warning on an older one; a rule whose replacement does not exist yet in your release stays quiet. The categories:

  • api (28): removed or renamed APIs and their releases, symbols that do not exist in the installed version, TSL names imported from the wrong entry, three/src imports, deprecations read from three's own source.

  • correctness (48): code that renders nothing or the wrong thing — no lights, shadows off, renderer never attached, render(camera, scene), scene.add(gltf), a mixer never updated, getElapsedTime() and getDelta() on one clock, instance and attribute updates without needsUpdate, raycasting with window instead of canvas coordinates, controls bound to document, decoders created but never attached; shaders: #include chunks that do not exist in the installed release, onBeforeCompile patches that do nothing, GLSL3 mistakes, redeclared built-ins, uniforms without { value }, GLSL materials under WebGPU and node materials under WebGL; React Three Fiber: state set in useFrame, objects made in render.

  • performance (10): allocations and heavy objects per frame, scene traversal per frame, uncapped pixel ratio, huge shadow maps, many meshes that should be instanced.

  • lifecycle (3): no resize handling, removed objects never disposed, dispose() without super.dispose().

  • color (8): colour textures without colorSpace, colour management off, EffectComposer without OutputPass or with double gamma, envMapIntensity that has no effect.

It reads text, not types (three_types adds the type checker for TypeScript). The rules are tested against three's own examples and addons for false alarms. If a finding is wrong: three_feedback, --disable <rule>, or // threesmith-disable-next-line <rule> (also -disable-line, -disable-file); an issue with the snippet is the most useful bug report.

GitHub Action

- uses: laaielichter/Threesmith@main
  with:
    min-score: 85
    check: dist          # folder with the built index.html; omit to skip the browser
    baseline: home       # screenshot baseline in .threesmith/baselines/home.png
    comment: true        # post the receipt on the pull request

The receipt (review, check, scenarios) appears in the job summary and optionally as a PR comment. Locally or in any CI: threesmith ci --check dist --junit junit.xml --sarif threesmith.sarif. Commit .threesmith/baselines/ and .threesmith/scenarios/; the rest of .threesmith/ is local state and ignored by its own .gitignore.

Limits

  • WebGL 2 in headless Chromium works in GitHub Actions (SwiftShader software rendering). WebGPU is best effort (--webgpu), depending on the runner having an adapter.

  • Frame times come from software rendering: compare them before and after on the same machine. Draw calls, triangles, programs and resource counts are exact.

  • Baselines should be made in the environment that checks them (CI), with the default tolerance.

  • The API lookup parses the JSDoc in three/src; it is tested on r187, older releases give thinner answers.

  • The review is heuristic; the asset check follows paths written as text, not paths built at run time.

Benchmarks

bench/ has tasks and a deterministic grader for comparing an agent with and without Threesmith. No results are published yet; see bench/README.md for the method.

Sister tools

From the same author, local and open source: ReversePort (reverse engineer and port games between engines), Godotwright (check the Godot code your agent writes), Stashpad (agent memory you can trust) and agentdisk (clean up after agents).

Support the project

If Threesmith is useful to you, a ⭐ on GitHub helps other people find it.

Thanks to everyone who has contributed: @chiragjangiir, @timmiballz22 and @IG-ABHINAV.

Develop

npm ci
npm run check     # typecheck, tests (incl. headless Chromium), build

Try the Claude Code plugin from this checkout, before a release: npm run build && npm run plugin:local, then start Claude Code with the claude --plugin-dir ... line it prints.

See AGENTS.md and CONTRIBUTING.md. Threesmith follows the design of its sister project for Godot, Godotwright. MIT licensed, made by laaielichter.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to inspect and edit live Three.js scenes — objects, materials, shaders, lighting, animation and performance — with zero project changes, previewing tweaks in the browser and converting them into ready-to-paste code. It also supports site performance audits, video frame capture, and Playwright/Puppeteer test integration.
      5,671 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to inspect and edit live Three.js scenes in the browser — objects, materials, shaders, textures, lights, animation, performance and memory — with 69 tools covering scene trees, screenshots, website audits and video frame capture. Changes can be previewed live with zero project modifications, then converted into ready-to-paste vanilla Three.js or React Three Fiber code.
      5,671 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to inspect and edit Three.js scenes, materials, shaders, lights, textures, animation, performance, and memory in real time, with live previews convertible into vanilla Three.js or React Three Fiber code. Also supports website audits, video frame capture, and Playwright/Puppeteer workflows.
      5,671 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to inspect live Three.js scenes in the browser, preview material, lighting, and camera changes without touching project files, and then write the approved tweaks back into source code. Its 69 tools also cover shaders, textures, animation, performance and memory debugging, website audits, and smooth frame capture for video clips.
      5,671 npm
      MIT