Skip to content

elithril/blender-kiln / plugin

Makes and fixes 3D assets in Blender, for games, the web and AR. Use when the user wants a 3D model, prop, character or GLB/glTF/FBX/USDZ file made — from a text brief, a reference image, a free marketplace (PolyHaven, Sketchfab) or AI generation — AND when they bring an existing 3D file to fix: too heavy or too many polygons (optimize, compress, LODs), broken normals, scale or origin, materials lost on glTF export, conversion between GLB, FBX and USDZ, texturing, rigging for animation, animating it (walk and idle cycles, text-to-motion, looping clips, articulated props), or inspection. Drives Blender through a Blender MCP server (ahujasid's or the official Blender Lab one). Batch mode produces many consistent assets unattended. Kiln Studio (`/kiln studio`) opens the project's models in the browser, where the user reviews them and pins notes for Claude to act on.

FileKindSize
.claude-plugin/plugin.jsonconfig1.2 KB
.mcp.jsonconfig236 B
LICENSEother1.0 KB
NOTICEother2.5 KB
SKILL.mdskill md29.0 KB
references/ai-generation.mdmarkdown21.0 KB
references/animation.mdmarkdown21.6 KB
references/batch-mode.mdmarkdown19.5 KB
references/blender-mcp.mdmarkdown9.4 KB
references/characters.mdmarkdown52.8 KB
references/cli-tools.mdmarkdown6.5 KB
references/commands.mdmarkdown10.7 KB
references/export-targets.mdmarkdown14.3 KB
references/log-format.mdmarkdown2.2 KB
references/naming-conventions.mdmarkdown5.8 KB
references/photo-projection.mdmarkdown6.3 KB
references/pipeline-brief.mdmarkdown4.2 KB
references/pipeline-import-cleanup.mdmarkdown6.3 KB
references/pipeline-optimize-export.mdmarkdown6.4 KB
references/pipeline-rig-animate.mdmarkdown5.8 KB
references/pipeline-source.mdmarkdown9.7 KB
references/print.mdmarkdown41.5 KB
references/reference-fidelity.mdmarkdown31.8 KB
references/review-rounds.mdmarkdown10.4 KB
references/setup-install.mdmarkdown2.8 KB
references/setup.mdmarkdown9.2 KB
references/sourcing-strategy.mdmarkdown6.1 KB
references/studio.mdmarkdown38.9 KB
references/texturing-strategy.mdmarkdown14.4 KB
references/topology-rules.mdmarkdown3.9 KB
references/uv-materials.mdmarkdown6.8 KB
references/validation-checklist.mdmarkdown10.5 KB
studio/approval_hook.pyscript14.2 KB
studio/blender_live.pyscript2.3 KB
studio/checks.pyscript38.1 KB
studio/estimate.pyscript4.2 KB
studio/example/barrel/barrel_final.glbbinary111.9 KB
studio/example/barrel/barrel_log.mdmarkdown445 B
studio/handoff.pyscript17.8 KB
studio/mcp_server.pyscript32.7 KB
studio/phoneshare.pyscript17.1 KB
studio/server.pyscript47.9 KB
studio/setup_status.pyscript7.5 KB
studio/static/app.jsscript241.4 KB
studio/static/apple-touch-icon.pngbinary20.6 KB
studio/static/fonts/OFL-JetBrainsMono.txtmarkdown4.3 KB
studio/static/fonts/OFL-Sora.txtmarkdown4.3 KB
studio/static/fonts/jetbrains-mono-latin-ext.woff2binary11.3 KB
studio/static/fonts/jetbrains-mono-latin.woff2binary30.6 KB
studio/static/fonts/sora-latin-ext.woff2binary11.8 KB
studio/static/fonts/sora-latin.woff2binary24.6 KB
studio/static/i18n.jsscript6.2 KB
studio/static/i18n/fr.jsonconfig101.2 KB
studio/static/icon-32.pngbinary2.6 KB
studio/static/icon-64.pngbinary6.6 KB
studio/static/icon-96.pngbinary12.8 KB
studio/static/index.htmlother39.5 KB
studio/static/style.cssother114.5 KB
studio/static/tutorial.jsscript49.0 KB
studio/static/tutorial/barrel_after.glbbinary117.3 KB
studio/static/tutorial/barrel_before.glbbinary111.9 KB
studio/static/tutorial/fixtures.jsonconfig13.5 KB
studio/static/tutorial/lantern_1_blockout.glbbinary83.1 KB
studio/static/tutorial/lantern_2_details.glbbinary101.8 KB
studio/static/tutorial/lantern_3_materials.glbbinary102.0 KB
studio/static/tutorial/lantern_4_final.glbbinary141.1 KB
studio/static/tutorial/make_tutorial.pyscript4.9 KB
studio/static/viewer.jsscript41.4 KB
studio/studio.pyscript29.2 KB
studio/studiolib.pyscript77.8 KB
studio/test_studio.pyscript90.2 KB
studio/test_worker.pyscript31.5 KB
studio/worker.pyscript56.8 KB
studio/worker_blender.pyscript2.7 KB
tools/autorig.pyscript44.1 KB
tools/bind_rigid_parts.pyscript3.6 KB
tools/blender_mcp_start.pyscript1.5 KB
tools/check_usdz.pyscript1004 B
tools/cutout.swiftscript2.0 KB
tools/export_outputs.pyscript5.2 KB
tools/fidelity_check.pyscript39.0 KB
tools/fit_coupon.pyscript11.3 KB
tools/fixtures/skintokens_raw_child.glbbinary88.8 KB
tools/fixtures/skintokens_skeletons.jsonconfig6.5 KB
tools/flatten.pyscript14.9 KB
tools/glb_to_fbx.pyscript2.1 KB
tools/glb_to_usdz.pyscript6.2 KB
tools/motion_loop.pyscript5.9 KB
tools/motion_measure.pyscript15.2 KB
tools/motions/LICENSE-image-to-3dlab.txtmarkdown11.1 KB
tools/motions/cheer.npzbinary48.4 KB
tools/motions/cheer_b.npzbinary48.1 KB
tools/motions/dance.npzbinary78.2 KB
tools/motions/dance_b.npzbinary78.9 KB
tools/motions/death.npzbinary45.9 KB
tools/motions/death_b.npzbinary46.5 KB
tools/motions/fight_stance.npzbinary60.3 KB
tools/motions/fight_stance_b.npzbinary61.3 KB
tools/motions/flying_kick.npzbinary39.7 KB
tools/motions/flying_kick_b.npzbinary39.9 KB
tools/motions/hit_react.npzbinary31.9 KB
tools/motions/hit_react_b.npzbinary31.8 KB
tools/motions/idle.npzbinary51.8 KB
tools/motions/idle_b.npzbinary57.7 KB
tools/motions/jump.npzbinary39.8 KB
tools/motions/jump_b.npzbinary39.9 KB
tools/motions/kata.npzbinary77.4 KB
tools/motions/kata_b.npzbinary75.3 KB
tools/motions/kick.npzbinary32.4 KB
tools/motions/kick_b.npzbinary32.5 KB
tools/motions/presets.jsonconfig9.6 KB
tools/motions/punch.npzbinary32.0 KB
tools/motions/punch_b.npzbinary32.1 KB
tools/motions/punch_combo.npzbinary47.4 KB
tools/motions/punch_combo_b.npzbinary47.5 KB
tools/motions/roll.npzbinary46.7 KB
tools/motions/roll_b.npzbinary47.5 KB
tools/motions/roundhouse.npzbinary39.7 KB
tools/motions/roundhouse_b.npzbinary39.9 KB
tools/motions/run.npzbinary47.2 KB
tools/motions/run_b.npzbinary47.7 KB
tools/motions/sit.npzbinary47.2 KB
tools/motions/sit_b.npzbinary47.2 KB
tools/motions/sneak.npzbinary61.6 KB
tools/motions/sneak_b.npzbinary61.8 KB
tools/motions/strafe_left.npzbinary45.9 KB
tools/motions/strafe_left_b.npzbinary47.1 KB
tools/motions/sword_swing.npzbinary39.7 KB
tools/motions/sword_swing_b.npzbinary39.4 KB
tools/motions/walk.npzbinary62.8 KB
tools/motions/walk_b.npzbinary62.6 KB
tools/motions/walk_woman.npzbinary62.9 KB
tools/motions/wave.npzbinary46.3 KB
tools/motions/wave_b.npzbinary46.3 KB
tools/open_blender.pyscript5.0 KB
tools/photo_project.pyscript37.8 KB
tools/presets.pyscript16.3 KB
tools/print_check.pyscript47.2 KB
tools/quadruped.pyscript19.4 KB
tools/retarget.pyscript46.9 KB
tools/review_renders.pyscript13.8 KB
tools/review_sheet.pyscript11.0 KB
tools/skintokens-requirements.txtmarkdown2.4 KB
tools/skintokens.patchother9.2 KB
tools/template_profile.pyscript5.8 KB
tools/test_autorig.pyscript15.9 KB
tools/test_fidelity_check.pyscript20.7 KB
tools/test_fit_coupon.pyscript6.4 KB
tools/test_flatten.pyscript15.0 KB
tools/test_open_blender.pyscript1.3 KB
tools/test_photo_project.pyscript12.6 KB
tools/test_presets.pyscript17.6 KB
tools/test_print_check.pyscript33.1 KB
tools/test_review_renders.pyscript11.4 KB
tools/test_review_sheet.pyscript4.0 KB
tools/test_template_profile.pyscript3.6 KB
tools/test_uv_check.pyscript5.0 KB
tools/test_verify_docs.pyexecutablescript7.9 KB
tools/unimate.patchother3.5 KB
tools/unimate.pyscript17.5 KB
tools/uv_check.pyscript8.4 KB
tools/verify_blender.pyexecutablescript29.2 KB
tools/verify_docs.pyexecutablescript16.6 KB

studio/approval_hook.py

View on GitHub
#!/usr/bin/env python3
"""PreToolUse hook for Kiln Studio's Claude worker: lets safe tool calls through and
defers the others, for the user to allow or deny in the Studio page.

Enabled only for the worker's runs (worker.py passes it through --settings); an ordinary
Claude Code session never loads it. It never waits for an answer: a hook that waits is
let through after its timeout, so it defers instead, the run ends with
stop_reason "tool_deferred", and the worker resumes the session once the user answered —
the same call then reaches this hook again and finds the answer in
$KILN_DECISIONS/<tool_use_id>.json.

Safe, allowed at once:
- reading (Read, Glob, Grep), the to-do list, skills, tool search;
- the worker's Blender (mcp__blender__*), except paid generation tools;
- the kiln-studio MCP tools;
- Edit / Write / NotebookEdit inside the project folder;
- Bash commands made only of the skill's own Python scripts and read-only commands
  (`sed -n` printing lines included), the skill's Swift scripts, `sips` reading a size or
  writing a copy in the project, `gltf-transform`'s optimisation steps on the project's files
  (never `optimize`), `cp` / `mv` / `ditto` into the project, and a background
  Blender running one of the skill's scripts.
Anything else is deferred (with KILN_APPROVALS=all: allowed, but for a write outside the
project, sudo or rm outside it; with KILN_APPROVALS=auto: left to Claude Code's auto mode, but
paid generation, which waits for the user unless KILN_PAID=auto). AskUserQuestion is denied with a reason:
nobody can answer it mid-run, the question goes in the message instead.

Standard library only. Also importable: classify() is what the tests exercise.
"""
from __future__ import annotations

import json
import os
import re
import shlex
import sys
from pathlib import Path

ALWAYS = {"Read", "Glob", "Grep", "TodoWrite", "Skill", "ToolSearch", "LS"}
EDITS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
READ_ONLY = {"ls", "cat", "head", "tail", "wc", "file", "stat", "grep", "rg", "echo", "pwd", "which",
             "du", "date", "sort", "uniq", "cut", "tr", "jq", "basename", "dirname", "realpath", "test",
             "true", "printf", "diff", "shasum", "md5", "sha256sum", "tree"}
# Blender MCP tools that can spend credits (rule 5): never automatic.
PAID = re.compile(r"^mcp__blender__(generate_|poll_|import_generated_asset)")
GLTF_TRANSFORM_STEPS = {"inspect", "validate", "draco", "meshopt", "webp", "ktx2", "resize", "dedup", "prune"}
HARMLESS_REDIRECTS = re.compile(r"\s*(?:2>&1|&>\s*/dev/null|[12]?>\s*/dev/null)")


def _inside(p: str, base: Path, cwd: Path) -> bool:
    try:
        q = Path(p).expanduser()
        q = (q if q.is_absolute() else cwd / q).resolve()
    except (OSError, RuntimeError, ValueError):
        return False
    return q == base or base in q.parents


def bash_safe(cmd: str, root: Path, plugin: Path) -> bool:
    """True when every part of the command is the skill's own script or a read-only command."""
    if any(x in cmd for x in ("`", "$", "<(", ">(", "<<")):
        return False
    cmd = HARMLESS_REDIRECTS.sub(" ", cmd)
    if ">" in cmd or "<" in cmd:
        return False
    cwd = root
    # Split into commands as the shell does: on ; && || | & and new lines, never inside quotes.
    try:
        lex = shlex.shlex(cmd.replace("\n", " ; "), posix=True, punctuation_chars=";&|")
        lex.whitespace_split = True
        tokens = list(lex)
    except ValueError:
        return False
    commands, cur = [], []
    for tok in tokens:
        if tok and set(tok) <= set(";&|"):
            commands.append(cur); cur = []
        else:
            cur.append(tok)
    commands.append(cur)
    for argv in commands:
        if not argv:
            continue
        name = os.path.basename(argv[0])
        if name == "cd":
            if len(argv) != 2 or not (_inside(argv[1], root, cwd) or _inside(argv[1], plugin, cwd)):
                return False
            cwd = Path(argv[1]) if Path(argv[1]).is_absolute() else (cwd / argv[1])
            continue
        if re.fullmatch(r"python3?(\.\d+)?", name) or argv[0] == sys.executable:
            if len(argv) < 2 or argv[1].startswith("-") or not argv[1].endswith(".py"):
                return False
            if not _inside(argv[1], plugin, cwd):
                return False
            continue
        if name == "find":
            if any(a in ("-exec", "-execdir", "-delete", "-ok", "-okdir", "-fprint", "-fprintf", "-fls") for a in argv):
                return False
            continue
        if name == "mkdir":
            if not all(_inside(a, root, cwd) for a in argv[1:] if not a.startswith("-")):
                return False
            continue
        if name == "sed":
            # Printing lines (-n), or editing files of the project in place (-i, like Edit there);
            # never a command that writes elsewhere or runs one (w, W, e).
            args = argv[1:]
            inplace = any(a.startswith(("-i", "--in-place")) for a in args)
            if not inplace and "-n" not in args:
                return False
            if any(re.search(r"(^|[;{}\s/\d$])[wWe](\s|$)", a) for a in args if not a.startswith("-")):
                return False
            if inplace:
                # BSD sed: -i '' then the script then the files; GNU: -i[SUFFIX].
                rest = [a for a in args if not a.startswith("-")]
                if args[args.index(next(a for a in args if a.startswith(("-i", "--in-place")))) + 1:][:1] == [""]:
                    rest = rest[1:] if rest and rest[0] == "" else rest
                files = [a for a in rest[1:] if a != ""]
                if not files or not all(_inside(f, root, cwd) for f in files):
                    return False
            continue
        if (name == "command" and argv[1:2] in (["-v"], ["-V"])) or name == "type" \
                or argv[1:] in (["--version"], ["-v"], ["-V"], ["version"]):
            continue   # which tools are installed, and their versions
        if name.lower() == "blender":
            # A background Blender running the skill's own script (fidelity_check, verify…).
            if not ({"-b", "--background"} & set(argv)) or any(a in ("--python-expr", "--python-console") for a in argv):
                return False
            scripts = [argv[k + 1] for k, a in enumerate(argv[:-1]) if a in ("--python", "-P")]
            if not scripts or not all(_inside(x, plugin, cwd) for x in scripts):
                return False
            continue
        if name == "swift":
            # The skill's own Swift scripts (cutout.swift), like its Python ones.
            if len(argv) < 2 or not argv[1].endswith(".swift") or not _inside(argv[1], plugin, cwd):
                return False
            continue
        if name in ("cp", "mv", "ditto"):
            # Copies and moves within the project (a source may also be the skill's own file).
            paths = [a for a in argv[1:] if not a.startswith("-")]
            if len(paths) < 2 or not _inside(paths[-1], root, cwd):
                return False
            if not all(_inside(a, root, cwd) or _inside(a, plugin, cwd) for a in paths[:-1]):
                return False
            continue
        if name == "gltf-transform":
            # The skill's own optimisation steps (cli-tools.md) on the project's files; never
            # `optimize`, whose simplify destroys geometry (rule 20). On 2026-10-21 a session
            # dropped this step for Blender's exporter only to avoid the approval.
            sub = next((a for a in argv[1:] if not a.startswith("-")), None)
            if sub not in GLTF_TRANSFORM_STEPS:
                return False
            files = [a for a in argv[2:] if re.search(r"\.(glb|gltf)$", a, re.I)]
            if not files or not all(_inside(f, root, cwd) for f in files):
                return False
            continue
        if name == "sips":
            # Reading an image's size, or writing a converted copy inside the project.
            if "--out" in argv or "-o" in argv:
                k = argv.index("--out") if "--out" in argv else argv.index("-o")
                if k + 1 >= len(argv) or not _inside(argv[k + 1], root, cwd):
                    return False
            elif any(a in ("-s", "--setProperty", "-r", "--rotate", "-f", "--flip", "-c", "-z", "-Z", "--resampleWidth",
                           "--resampleHeight", "--resampleHeightWidth", "--resampleHeightWidthMax", "--padToHeightWidth",
                           "--cropToHeightWidth", "-m", "--matchTo", "-e", "--embedProfile", "-d", "--deleteProperty") for a in argv):
                return False   # changes the file in place
            continue
        if name not in READ_ONLY:
            return False
    return True


def classify(tool: str, tool_input: dict, root: Path, plugin: Path) -> tuple[str, str]:
    """(decision, reason) before the user has said anything: allow, defer or deny."""
    if tool in ALWAYS or tool.startswith("mcp__kiln-studio__"):
        return "allow", "safe"
    if tool.startswith("mcp__blender__"):
        if PAID.match(tool):
            return "defer", "a generation tool that can spend credits"
        return "allow", "the worker's own Blender"
    if tool == "AskUserQuestion":
        return "deny", ("Nobody can answer a question mid-run here: the user reads your messages in Kiln "
                        "Studio. Put the question at the end of your message, on a line starting "
                        "KILN-PROPOSAL:, and end your turn.")
    if tool in EDITS:
        path = str(tool_input.get("file_path") or tool_input.get("notebook_path") or "")
        if path and _inside(path, root, root):
            return "allow", "inside the project"
        return "defer", "writes outside the project"
    if tool == "Bash":
        if bash_safe(str(tool_input.get("command", "")), root, plugin):
            return "allow", "the skill's scripts or a read-only command"
        return "defer", "a shell command outside the safe list"
    return "defer", f"{tool} is not on the safe list"


def outside(tool: str, tool_input: dict, root: Path) -> str:
    """What still waits for the user with allow all: a write outside the project, sudo, or rm of a
    path outside it. Empty when the call stays in the project's work."""
    if tool in EDITS:
        path = str(tool_input.get("file_path") or tool_input.get("notebook_path") or "")
        return "" if path and _inside(path, root, root) else "writes outside the project"
    if tool != "Bash":
        return ""
    cmd = str(tool_input.get("command", ""))
    try:
        lex = shlex.shlex(cmd.replace("\n", " ; "), posix=True, punctuation_chars=";&|")
        lex.whitespace_split = True
        tokens = list(lex)
    except ValueError:
        return "a shell command it cannot read"
    cwd, first = root, True
    for i, tok in enumerate(tokens):
        if set(tok) <= set(";&|"):
            first = True
            continue
        name = os.path.basename(tok) if first else None
        first = False
        if tok == "sudo":
            return "sudo"
        if name == "cd" and i + 1 < len(tokens):
            nxt = tokens[i + 1]
            cwd = Path(nxt) if Path(nxt).expanduser().is_absolute() else cwd / nxt
        if name in ("rm", "rmdir", "unlink"):
            args = []
            for t in tokens[i + 1:]:
                if set(t) <= set(";&|"):
                    break
                if not t.startswith("-"):
                    args.append(t)
            if not args or not all(_inside(a, root, cwd) for a in args):
                return "deletes outside the project"
    return ""


def decide(event: dict, env: dict) -> tuple[str, str]:
    root = Path(env.get("KILN_STUDIO_ROOT") or event.get("cwd") or ".").resolve()
    plugin = Path(env.get("KILN_PLUGIN_DIR") or Path(__file__).resolve().parent.parent).resolve()
    tool, tool_input = str(event.get("tool_name", "")), event.get("tool_input") or {}
    decision, reason = classify(tool, tool_input if isinstance(tool_input, dict) else {}, root, plugin)
    if decision == "defer" and PAID.match(tool) and env.get("KILN_PAID") == "auto":
        return "allow", "paid generation is set to auto in Kiln Studio"
    if decision == "defer" and env.get("KILN_APPROVALS") == "all" and not PAID.match(tool):
        # Allow all: whatever makes the model goes through; what leaves the project still waits.
        out = outside(tool, tool_input if isinstance(tool_input, dict) else {}, root)
        if not out:
            return "allow", "allow all is on in Kiln Studio"
        reason = out
    if decision == "defer" and env.get("KILN_APPROVALS") == "auto" and not PAID.match(tool):
        # Auto: Claude Code's auto mode decides the rest; only what can spend money waits here.
        return None, "auto mode decides"
    if decision == "defer" and env.get("KILN_DECISIONS"):
        tid = str(event.get("tool_use_id", ""))
        if re.fullmatch(r"[A-Za-z0-9_-]{1,100}", tid):
            p = Path(env["KILN_DECISIONS"]) / f"{tid}.json"
            if p.is_file():
                try:
                    ans = json.loads(p.read_text())
                except (OSError, ValueError):
                    ans = {}
                if ans.get("decision") == "allow":
                    return "allow", "the user allowed it in Kiln Studio"
                if ans.get("decision") == "deny":
                    return "deny", "The user denied this call in Kiln Studio" + (f": {ans['reason']}" if ans.get("reason") else ".")
    return decision, reason


def main() -> None:
    try:
        event = json.load(sys.stdin)
    except ValueError:
        sys.exit(0)   # no decision: dontAsk refuses whatever is not on --allowedTools
    decision, reason = decide(event, dict(os.environ))
    if decision is None:
        sys.exit(0)   # no decision: the permission mode's own
    log = os.environ.get("KILN_DECISIONS")
    if log:
        try:
            with open(Path(log) / "hook.log", "a") as f:
                f.write(json.dumps({"tool": event.get("tool_name"), "id": event.get("tool_use_id"),
                                    "decision": decision, "reason": reason}) + "\n")
        except OSError:
            pass
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse",
                                             "permissionDecision": decision,
                                             "permissionDecisionReason": reason}}))


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall