Blender Agent Studio

Build, inspect, rig, animate, simulate, render, and benchmark Blender work with reproducible Python,
explicit graybox-to-polish stages, fixed visual evidence, deterministic quality
gates, and a bounded local MCP. Finished assets default to a polished smooth
quality target unless low-poly is explicitly requested.

Blender Agent Studio packages one umbrella routing skill, eleven specialist
skills, and evaluation tools for turning a user request into inspectable
.blend and GLB deliverables. It is designed to answer a harder question than
“did Blender produce a file?”: does the result satisfy the request, survive
export, read correctly from every side, and improve when the agent workflow
changes?

Astra and adaptive presentation

Version 0.5.0 adds Astra-aware execution guidance, explicit model profiles,
and an adaptive studio presentation. Routine choices use stated defaults;
related build stages share review passes while final quality gates remain.

Evidence renders now scale light power with asset dimensions, reset inherited
lighting/exposure, and frame small props more closely. The default auto
presentation uses a material-color hint to select neutral, dark, or light studio
contrast. Review the hero image and override when the asset needs a different
look. Two presentation options are useful when they serve distinct needs.

The MCP accepts presentation: "auto" | "neutral" | "dark" | "light";
the rendering script accepts --presentation with the same options.
The benchmark pins neutral and records renderer version 2. Rerender old and
new candidates under matching settings before making visual comparison claims.

Use --profile astra, sol, terra, or luna to pin a benchmark model.
All profiles default to medium effort; --reasoning can explicitly override it.
Interactive model selection remains yours. This update has a real Blender
smoke test, but no paired Astra-versus-GPT-5.6 quality or speed claim.

Quick start

Install the complete Codex plugin from this GitHub marketplace:

codex plugin marketplace add ifBars/blender-agent-studio
codex plugin add blender-agent-studio@blender-agent-studio

Start a new Codex task, then ask:

Use $blender-agent-studio:blender-modeling-workflow and
$blender-agent-studio:blender-asset-validation to build a stylized,
game-ready coffee grinder as reproducible Python, .blend, and GLB files.

Add $blender-agent-studio:blender-animation-workflow when the asset has
articulated or animated parts.

Full Codex plugin

The marketplace install includes all eleven specialist skills, the Blender icon and plugin
metadata, and the bounded local MCP:

codex plugin marketplace add ifBars/blender-agent-studio
codex plugin add blender-agent-studio@blender-agent-studio

Update a GitHub-backed installation:

codex plugin marketplace upgrade blender-agent-studio
codex plugin add blender-agent-studio@blender-agent-studio

Skills-only install

Install the umbrella routing skill through the Vercel Agent Skills CLI:

bunx skills add -g ifBars/blender-agent-studio --skill blender-agent-studio --agent codex -y

Install the umbrella and all eleven specialist skills:

bunx skills add -g ifBars/blender-agent-studio --skill "*" --agent codex --full-depth -y

The skills-only route does not install the bundled MCP or Codex plugin
presentation metadata.

Blender 5.2 LTS is the validated runtime. Put blender on PATH, pass
--blender to benchmark commands, or set BLENDER_EXECUTABLE.

PowerShell:

$env:BLENDER_EXECUTABLE = "C:\path\to\Blender\blender.exe"

macOS or Linux:

export BLENDER_EXECUTABLE="/path/to/blender"

The executable resolver fails clearly when Blender cannot be found; the public
package contains no machine-specific installation path.

Choose a workflow

Reproducible model

Ask the agent to deliver:

create_asset.py
asset.blend
asset.glb
final_report.md

The Python script is the durable source. Generated files must be reproducible
from a clean Blender process.

Headless Blender execution

& $env:BLENDER_EXECUTABLE `
  --background --factory-startup --python .\create_asset.py

Deterministic asset inspection

& $env:BLENDER_EXECUTABLE `
  --background --factory-startup `
  --python ".\plugins\blender-agent-studio\skills\blender-asset-validation\scripts\inspect_asset.py" -- `
  --input ".\asset.glb" --output ".\evidence\metrics.json"

Paired quick benchmark

Run each condition into a new output directory:

cd .\plugins\blender-agent-studio
bun install

bun run benchmark --suite quick --mode baseline `
  --output C:\bench\baseline --blender $env:BLENDER_EXECUTABLE

bun run benchmark --suite quick --mode skills `
  --output C:\bench\skills --blender $env:BLENDER_EXECUTABLE

Run skills_mcp separately so MCP transport does not receive credit for skill
or prompt improvements.

Keep full as the historical regression anchor. Run the opt-in harder
environment, procedural, character-rig, and simulation coverage separately:

bun run benchmark --suite challenge --mode skills `
  --condition-label revised-plugin `
  --output C:\bench\revised-challenge --blender $env:BLENDER_EXECUTABLE

When comparing the current plugin with a revision, label both runs distinctly
and pin each to its exact plugin directory with --skill-root, then pass
--require-non-regression to compare_runs.ts. The strict gate does
not allow a gain on one task to average away a missing pair, hard-gate loss,
per-task automated-score decrease, blinded visual majority loss, or critical
visual-criterion regression.

What you get

• Contract-first procedural modeling with semantic objects and materials
• Authored-scene and fresh-import geometry inspection
• Perspective, orthographic, contact-sheet, and critical-frame evidence
• Mechanical animation checks for pivots, supports, and connector endpoints
• Immutable benchmark runs with clean-source reproduction
• Hard-gate scoring plus blinded pairwise visual judging
• Structured presence, count, relation, material, lighting, style, motion, and
  deformation checks against multiview evidence
• A realistic fire-lantern challenge with six-view review and a validated
  15-second moving-flame MP4
• A first-candidate, critic, targeted-repair, same-evidence recheck loop
• Historical regression plus opt-in challenge and integrated gauntlet suites
• Separate baseline, skills, and skills-plus-MCP conditions
• A bounded MCP that cannot execute arbitrary Blender Python

SKILL.md
agents/openai.yaml
.agents/plugins/marketplace.json
plugins/blender-agent-studio/
  .codex-plugin/plugin.json
  .mcp.json
  assets/
  mcp/
  scripts/
  skills/
    blender-agent-benchmark/
    blender-art-direction-intake/
    blender-animation-workflow/
    blender-asset-validation/
    blender-character-workflow/
    blender-iterative-refinement/
    blender-mcp-integration/
    blender-modeling-workflow/
    blender-procedural-workflow/
    blender-rendering-workflow/
    blender-simulation-workflow/

The repository root is a Codex marketplace. The installable plugin lives under
plugins/blender-agent-studio/.

Requirements

• Blender 5.2 LTS recommended
• Codex CLI with plugin marketplace support for the full installation
• Bun 1.3.5+ for the MCP, tests, and benchmark harness
• Python supplied by Blender for asset-generation and evaluation scripts

Install dependencies and run the same checks used by GitHub Actions:

bun install --cwd plugins/blender-agent-studio
bun run check
bun run test
bun run test:python

The checks validate marketplace and plugin metadata, interface assets, skill
frontmatter, bounded MCP discovery, benchmark scoring, challenge coverage, and
the non-regression gate.

The Python suite includes an optional live Blender renderer test when Blender
is on PATH or BLENDER_EXECUTABLE is set. CI without Blender runs the pure
settings tests and reports the runtime test as skipped.

When editing plugins/blender-agent-studio/references/astra-workflow.md, run
bun tools/sync-guidance.ts to bundle the same guidance inside every specialist
skill. bun run check rejects stale copies, so individual skill installs do
not depend on a shared file outside their package.

Generated models, exports, renders, benchmark runs, and agent traces are
excluded from source control.

Validated benchmark snapshot

The July 2026 snapshot used Blender 5.2.0 LTS, Codex CLI 0.145.0, and
gpt-5.6-terra at medium reasoning.

The final plugin runs received 10 of 10 blinded preference votes with no
hard-gate regression. They averaged about 48% longer because they performed
their own validation and evidence work.

This is directional evidence from one selected generation per condition—not a
universal claim across prompts, models, styles, or random variation. See the
methodology
and validated result.

Security

Blender executes Python with the current user's permissions. Review untrusted
scripts and .blend files before execution. The bundled MCP deliberately
exposes version, inspection, and evidence-render tools instead of generic
arbitrary Python.

Do not commit private models, generated renders, benchmark traces, or sensitive
prompts. See SECURITY.md.

License and trademarks

The project source is available under the MIT License.

Blender and the Blender logo are trademarks of the Blender Foundation. This
project integrates with Blender but is not affiliated with or endorsed by the
Blender Foundation. See THIRD_PARTY_NOTICES.md.