Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
Install img2threejs
One command installs the skill into every supported coding agent on your machine. Plugins are optional and only needed for specific domains, for example CS2 skins.
You need Node.js ≥ 18, Git, and Python ≥ 3.10, plus one of: Claude Code, Codex, OpenCode, Hermes. Other agents: §7.
Paste this to your agent
If you would rather let your coding agent do it, paste:
Install the img2threejs skill for me, following
https://github.com/img2threejs/img2threejs/blob/main/docs/INSTALL.md
1. Run `npx --yes img2threejs@latest install`, then `npx --yes img2threejs@latest doctor`.
Always use the npx form, never a bare `img2threejs` command.
Exit 2 means an existing skill is in the way: show me the path and stop.
2. If ~/.hermes exists, run the Hermes step in §1.
3. Install the plugin harness only if I asked for something a plugin provides (§3; `img2 plugins` lists them).
4. Re-running any step is safe. Do not edit dotfiles by hand.
5. Tell me which agents were linked and that I must restart them.
1. Install the skill
npx --yes img2threejs@latest install # links the skill into every agent it finds
npx --yes img2threejs@latest doctor # one line per agent: "managed" means installed
Expected output of install (one ✓ line per agent found):
→ install skill img2threejs/img2threejs @ v2.0.0 into: hermes, claude
✓ hermes: ~/.hermes/skills/img2threejs → ~/.img2threejs/releases/<sha>/img2threejs (2.0.0, <sha>)
✓ claude: ~/.claude/skills/img2threejs → ~/.img2threejs/releases/<sha>/img2threejs (2.0.0, <sha>)
An agent is found when its folder exists: ~/.claude, ~/.codex, ~/.config/opencode
(or $XDG_CONFIG_HOME/opencode), ~/.hermes. Install into one only with --host claude
(or codex, opencode, hermes). Preview without changing anything with --dry-run.
Hermes only — one more line. Hermes loads skills per profile, and the installer only writes
~/.hermes/skills/. Link the skill into the profile you use (default img2threejs):
ln -sfn ~/.hermes/skills/img2threejs ~/.hermes/profiles/${HERMES_ACTIVE_PROFILE:-img2threejs}/skills/img2threejs
Use ln -sfn, not ln -s: running ln -s a second time on an existing directory link silently
creates a stray link inside the skill checkout. Repeat the line for each profile that should see
the skill. Without it, Hermes reports "Unknown skill".
2. Restart your agent and try it
Restart the agent (or start a new session) so it loads the skill. Then, with an image in your project:
| Agent | Type |
|---|---|
| Claude Code | /img2threejs Rebuild the object in ./reference.png as a procedural Three.js model. |
| Codex, OpenCode, Hermes | Use the img2threejs skill to rebuild the object in ./reference.png as a procedural Three.js model. |
That is all a generic object needs. More prompts: README §4.
3. Add a plugin (only if you need one)
Plugins come from a second, separate CLI, the img2 harness. Install it once, then add plugins
by id (list them with img2 plugins; harness 0.4.0 or newer):
npx --yes @img2threejs/img2@latest install --yes # once per machine: creates ~/.img2
npx --yes @img2threejs/img2@latest add cs2 --yes # example id; `img2 plugins` lists all
npx --yes @img2threejs/img2@latest list # the plugin must be listed here
Then restart the agent. add before install fails with no harness checkout at …/harness / run `img2 install` first.
What install changes on your machine:
- creates
~/.img2(or$IMG2_HOME) with the harness checkout and plugin registry; - if
~/.claude/exists, adds that folder topermissions.additionalDirectoriesin~/.claude/settings.json, whether or not Claude Code is installed; - links an
img2command into~/.local/bin,/opt/homebrew/binor/usr/local/bin, whichever is on yourPATHand writable. OtherPATHfolders are not used. If none qualifies it printsNo writable launcher directory on PATH; use npx instead, and you keep using thenpxform (oralias img2='npx --yes @img2threejs/img2@latest').
add links the plugin as a skill (img2-<id>) for Claude Code, Codex and OpenCode. Hermes
needs it by hand, per plugin:
ln -sfn "${IMG2_HOME:-$HOME/.img2}/plugins/cs2" ~/.hermes/profiles/${HERMES_ACTIVE_PROFILE:-img2threejs}/skills/img2-cs2
The environment plugin is private: it needs a GitHub account with access to its repository.
Why a run cannot see an installed plugin, and how plugins reach the pipeline:
PLUGINS.md.
4. Update and uninstall
npx --yes img2threejs@latest update # newest pinned release of the skill
npx --yes img2threejs@latest update --ref v2.0.0 # a specific tag or full 40-char SHA
img2 update --check # exits 1 when a plugin update is pending
img2 update cs2
img2 remove cs2 # unlinks it and moves its checkout to ~/.img2/backups
update never downgrades. --ref takes a vX.Y.Z tag or a 40-character SHA; branches and short
SHAs are refused.
There is no uninstall command for the skill. Delete each agent's img2threejs link (the paths in
doctor output, plus any Hermes profile link), then ~/.img2threejs/. For the harness, img2 remove
each plugin, then delete ~/.img2 and the img2 launcher.
5. Manual install (no CLI)
Keep one checkout and symlink it into each agent, so copies cannot drift. Use either this or the CLI for a given path, not both: the CLI refuses (exit 2) to replace a link it did not create.
git clone https://github.com/img2threejs/img2threejs.git ~/src/img2threejs
ln -sfn ~/src/img2threejs ~/.claude/skills/img2threejs
ln -sfn ~/src/img2threejs ~/.codex/skills/img2threejs
ln -sfn ~/src/img2threejs ~/.config/opencode/skills/img2threejs
ln -sfn ~/src/img2threejs ~/.hermes/profiles/${HERMES_ACTIVE_PROFILE:-img2threejs}/skills/img2threejs
ln -sfn ~/src/img2threejs ~/.hermes/skills/img2threejs # only so `doctor` sees Hermes
Create the parent skills/ folder first if it does not exist. A clone follows the default
branch; the CLI pins a release.
6. When something is off
| Symptom | Cause | Fix |
|---|---|---|
img2threejs: command not found or img2: command not found |
not installed globally (expected) | use the npx --yes …@latest form shown above |
img2threejs starts something else (e.g. Hermes) |
another program owns that name on your PATH |
use the npx form; check which img2threejs |
An agent is missing from the install plan |
its folder does not exist yet | run that agent once, or pass --host <name> |
error (2): refusing to replace an unmanaged skill at <path> |
a manual install or other link is already there | keep it, or move that path away and re-run |
error (2): ref must be a vX.Y.Z tag or 40-char SHA |
--ref got a branch or short SHA |
pass a tag or the full SHA |
| Slash command or skill not found after install | the agent was not restarted | restart it / open a new session |
| Hermes says "Unknown skill" | no link in the profile folder | the Hermes line in §1 |
doctor shows hermes … (no link) though Hermes works |
doctor checks only ~/.hermes/skills/ |
link that path too, or ignore |
| A plugin is installed but the run does not offer its profile | it is registered in a different $IMG2_HOME |
PLUGINS.md |
~/.claude/settings.json changed after img2 install |
~/.claude/ exists (see §3) |
expected; back the file up first if you want to restore it |
git ls-remote … failed / could not read Username for 'https://github.com' |
private plugin, no GitHub access | sign in with an account that has access and configure Git credentials |
Neither doctor proves the result looks right; that is what the reconstruction's own render
gates check.
7. Other coding agents
The installer knows four agents. Others can load the skill by hand: clone it (§5) and link or reference it where the agent reads skills or instructions. The paths below come from each vendor's documentation and have not been tested with img2threejs; check the vendor's docs if one does not work, and tell us so we can fix the row.
| Agent | Where it reads skills / instructions | Note |
|---|---|---|
| Cursor | .cursor/skills/<name>/SKILL.md, ~/.cursor/skills/ |
rules use .cursor/rules/*.mdc |
| JetBrains Junie | .junie/skills/<name>/SKILL.md, ~/.junie/skills/ |
prefers .junie/AGENTS.md |
| Kiro | .kiro/skills/<name>/SKILL.md, ~/.kiro/skills/ |
steering in .kiro/steering/*.md |
| Pi | ~/.pi/skills/<name>/SKILL.md |
also reads root AGENTS.md |
| Droid (Factory) | ~/.factory/skills/ |
|
| Crush | ./.crush/skills/, ~/.config/crush/skills/ |
|
| Warp | scans .agents/, .warp/, .claude/, .codex/ |
a Claude/Codex link may be enough |
| Aider | root AGENTS.md / CONVENTIONS.md |
add the file to read: in .aider.conf.yml |
| Mistral Vibe, Amp, Auggie, Zed | root AGENTS.md |
point it at the checkout's SKILL.md |
| Trae | AGENTS.md (enable in Settings → Rules & Memories) |
|
| Windsurf | .windsurf/rules/*.md |
|
| Continue | .continue/rules/*.md |
CLI is cn |
Plugins (img2 add) are linked only for Claude Code, Codex and OpenCode. In any other agent, have
it read the plugin's SKILL.md from ~/.img2/plugins/<id>/.
Reference: the two CLIs
| Skill CLI | Plugin harness CLI | |
|---|---|---|
| npm package | img2threejs |
@img2threejs/img2 |
| Installs | this skill into agents | plugins (domain steps, gates, output targets) |
| Agents it links | hermes, claude, codex, opencode | claude, codex, opencode |
| Version check | npx --yes img2threejs@latest --version (plain text) |
npx --yes @img2threejs/img2@latest --version --json (JSON) |
Installing one does not install the other, and neither generates a model: the agent does that
when you ask it to. The first --yes in every command belongs to npx (allow the package
download); a trailing --yes on img2 skips its confirmation prompt. Neither overwrites anything.
Skill checkouts live in ~/.img2threejs/releases/<sha>/img2threejs, shared by every agent on the
same release. To test the CLI from a clone: node bin/img2threejs.mjs install --dry-run; packaging
checks are in CONTRIBUTING.md.