# Blender (for Agents) — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Blender (Agent Automation) Knowledge Base — Index" type: index updated: 2026-07-17 blender_version: "5.2 LTS" --- # Blender for Agents — Knowledge Base Using Blender with AI agents: headless `bpy` automation, deterministic scene scripts, agent render loops, tool-servers, and the LLM/agent tooling ecosystem (Blender-MCP and friends). Focused on how code agents and tool-using LLMs produce and modify `.blend` files reliably and safely — current as of Blender 5.2 LTS. Not a general Blender artist manual. Master catalog — every page appears here. ## Concepts - [[concepts/headless-blender-execution]] — running Blender `--background` for batch/automation - [[concepts/bpy-data-first-automation]] — prefer `bpy.data` over operators for deterministic scripts - [[concepts/operator-context-management]] — when operators are unavoidable: context overrides - [[concepts/idempotent-scene-scripts]] — re-runnable scene scripts that don't duplicate state - [[concepts/agent-render-loop]] — the generate → render → validate loop - [[concepts/render-evidence-review]] — critic-agent review of rendered output - [[concepts/blender-security-model-for-agents]] — arbitrary-Python risk & sandboxing - [[concepts/tool-server-blender-control]] — exposing Blender to agents via a tool server - [[concepts/addon-mediated-agent-control]] — driving interactive Blender through an add-on - [[concepts/geometry-nodes-agent-workflows]] — procedural geometry via Geometry Nodes - [[concepts/animation-agent-workflows]] — keyframe/animation automation - [[concepts/debugging-blender-agent-runs]] — logs, exit codes, and failure diagnosis ## Entities - [[entities/blender]] — the application & current version - [[entities/bpy]] — the Blender Python API - [[entities/bpy-ops]] — the operators module (`bpy.ops`) and its pitfalls - [[entities/blend-file]] — the `.blend` file format - [[entities/command-line-blender]] — the CLI (`--background`, `--python`, `--render-*`) - [[entities/blender-addon]] — add-on structure & registration - [[entities/geometry-nodes]] — the Geometry Nodes system - [[entities/render-engines]] — EEVEE, Cycles, Workbench - [[entities/blender-mcp]] — the Blender-MCP server + socket add-on ## Syntheses - [[syntheses/headless-vs-interactive-agents]] — headless batch vs live-session control - [[syntheses/data-api-vs-operators]] — `bpy.data` vs `bpy.ops` for automation - [[syntheses/agentic-blender-production-pipeline]] — end-to-end agent production pipeline - [[syntheses/blender-agent-risk-register]] — risks & mitigations for agent-driven Blender - [[syntheses/llm-blender-tool-landscape]] — Blender-MCP, BlenderGPT, BlenderLM, SceneCraft, LL3M compared ## Statistics - **Total pages**: 26 - **Concepts**: 12 - **Entities**: 9 - **Summaries**: 0 - **Syntheses**: 5 --- title: "Add-on Mediated Agent Control" type: concept tags: [addons, interactive, operators, advanced] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/agent-automation-patterns.md"] confidence: medium --- # Add-on Mediated Agent Control ## Definition Add-on mediated agent control is an interactive workflow where a [[entities/blender-addon]] exposes agent-friendly operators, panels, or services inside Blender. ## How It Works The add-on may provide commands to run generated scripts, export a scene manifest, inspect selected objects, render previews, or apply structured patches. The agent interacts with the add-on rather than directly manipulating every UI state. Final validation should still use [[concepts/headless-blender-execution]] where possible. ## Key Parameters - Operators exposed to the agent. - Panel UI and user approval points. - Script execution policy. - Manifest schema. - Logging and rollback behavior. ## When To Use Use it when the user needs interactive review, selected-object assistance, in-viewport iteration, or workflows that depend on an open Blender session. ## Risks & Pitfalls - Interactive state is harder to reproduce than headless runs. - Add-ons increase the security and compatibility surface. - Long-running operations can block the UI if not designed carefully. ## Related Concepts - [[concepts/operator-context-management]] - [[concepts/blender-security-model-for-agents]] - [[concepts/render-evidence-review]] - [[syntheses/headless-vs-interactive-agents]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/agent-automation-patterns.md` --- title: "Agent Render Loop" type: concept tags: [agent, rendering, validation, headless, foundational] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/agent-automation-patterns.md"] confidence: high --- # Agent Render Loop ## Definition The agent render loop is an evidence-driven cycle where an agent plans a Blender task, generates or edits Python, runs Blender, collects artifacts, critiques the result, and repeats until the acceptance criteria pass. ## How It Works The loop begins with a structured scene or task specification from scene specification contracts. A coder agent writes a script that uses [[entities/bpy]] and usually executes through [[concepts/headless-blender-execution]]. Blender emits logs, render files, saved `.blend` files, and optional JSON reports. A critic agent performs [[concepts/render-evidence-review]] and returns concrete fixes. The coder patches the script, not just the prompt, so changes are durable and reviewable. ## Key Parameters - Blender version and command-line flags. - Target artifacts: `.blend`, PNG, EXR, video, JSON report. - Acceptance checklist and visual requirements. - Timeout, sample count, resolution, and render engine. - Whether the script starts from a blank scene or modifies an existing [[entities/blend-file]]. ## When To Use Use this for generated scenes, asset conversion, automated camera and lighting work, batch renders, model QA, and any workflow where natural-language intent must be verified through actual Blender output. ## Risks & Pitfalls - Reviewing only code without a render misses camera, lighting, scale, and visibility errors. - Reviewing only the render misses scene graph, naming, asset path, and file-output problems. - Long render settings can make iteration too slow; use low-resolution previews before final output. - Stale state can hide bugs unless scripts are [[concepts/idempotent-scene-scripts]]. ## Related Concepts - [[concepts/headless-blender-execution]] - [[concepts/render-evidence-review]] - [[concepts/debugging-blender-agent-runs]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/agent-automation-patterns.md` --- title: "Animation Agent Workflows" type: concept tags: [animation, rendering, validation, advanced] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/agent-automation-patterns.md", "raw/blender-agent-field-guide.md"] confidence: medium --- # Animation Agent Workflows ## Definition Animation agent workflows use agents to create or modify keyframes, camera paths, object motion, materials, and render settings for time-based Blender outputs. ## How It Works The scene specification defines frame range, fps, beats, camera targets, object actions, and output format. The coder agent inserts keyframes or creates actions using [[entities/bpy]]. The render agent produces preview frames or short clips. The critic agent reviews timing, continuity, framing, and whether required events appear in the right order. ## Key Parameters - Frame start, frame end, fps, and duration. - Camera paths and focal targets. - Keyframe interpolation. - Preview frame sampling strategy. - Render engine and output codec or image sequence format. ## When To Use Use this for turntables, product motion, explainer animations, procedural motion tests, and animated scene generation. ## Risks & Pitfalls - Checking only one frame can miss animation failures. - Motion can leave objects outside the camera view. - Long final renders should be preceded by low-cost preview sampling. ## Related Concepts - [[concepts/agent-render-loop]] - [[concepts/render-evidence-review]] ## Sources - `raw/agent-automation-patterns.md` - `raw/blender-agent-field-guide.md` --- title: "Blender Security Model for Agents" type: concept tags: [security, python-script, addons, validation] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/blender-python-api-notes.md"] confidence: medium --- # Blender Security Model for Agents ## Definition The Blender security model for agents is a set of constraints for safely executing LLM-generated Blender Python, add-ons, and asset-processing scripts. ## How It Works Agent-generated scripts are treated as untrusted code. The orchestrator limits working directories, disables unnecessary network access, avoids shell execution from Blender Python, controls add-on loading, and reviews imports. For command-line runs, [[concepts/headless-blender-execution]] should use explicit scripts and output paths rather than open-ended execution. ## Key Parameters - Allowed input and output directories. - Whether automatic script execution is enabled. - Import allowlist and blocked modules. - Network policy. - Add-on trust and provenance. - Cleanup and temporary-file policy. ## When To Use Use it whenever an agent writes Python, installs or enables add-ons, opens untrusted `.blend` files, downloads assets, or modifies user files. ## Risks & Pitfalls - Blender Python can read and write files like normal Python. - Add-ons can execute code during registration or operation. - Untrusted `.blend` files can contain drivers or scripts depending on execution settings. - Overly restrictive policies can block legitimate imports or asset paths. ## Related Concepts - [[concepts/idempotent-scene-scripts]] - [[concepts/headless-blender-execution]] - [[concepts/addon-mediated-agent-control]] - [[syntheses/blender-agent-risk-register]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/blender-python-api-notes.md` --- title: "bpy.data First Automation" type: concept tags: [bpy, data-api, deterministic, foundational] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-python-api-notes.md", "raw/blender-agent-field-guide.md"] confidence: high --- # bpy.data First Automation ## Definition `bpy.data` first automation is the practice of editing Blender data-blocks directly instead of relying primarily on UI-style operators. ## How It Works The script creates meshes, materials, collections, cameras, lights, actions, and node trees through [[entities/bpy]] data APIs. It sets RNA properties directly and links objects into collections. Operators from [[entities/bpy-ops]] are reserved for tasks where Blender already packages complex behavior as an operator. ## Key Parameters - Object and collection naming conventions. - Whether data-blocks are created fresh, reused, or updated. - Direct property settings for transforms, materials, render settings, and visibility. - Cleanup policy for old generated data. ## When To Use Use this for generated scenes, deterministic setup blocks, testable asset creation, material assignment, camera and light construction, and any agent script expected to run in background mode. ## Risks & Pitfalls - Some operations are more tedious through direct data APIs than through operators. - Low-level mesh construction requires correct vertices, faces, normals, and transforms. - Agents may hallucinate property names; validate with actual Blender runs. ## Related Concepts - [[concepts/operator-context-management]] - [[concepts/idempotent-scene-scripts]] - [[concepts/debugging-blender-agent-runs]] ## Sources - `raw/blender-python-api-notes.md` - `raw/blender-agent-field-guide.md` --- title: "Debugging Blender Agent Runs" type: concept tags: [debugging, logs, testing, headless, foundational] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/blender-python-api-notes.md"] confidence: high --- # Debugging Blender Agent Runs ## Definition Debugging Blender agent runs is the process of diagnosing failures in generated scripts, command-line execution, renders, and output artifacts. ## How It Works The agent captures stdout, stderr, process exit code, script path, Blender version, command-line arguments, output directory listing, and optional JSON scene reports. It classifies failures as syntax/API errors, context/operator errors, missing assets, render/camera/light failures, timeout/resource failures, or acceptance-check failures. ## Key Parameters - Exact command and working directory. - Blender version. - Non-zero exit behavior via command-line Python options. - Log capture path. - Report schema and render output checks. ## When To Use Use this on every failed [[concepts/agent-render-loop]] iteration and before changing prompts blindly. ## Risks & Pitfalls - A black render may be a camera, lighting, material, visibility, or world issue. - `bpy.ops` failures can be context errors rather than missing API. - Missing output files may indicate command ordering mistakes, not rendering bugs. ## Related Concepts - [[concepts/headless-blender-execution]] - [[concepts/operator-context-management]] - [[concepts/render-evidence-review]] - [[syntheses/blender-agent-risk-register]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/blender-python-api-notes.md` --- title: "Geometry Nodes Agent Workflows" type: concept tags: [geometry-nodes, procedural, advanced, experimental] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/agent-automation-patterns.md"] confidence: low --- # Geometry Nodes Agent Workflows ## Definition Geometry Nodes agent workflows use agents to design, parameterize, or validate procedural node systems in [[entities/geometry-nodes]]. ## How It Works An agent can treat a node tree as a procedural program: define inputs, construct nodes, link sockets, set default values, and attach the modifier to an object. A more robust approach is to maintain known-good node group templates and let the agent adjust exposed parameters rather than synthesize large node graphs from scratch. ## Key Parameters - Node group inputs and outputs. - Modifier target object. - Parameter ranges. - Template node groups. - Realized geometry checks. ## When To Use Use this for scatter systems, parametric architecture, procedural props, instancing, and repeated scene variation. ## Risks & Pitfalls - Node APIs and socket names are version-sensitive. - Large generated node graphs are hard to review textually. - Visual failures may not be obvious without rendered or viewport evidence. ## Related Concepts - [[concepts/render-evidence-review]] - [[concepts/bpy-data-first-automation]] ## Sources - `raw/agent-automation-patterns.md` --- title: "Headless Blender Execution" type: concept tags: [headless, command-line, batch, rendering, foundational] created: 2026-06-04 updated: 2026-07-17 sources: ["raw/blender-python-api-notes.md", "raw/blender-agent-field-guide.md"] confidence: high --- # Headless Blender Execution ## Definition Headless Blender execution means running Blender without the interactive UI, usually with `--background` or `-b`, so agents can execute scripts and renders repeatably from the command line. ## How It Works An agent writes a Python script, then invokes [[entities/command-line-blender]] with a command such as `blender --background --python script.py --python-exit-code 1`. The script uses [[entities/bpy]] to build or modify the scene, saves outputs, and exits. For rendering, command-line render options must appear after the settings they depend on. ## Key Parameters - Blender executable path. - Working directory and allowed output directory. - `--background`, `--python`, `--python-exit-code`, render frame/range, and render output flags. - Timeout and maximum resource usage. - Whether system Python environment access is allowed. ## When To Use Use headless execution for CI, batch rendering, automated asset generation, regression tests, preview renders, and agent loops where deterministic evidence matters more than UI interaction. ## Risks & Pitfalls - A script can succeed while the render fails if command-line argument order is wrong. - Some UI-only operators or add-ons expect interactive context. - GPU and add-on availability can differ between user sessions and background runs. - Without `--python-exit-code`, a failed Python script may be harder for an orchestrator to classify correctly. - Background render progress moved to Blender's unified logging system in 5.0, changing stdout formatting. Prefer exit codes and inspecting the written output files over scraping the pre-5.0 progress lines. ## Related Concepts - [[concepts/agent-render-loop]] - [[concepts/debugging-blender-agent-runs]] - [[concepts/blender-security-model-for-agents]] - [[concepts/addon-mediated-agent-control]] ## Sources - `raw/blender-python-api-notes.md` - `raw/blender-agent-field-guide.md` --- title: "Idempotent Scene Scripts" type: concept tags: [python-script, testing, deterministic, foundational] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md"] confidence: high --- # Idempotent Scene Scripts ## Definition An idempotent scene script can be run repeatedly and produce the same intended Blender scene without accumulating duplicate objects, stale materials, or conflicting state. ## How It Works The script either clears the scene or works inside a namespaced collection. It uses stable object names, deletes or updates prior generated data, sets all important properties explicitly, and writes deterministic output paths. It should create or validate its own cameras, lights, materials, render settings, and reports. ## Key Parameters - Cleanup strategy: clear scene, replace collection, or update named objects. - Stable naming prefix. - Random seed policy. - Output directory and overwrite behavior. - Version and unit assumptions. ## When To Use Use this for every generated script that an agent may run more than once, especially inside [[concepts/agent-render-loop]]. ## Risks & Pitfalls - Partial cleanup can delete user work if namespaces are not respected. - Hidden data-block users can keep old meshes or materials alive. - Randomized generation without a seed makes visual diffs noisy. ## Related Concepts - [[concepts/bpy-data-first-automation]] - [[concepts/debugging-blender-agent-runs]] - [[concepts/blender-security-model-for-agents]] ## Sources - `raw/blender-agent-field-guide.md` --- title: "Operator Context Management" type: concept tags: [operators, context, bpy, debugging, foundational] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-python-api-notes.md", "raw/blender-agent-field-guide.md"] confidence: high --- # Operator Context Management ## Definition Operator context management is the discipline of calling [[entities/bpy-ops]] only with the context, selection, mode, and active data that the operator expects. ## How It Works Blender operators are commands originally designed around UI actions. They can inspect [[entities/bpy]] context, active object, selected objects, mode, window, area, region, and scene state. An agent must either prepare that state or use context overrides where appropriate. It should check return status and catch `RuntimeError` for reported errors. ## Key Parameters - Active object and selected objects. - Object mode, edit mode, pose mode, or sculpt mode. - Scene, view layer, collection, area, and region context. - Operator return set and reported errors. ## When To Use Use operator context management when calling import/export operators, mesh tools, baking operations, add-on operators, or UI-bound commands that do not have a simpler direct data API equivalent. ## Risks & Pitfalls - Operators may return `{'CANCELLED'}` without raising if no error report exists. - Context requirements can differ between interactive and headless runs. - Hidden selection or mode state can make scripts non-idempotent. ## Related Concepts - [[concepts/bpy-data-first-automation]] - [[concepts/headless-blender-execution]] - [[concepts/debugging-blender-agent-runs]] ## Sources - `raw/blender-python-api-notes.md` - `raw/blender-agent-field-guide.md` --- title: "Render Evidence Review" type: concept tags: [qa, critic-agent, image-output, validation] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/agent-automation-patterns.md"] confidence: medium --- # Render Evidence Review ## Definition Render evidence review is the practice of evaluating Blender agent output using concrete artifacts: rendered images, saved files, logs, JSON scene manifests, and measured scene properties. ## How It Works After [[concepts/headless-blender-execution]], the agent collects output files and checks them against scene specification contracts. A critic may inspect pixels, confirm the camera frames the required objects, parse JSON object inventories, and review logs for errors or warnings. ## Key Parameters - Preview render resolution and sample count. - Required output paths and file size checks. - Camera visibility and bounding-box checks. - Visual acceptance criteria. - Critic model or human review rubric. ## When To Use Use it for generated scenes, final renders, asset QA, animation previews, and regression tests after script changes. ## Risks & Pitfalls - Low-resolution renders can hide material and geometry errors. - Pixel review alone cannot verify object hierarchy, names, or asset provenance. - Automated visual review can miss subtle intent mismatches. ## Related Concepts - [[concepts/agent-render-loop]] - [[concepts/debugging-blender-agent-runs]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/agent-automation-patterns.md` --- title: "Tool Server Blender Control" type: concept tags: [tool-server, mcp, interactive, security, advanced] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/community-agent-sources-ingest.md"] confidence: medium --- # Tool Server Blender Control ## Definition Tool server Blender control exposes Blender state and actions to an external agent through a protocol, local server, or tool API. ## How It Works Instead of copy-pasting generated scripts into Blender, an agent calls tools such as inspect scene, run Python, render preview, create object, export manifest, or save file. Blender MCP and BlenderLM-style projects illustrate this direction. The pattern is powerful because it lets an external orchestrator implement [[concepts/agent-render-loop]] while Blender remains the execution environment. ## Key Parameters - Tool API shape and permissions. - Allowed Python execution scope. - Scene inspection schema. - Authentication or local-only boundary. - Logging, rollback, and user approval. ## When To Use Use it for agent frameworks, IDE integrations, local automation, and workflows that need live scene context without building a full UI add-on. ## Risks & Pitfalls - Broad `run_python` tools are equivalent to arbitrary code execution. - Remote access must be locked down. - Tool responses need enough structure for agents to reason accurately. - Long operations need timeout and cancellation support. ## Related Concepts - [[concepts/addon-mediated-agent-control]] - [[concepts/blender-security-model-for-agents]] - [[concepts/render-evidence-review]] - [[concepts/debugging-blender-agent-runs]] ## Sources - `raw/community-agent-sources-ingest.md` --- title: "Blend File" type: entity tags: [artifact, blend-file] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/agent-automation-patterns.md"] confidence: high --- # Blend File ## Overview A `.blend` file is Blender's native project file and the primary persistent artifact for scenes, assets, animation, materials, and render settings. ## Characteristics - Can contain scene data, linked or appended assets, scripts, drivers, and custom properties. - Useful as both input and output for agent workflows. - Must be treated carefully when untrusted because it can carry executable or behavior-affecting data depending on settings. ## Common Strategies - [[concepts/idempotent-scene-scripts]] - [[concepts/blender-security-model-for-agents]] - [[concepts/render-evidence-review]] ## Related Entities - [[entities/blender]] - [[entities/bpy]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/agent-automation-patterns.md` --- title: "Blender Add-on" type: entity tags: [addons, interactive, operators] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/agent-automation-patterns.md"] confidence: medium --- # Blender Add-on ## Overview A Blender add-on is a Python extension that can register operators, panels, properties, menus, and other integrations inside Blender. ## Characteristics - Can expose agent-facing UI or command surfaces. - Often interacts with [[entities/bpy-ops]] and context. - Adds security and compatibility considerations. - Useful for interactive workflows that cannot be handled comfortably by headless scripts. ## Common Strategies - [[concepts/addon-mediated-agent-control]] - [[concepts/operator-context-management]] - [[concepts/blender-security-model-for-agents]] - [[concepts/render-evidence-review]] ## Related Entities - [[entities/blender]] - [[entities/bpy]] - [[entities/bpy-ops]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/agent-automation-patterns.md` --- title: "Blender MCP" type: entity tags: [community, mcp, tool-server, llm-agent, socket-addon] created: 2026-06-04 updated: 2026-07-17 sources: ["raw/agent-tool-research-2026-07.md", "raw/community-agent-sources-ingest.md"] confidence: high --- # Blender MCP ## Overview Blender MCP ([ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp)) is the dominant open-source project for driving Blender from an LLM. It is a Model Context Protocol (MCP) server that exposes a live Blender session to any MCP-aware client — Claude Desktop, Cursor, VS Code, OpenCode, or Claude Code — for prompt-assisted 3D modeling, scene creation, inspection, and manipulation. Created by Siddharth Ahuja (@sidahuj), MIT-licensed, ~24.4k GitHub stars as of July 2026. ## Characteristics - Two-part architecture: a Blender [[entities/blender-addon|addon]] (`addon.py`) runs a **socket server inside Blender** (default `localhost:9876`, override with `BLENDER_HOST` / `BLENDER_PORT`), and a separate **MCP server** (`src/blender_mcp/server.py`) speaks MCP to the agent client and forwards commands over the socket to [[entities/bpy|bpy]]. - Exposes tools for scene/object inspection (`get_scene_info`), object create/delete/ modify, material creation/application, and viewport screenshot capture. - Ships `execute_blender_code`, which runs arbitrary Python inside Blender — the most powerful and most dangerous tool. - Integrates external asset sources: Poly Haven (models/textures/HDRIs), Hyper3D Rodin and Hunyuan3D (AI model generation), and Sketchfab search/download. - Requires Blender 3.0+, Python 3.10+, and the `uv` package manager. ## How to Use 1. Install `uv` via its official installer (the MCP server runs through `uvx`, not pip). 2. Download `addon.py` from the repo. In Blender: Edit > Preferences > Add-ons > Install, select `addon.py`, and enable the checkbox. 3. Open the BlenderMCP panel in the 3D-view sidebar (press N) and start the server; it begins listening on `localhost:9876`. 4. Register the MCP server in your client. For Claude Desktop / Cursor / VS Code, add a server whose command is `uvx blender-mcp`. 5. Prompt the agent (e.g. "add a red cube and render the scene"); the client calls MCP tools, which reach `bpy` through the addon socket. Save your `.blend` before running. ## Related Entities - [[entities/blender]] - [[entities/bpy]] - [[entities/blender-addon]] - [[entities/command-line-blender]] ## Common Strategies - [[concepts/tool-server-blender-control]] - [[concepts/blender-security-model-for-agents]] - [[concepts/agent-render-loop]] - [[concepts/debugging-blender-agent-runs]] ## Security Notes - `execute_blender_code` is arbitrary code execution in Blender — treat every generated script as untrusted and save work first (see [[concepts/blender-security-model-for-agents]]). - The addon socket accepts commands with no authentication; keep it on localhost or a trusted network only. - Anonymized telemetry is on by default; disable via the preferences checkbox or `DISABLE_TELEMETRY=true`. ## Sources - `raw/agent-tool-research-2026-07.md` - `raw/community-agent-sources-ingest.md` --- title: "Blender" type: entity tags: [tool, rendering, blend-file] created: 2026-06-04 updated: 2026-07-17 sources: ["raw/blender-agent-field-guide.md", "raw/blender-python-api-notes.md"] confidence: high --- # Blender ## Overview Blender is an open-source 3D creation suite that agents can control through Python scripts, command-line rendering, add-ons, and `.blend` files. ## Characteristics - The current stable release is Blender 5.2 LTS (July 2026); the 5.x series is the baseline agents should target. - Stores scenes, assets, materials, animation, and settings in [[entities/blend-file]] files. - Exposes a Python API through [[entities/bpy]]. - Supports background execution through [[entities/command-line-blender]]. - Can be extended through [[entities/blender-addon]] packages. ## Common Strategies - [[concepts/headless-blender-execution]] - [[concepts/agent-render-loop]] - [[concepts/bpy-data-first-automation]] - [[concepts/blender-security-model-for-agents]] ## Related Entities - [[entities/bpy]] - [[entities/blend-file]] - [[entities/render-engines]] - [[entities/geometry-nodes]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/blender-python-api-notes.md` --- title: "bpy.ops" type: entity tags: [api, operators, context] created: 2026-06-04 updated: 2026-07-17 sources: ["raw/blender-python-api-notes.md", "raw/blender-agent-field-guide.md"] confidence: high --- # bpy.ops ## Overview `bpy.ops` is Blender's Python access path for operators: commands implemented by Blender, Python scripts, macros, or add-ons. ## Characteristics - Operators are context-sensitive. - Operator calls use keyword arguments for properties. - Operators return status sets such as `{'FINISHED'}` or `{'CANCELLED'}`. - Reported operator errors can raise `RuntimeError`. ## Common Strategies - [[concepts/operator-context-management]] - [[concepts/bpy-data-first-automation]] - [[concepts/debugging-blender-agent-runs]] - [[concepts/addon-mediated-agent-control]] ## Related Entities - [[entities/bpy]] - [[entities/blender-addon]] - [[entities/command-line-blender]] ## Sources - `raw/blender-python-api-notes.md` - `raw/blender-agent-field-guide.md` --- title: "bpy" type: entity tags: [api, bpy, python-script] created: 2026-06-04 updated: 2026-07-17 sources: ["raw/blender-python-api-notes.md"] confidence: high --- # bpy ## Overview `bpy` is Blender's Python API module. It is the main interface agents use to create, inspect, modify, render, and save Blender scenes. ## Characteristics - `bpy.data` exposes data-blocks such as meshes, objects, materials, images, cameras, lights, scenes, and collections. - `bpy.context` exposes current execution context. - `bpy.ops` exposes [[entities/bpy-ops]]. - `bpy.app` exposes application information, handlers, and timers. `bpy.app.version` reports the running version (e.g. `(5, 2, 0)` on Blender 5.2 LTS) and is the reliable way for a script to branch on version-specific behavior. - `bpy.types` exposes Blender type definitions. - The core `bpy` module layout is stable across the 5.x series, but some data-block properties were renamed in 5.0 (for example EEVEE ambient-occlusion settings moved to the view layer). Scripts targeting a fleet of versions should read `bpy.app.version` before touching version-sensitive properties. ## Common Strategies - [[concepts/bpy-data-first-automation]] - [[concepts/operator-context-management]] - [[concepts/idempotent-scene-scripts]] - [[concepts/debugging-blender-agent-runs]] ## Related Entities - [[entities/blender]] - [[entities/bpy-ops]] - [[entities/command-line-blender]] ## Sources - `raw/blender-python-api-notes.md` --- title: "Command-Line Blender" type: entity tags: [command-line, headless, rendering] created: 2026-06-04 updated: 2026-07-17 sources: ["raw/blender-python-api-notes.md"] confidence: high --- # Command-Line Blender ## Overview Command-line Blender is the execution surface for running Blender from terminals, automation systems, and agents without requiring direct UI interaction. ## Characteristics - Supports background mode with `--background` or `-b`. - Runs Python files with `--python` or `-P`. - Can render frames or animations from command-line options: `--render-frame`/`-f`, `--render-anim`/`-a`, and `--render-output`/`-o`. These flags are unchanged in the 5.x series. - Argument order matters for rendering workflows. - Blender 5.0 routed background render progress through the unified logging system, so terminal output during a render changed from earlier versions (the per-frame "Fra:"/scene line was initially dropped and partially restored). Orchestrators that parse render progress from stdout should not assume the pre-5.0 format. ## Common Strategies - [[concepts/headless-blender-execution]] - [[concepts/agent-render-loop]] - [[concepts/debugging-blender-agent-runs]] - [[concepts/blender-security-model-for-agents]] ## Related Entities - [[entities/blender]] - [[entities/bpy]] - [[entities/render-engines]] ## Sources - `raw/blender-python-api-notes.md` --- title: "Geometry Nodes" type: entity tags: [geometry-nodes, procedural] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/agent-automation-patterns.md"] confidence: medium --- # Geometry Nodes ## Overview Geometry Nodes is Blender's procedural node system for generating and modifying geometry. ## Characteristics - Represents procedural logic as node groups and links. - Can expose parameters for agent-controlled variation. - Useful for scattering, instancing, terrain, architecture, and repeated patterns. - More difficult for agents to synthesize safely than simple `bpy.data` scenes. ## Common Strategies - [[concepts/geometry-nodes-agent-workflows]] - [[concepts/render-evidence-review]] ## Related Entities - [[entities/blender]] - [[entities/bpy]] ## Sources - `raw/agent-automation-patterns.md` --- title: "Render Engines" type: entity tags: [rendering, cycles, eevee] created: 2026-06-04 updated: 2026-07-17 sources: ["raw/blender-agent-field-guide.md", "raw/blender-python-api-notes.md"] confidence: medium --- # Render Engines ## Overview Render engines are Blender subsystems that convert scenes into images or animations. Agent workflows commonly need to choose between fast previews and final-quality renders. ## Characteristics - Blender ships three engines: EEVEE (real-time rasterizer with ray tracing), Cycles (physically based path tracer), and Workbench (fast solid-shading previews). - Set the engine with `bpy.context.scene.render.engine`. Valid identifiers in the 5.x series are `'BLENDER_EEVEE'`, `'CYCLES'`, and `'BLENDER_WORKBENCH'`. - The engine formerly known as EEVEE Next is now simply EEVEE. Legacy EEVEE was removed in Blender 5.0, and the engine identifier was renamed from `BLENDER_EEVEE_NEXT` (4.2-4.5) back to `BLENDER_EEVEE` in 5.0. Scripts written for 4.x that set `'BLENDER_EEVEE_NEXT'` must be updated for 5.x. - Render engine choice affects speed, quality, lighting behavior, and available settings. - Preview iterations should usually use reduced resolution and sample counts. - Final renders should be separated from validation previews in [[concepts/agent-render-loop]]. ## Common Strategies - [[concepts/render-evidence-review]] - [[concepts/headless-blender-execution]] - [[concepts/animation-agent-workflows]] ## Related Entities - [[entities/blender]] - [[entities/command-line-blender]] - [[entities/blend-file]] ## Sources - `raw/blender-agent-field-guide.md` - `raw/blender-python-api-notes.md` --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion --- title: "Agentic Blender Production Pipeline" type: synthesis tags: [agent, pipeline, validation, rendering] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/agent-automation-patterns.md"] confidence: medium --- # Agentic Blender Production Pipeline ## Comparison | Stage | Main page | Output | |---|---|---| | Intent capture | scene specification contracts | Structured scene/task spec | | Planning | agent role separation | Work plan and acceptance checks | | Code generation | [[concepts/bpy-data-first-automation]] | Blender Python script | | Execution | [[concepts/headless-blender-execution]] | Logs, `.blend`, renders | | Review | [[concepts/render-evidence-review]] | Failure list or acceptance | | Hardening | [[concepts/idempotent-scene-scripts]] | Repeatable script and artifacts | ## Analysis The central production insight is that generated Blender code is not the deliverable by itself. The deliverable is a verified bundle: script, `.blend`, renders, logs, and evidence that the output satisfies the scene contract. ## Recommendations - Keep the scene spec explicit and versioned. - Use known-good templates for render setup, cameras, color management, and reports. - Run low-cost previews before final renders. - Preserve evidence from each run so regressions can be explained. ## Pages Compared - [[concepts/agent-render-loop]] - [[concepts/render-evidence-review]] - [[concepts/idempotent-scene-scripts]] --- title: "Blender Agent Risk Register" type: synthesis tags: [security, debugging, validation, risk] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/blender-python-api-notes.md", "raw/agent-automation-patterns.md"] confidence: medium --- # Blender Agent Risk Register ## Comparison | Risk | Symptom | Mitigation | |---|---|---| | Context-sensitive operator failure | `{'CANCELLED'}` or `RuntimeError` | [[concepts/operator-context-management]] | | Black or empty render | File exists but scene is invisible | [[concepts/render-evidence-review]] plus camera/light checks | | Stale generated scene state | Duplicate or old objects | [[concepts/idempotent-scene-scripts]] | | Missing assets | Broken links or placeholder geometry | asset library grounding | | Unsafe generated Python | Unexpected file/network actions | [[concepts/blender-security-model-for-agents]] | | Slow iteration | Agent spends time on final-quality renders | Preview-first [[concepts/agent-render-loop]] | | Hallucinated API | Attribute errors or invalid calls | [[concepts/debugging-blender-agent-runs]] | ## Analysis Most Blender-agent failures are not pure language-model failures. They are interface-contract failures: missing context, unspecified output, absent evidence, unsafe execution assumptions, or ambiguous visual requirements. ## Recommendations - Require a script report for every run. - Make output paths explicit and workspace-scoped. - Validate camera framing and object visibility automatically. - Prefer direct data APIs for deterministic construction. - Treat add-ons and generated scripts as code with a security review surface. ## Pages Compared - [[concepts/blender-security-model-for-agents]] - [[concepts/debugging-blender-agent-runs]] - [[concepts/operator-context-management]] - [[concepts/render-evidence-review]] --- title: "Data API vs Operators" type: synthesis tags: [bpy, operators, data-api, deterministic] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-python-api-notes.md", "raw/blender-agent-field-guide.md"] confidence: high --- # Data API vs Operators ## Comparison | Dimension | `bpy.data` and direct properties | `bpy.ops` operators | |---|---|---| | Primary page | [[concepts/bpy-data-first-automation]] | [[concepts/operator-context-management]] | | Determinism | Usually high | Context-dependent | | Verbosity | Can be more verbose | Often concise | | Headless suitability | Strong | Depends on operator | | Error mode | Python exceptions and property errors | Return status sets, cancellations, `RuntimeError` on reported errors | ## Analysis Agents should default to direct data manipulation because it minimizes hidden dependencies on UI state. Operators remain valuable for import/export, specialized tool behavior, add-on commands, and workflows where Blender already implements complex operations. ## Recommendations - Use `bpy.data` for scene construction, materials, cameras, lights, collections, and explicit settings. - Use `bpy.ops` only after preparing context and checking return values. - When an operator fails, debug context before assuming the API does not exist. ## Pages Compared - [[concepts/bpy-data-first-automation]] - [[concepts/operator-context-management]] - [[entities/bpy]] - [[entities/bpy-ops]] --- title: "Headless vs Interactive Agents" type: synthesis tags: [headless, interactive, addons, validation] created: 2026-06-04 updated: 2026-06-04 sources: ["raw/blender-agent-field-guide.md", "raw/agent-automation-patterns.md", "raw/blender-python-api-notes.md"] confidence: medium --- # Headless vs Interactive Agents ## Comparison | Dimension | Headless agent | Interactive add-on agent | |---|---|---| | Primary page | [[concepts/headless-blender-execution]] | [[concepts/addon-mediated-agent-control]] | | Strength | Repeatable execution and CI-friendly evidence | Works with selected objects and user-visible UI state | | Weakness | Limited access to UI-only context | Harder to reproduce and automate | | Best artifact | Logs, JSON report, render output | Scene manifest, selected-object inspection, viewport-driven edits | | Security concern | Generated Python and file access | Add-on trust, script execution, UI state changes | ## Analysis Headless agents are better for acceptance testing, batch work, and final validation. Interactive agents are better for assisting a user already working inside Blender. A mature system often uses both: the add-on gathers context or applies edits, then a headless run validates the result. ## Recommendations - Prefer headless execution for deliverables, tests, and repeatable render loops. - Use interactive add-ons for selected-object assistance, user approval, and viewport workflows. - Validate interactive changes through [[concepts/agent-render-loop]] before treating them as complete. ## Pages Compared - [[concepts/headless-blender-execution]] - [[concepts/addon-mediated-agent-control]] - [[entities/command-line-blender]] - [[entities/blender-addon]] --- title: "LLM/Agent Blender Tool Landscape" type: synthesis tags: [landscape, mcp, tool-server, code-generation, llm-agent] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/agent-tool-research-2026-07.md"] confidence: medium --- # LLM/Agent Blender Tool Landscape A comparison of the main tools that connect LLM agents to Blender, as of July 2026. They split into two families: **tool servers** that expose Blender to an external agent, and **code-writing agents** that generate and run Python against Blender. ## Comparison | Tool | Connection method | Capabilities | Maturity | Security | |---|---|---|---|---| | blender-mcp (ahujasid) | MCP server + Blender socket addon (localhost:9876) | Scene inspect, object/material ops, viewport screenshot, arbitrary Python exec, Poly Haven / Hyper3D / Sketchfab / Hunyuan3D assets | High — ~24.4k stars, active, broad client support | Arbitrary exec + unauthenticated socket; save work; keep local; telemetry on by default | | BlenderGPT (gd3kr) | In-UI Blender addon, direct Python exec of GPT-4 output | Basic single-shot instructions (move, texture, primitives) | Low — early, ~32 commits, no releases, stale | Auto-generates and runs Python, no sandbox | | BlenderLM (victordibia) | Blender socket addon + FastAPI REST server (8000) + Python client | Primitives, transforms, materials, scene mgmt, rendering; Autogen / Google ADK / CrewAI tools | Low — talk/demo sample, may be unmaintained | Unauthenticated socket; trusted networks only | | SceneCraft (research) | Python code-gen loop (scene graph -> script -> render -> VLM critique) | Multi-asset scene synthesis (~100 assets), reusable script library | Research prototype, not packaged | Generated-code execution surface | | LL3M (threedle) | Multi-agent Python code-gen + BlenderRAG knowledge base | Complex assets, procedural shaders, hierarchical scenes, identity-preserving edits | Research; code public but hosted server discontinued (retired model) | Generated-code execution; self-host wiring | ## Analysis blender-mcp is the clear center of gravity. It standardizes on MCP, works with mainstream agent clients out of the box, and its socket addon has become a de-facto backend that other projects (e.g. saofund/LLM-Blender-Agent) build on top of. Its breadth comes from `execute_blender_code`, which is also its main risk. The tool-server family (blender-mcp, BlenderLM) gives agents clean tool calls into a live session — good for interactive, iterative work. BlenderLM is architecturally similar but adds a REST bridge and framework-native tool functions, at the cost of being an unmaintained demo. The code-writing research systems (SceneCraft, LL3M) are less about being installable products and more about proving the [[concepts/agent-render-loop]] pattern: plan -> generate code -> render -> critique -> refine. LL3M adds retrieval (BlenderRAG) and multi-agent debugging, and its public code is a strong reference even though the hosted server is gone. BlenderGPT is mostly historical — the pattern that everything else improved on. Every option converges on the same two hazards: arbitrary Python execution in Blender and unauthenticated local sockets. That makes the [[concepts/blender-security-model-for-agents]] non-optional regardless of which tool you pick. ## Recommendations - Default to **blender-mcp** for agent-driven Blender work: it is the most mature, most supported, and interoperable via MCP. Keep it on localhost, disable telemetry if needed, and gate `execute_blender_code` behind review. - Choose **BlenderLM** only if you specifically need Autogen/CrewAI/Google ADK tool functions and accept its demo/unmaintained status. - Mine **LL3M** and **SceneCraft** for architecture ideas — retrieval-augmented code gen and the render-critique-refine loop — rather than as turnkey services. - Treat **BlenderGPT** as a historical reference, not a production choice. - Apply the same security posture to all of them via [[concepts/tool-server-blender-control]] and [[concepts/blender-security-model-for-agents]]. ## Pages Compared - [[entities/blender-mcp]] - [[concepts/tool-server-blender-control]] - [[concepts/blender-security-model-for-agents]] - [[concepts/agent-render-loop]] - [[concepts/debugging-blender-agent-runs]]