Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

10.3 KB
Raw Blame

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 to permissions.additionalDirectories in ~/.claude/settings.json, whether or not Claude Code is installed;
  • links an img2 command into ~/.local/bin, /opt/homebrew/bin or /usr/local/bin, whichever is on your PATH and writable. Other PATH folders are not used. If none qualifies it prints No writable launcher directory on PATH; use npx instead, and you keep using the npx form (or alias 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.