img2threejs turns one reference image into a TypeScript Three.js factory, and needs an agent host to do it

One reference image in, a THREE.Group factory out

The input is a single reference image of an object. The output is a THREE.Group factory written in TypeScript that recreates the object from primitives, procedural shaders and generated geometry. The project calls this reconstruction by code and sets it apart from photogrammetry, mesh extraction and downloaded art packs.

The factory carries a runtime hierarchy of pivots, sockets and colliders. That is what the project means by animation-ready: a door hinge or a character arm already has a pivot to rotate around, and a weapon has a socket to attach to, so the result can be animated without first being rigged by hand. The alternative it is avoiding is what the README calls an inert lump.

The gallery at img2threejs.io shows the format. Each entry links to a source file such as createMarsCatModel.ts or createStarshipSuperHeavyModel.ts in the img2threejs-showcase repository, and every model in that gallery is generated code running in the browser, with no mesh files and no downloads. Reading one of those files is the fastest way to see what you would get back from your own image.

The npm package installs a skill and does not reconstruct anything

The package.json at the repository root describes its own job plainly: install and update the img2threejs skill into agent hosts (Hermes, Claude Code, Codex, OpenCode). Its bin entry maps the img2threejs command to bin/img2threejs.mjs, and the files array ships only that one script. It requires Node 18 or newer through its engines field and is published publicly to the npm registry.

The consequence for a reader is that there is no standalone converter here. Running the img2threejs command does not take an image and emit TypeScript; it places the skill where an agent can load it, and the agent then does the reconstruction. If your plan was to wire image-to-3D into a build script or a server job without an agent in the loop, this repository does not give you that path.

The versions also diverge. The npm installer sits at 0.1.1 while the skill itself has GitHub releases up to v2.0.0. When filing a bug, name the skill release rather than the installer version, since the two numbers track different things. The package scripts are limited to a test run, node --test bin/img2threejs.mjs-test.mjs, and a packaging check, npm pack --dry-run.

The agent host supplies the eyes, so results depend on what it can see

img2threejs runs under Hermes, Claude Code, Codex or OpenCode and calls itself agent-agnostic. Wherever its docs say agent vision or agent browser tool, it uses whatever the host provides: native image reading, a browser MCP, the project preview, or a screenshot the user supplies.

This flexibility moves a real dependency onto you. The skill does not bring its own vision model or renderer. If your host cannot read images natively and has no browser tool attached, the fallback is you taking screenshots and handing them over, which turns a quality check into manual work. Comparing the rebuilt model against the reference is part of how the pipeline judges its own output, so a host with weak image reading weakens that comparison too.

The repository root includes SKILL.md, CLAUDE.md, a skills directory and an integrations directory, which is where host-specific wiring lives. Anyone evaluating it should check those files for their own host before assuming parity across all four, because the agent-agnostic claim describes how the skill asks for capabilities, not a promise that every host offers the same ones.

The detailInventory gate blocks code generation until every small detail is accounted for

Before any code is generated, the pipeline enumerates a detailInventory: the identity-defining small details of the subject. The listed categories are gloss, bevel or rounding, screws and rivets, engraved or painted linework, contours, and stains and wear. Each detail has to map to a real component or a material entry, and a strict-quality gate refuses to let generation start until the inventory is complete. The taxonomy lives in grimoire/intake/detail_inventory.md.

The benefit is that a rivet seen in the photo does not silently vanish from the model. The cost is friction. A blurry or low-resolution reference makes small details hard to enumerate, and the gate does not let the agent skip ahead to produce a rough draft first. Expect more back-and-forth on images where wear, linework or fasteners are ambiguous.

The gate also explains the project's token-efficient label. Spending effort on an explicit inventory up front is meant to avoid regenerating whole models after a missed feature shows up in review.

Objects, characters and hybrids take separate tracks

Every subject is classified as object, character or hybrid. Objects follow a hard-surface pipeline. Characters route through an anatomy-aware track that works with head-unit proportions, facial landmarks and pose, documented in grimoire/character/reconstruction.md.

The gallery mirrors that split. Entries such as the Ocean Blue PRS Guitar, the Starship and Super Heavy stack and the AWP Medusa rebuild are tagged object, while Groot, Mars Cat, Lee Sin and the Dual-Sword Warrior are tagged character. Release v1.5.2, published 2026-09-03, is titled Support VFX / Animation for character, and the Raz demo built with it links to a razVfx.ts source file rather than a model file.

There is also an opt-in projection-first path aimed at maximum likeness for a specific person or character, which fits a parametric template to image landmarks. Because it is opt-in, a default run on a portrait goes through the general character track. If likeness to one particular face matters, choose that path deliberately rather than expecting the default to reach it.

Code instead of meshes means some jobs are out of reach

Reconstruction by code is the whole point, and it rules out a set of uses. The result is a TypeScript factory built from primitives and procedural shaders. It is not a scanned mesh and not a photogrammetry capture, so the surface is whatever those primitives and shaders can express. A subject whose identity lives in irregular organic geometry has to be approximated by generated shapes, and the fidelity you get depends on how well the agent decomposes it.

The practical consequence lands in your pipeline. A team that expects a model file to drop into a content tool receives source code that must be compiled and run inside a Three.js scene. That suits a web project already written in TypeScript and is awkward for anything else. Release v1.5.1, published 2026-08-23, is titled add the GLB-reference route; the title describes a GLB used as reference input, not GLB as the output.

The gallery demos are the honest yardstick. Open one close to your subject, orbit it and read the source before committing to the approach.

Release cadence and the gallery's version tags

Three releases landed in a short span: v1.5.1 on 2026-08-23, v1.5.2 on 2026-09-03, and v2.0.0, titled The Plugin Update, on 2026-09-06. The last push to the main branch was on 2026-10-28, and the repository is not archived. It is licensed Apache-2.0.

The demo table in the README is not hand-maintained. It is generated from the gallery's demos.json by scripts/ci/showcase_table.py, and the Built with column shows the version tag in each demo's own generatedWith record. Several of the newest entries, including the Tropical Island diorama, the Man Robot studio and the Snowbound Crossing mini game, name no version at all, so you cannot tell from the table which release produced them. Older entries name versions as far back as v1.2.0 and v1.4.4.

That matters when you compare your own output with a demo. A model tagged v1.4.4 predates the character VFX work and the plugin release, so a mismatch between your result and an older showcase piece may come from the version gap rather than from your reference image. The gallery also holds work in progress beyond the finished demos listed.

Editorial conclusion

img2threejs suits developers who already work in Claude Code, Codex, OpenCode or Hermes and want an editable, animation-ready Three.js object written as TypeScript, not an asset file. It is the wrong tool for anyone who needs a scanned mesh, a photogrammetry result or a standalone command-line converter. Before adopting it, confirm that your agent host can read images or drive a browser, and open the generated source of a gallery demo close to your subject to judge whether primitives and procedural shaders reach the fidelity you need.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes