An AI-native Blender add-on that presents a chat panel backed by an LLM agent with full bpy access.
BlenderCode hides Blender and presents a conversation. Behind it is the full Blender runtime: meshes, modifiers, materials, physics, the compositor, the render pipeline, and the complete bpy Python API. The user types. The agent acts. The 3D viewport surfaces only when it needs to.
Not a scripting helper. An AI-native content pipeline running inside Blender's interpreter.
- Chat panel in the N-panel (sidebar) as the primary UI
- 55 tools covering scene, mesh, materials, rendering, animation, file I/O, code execution, web access, and workflow orchestration
- 3 LLM providers — Anthropic, OpenAI, Google Gemini — with transparent switching
- Headless mode for CI/CD pipelines and batch processing
- Extension system with hot-reloadable
register(api)modules - Persistent memory and session management with branching
# Package as ZIP
python -m build
# In Blender: Preferences → Add-ons → Install → select the ZIP# Option 1: Environment variableexport ANTHROPIC_API_KEY=sk-ant-...
# Option 2: Settings file
mkdir -p ~/.blendercode
echo'{"api_key": "sk-ant-...", "provider": "anthropic"}'>~/.blendercode/settings.json- Open Blender 5.1+
- Press
Nin the 3D viewport → BlenderCode tab - Type a prompt: "Create a scene with three colored spheres and a camera looking at them"
- The agent creates objects, sets materials, and positions the camera
blender --background scene.blend \
--python-expr "import blendercode; blendercode.run_headless( prompt='Unwrap all meshes, bake AO to vertex color, export as GLTF', model='claude-sonnet-4-20250514', bypass=True )"blendercode/
├── ai/ # Unified multi-provider LLM API (Anthropic, OpenAI, Google)
├── agent/ # AgentLoop, Agent, Tool base, EventEmitter
├── session/ # JSONL session manager, context builder, settings, resources
├── permissions/ # Three modes: default, plan, bypass
├── memory/ # Persistent markdown memory files
├── undo/ # Wraps bpy.ops.ed.undo(), session-scoped
├── tools/ # 55 tools across 9 categories
├── commands/ # 11 slash commands
├── ui/ # Blender N-panel chat interface
├── extensions/ # Extension loader with register(api) pattern
└── headless.py # CLI entry point for pipeline mode
| Category | Tools | Read-Only |
|---|---|---|
| Scene | SceneList, ObjectInspect, ObjectSelect, ObjectTransform, ObjectCreate, ObjectDelete, ObjectDuplicate, CollectionManage, ParentSet | 2 / 9 |
| Mesh | MeshInspect, ModifierList, ModifierAdd, ModifierEdit, ModifierApply, ModifierRemove, MeshEditOps, GeometryNodesAdd | 2 / 8 |
| Materials | MaterialList, MaterialInspect, MaterialCreate, MaterialAssign, ShaderNodeAdd, ShaderNodeConnect, ShaderNodeSetValue, TextureCreate | 2 / 8 |
| Render | RenderSettingsRead, RenderSettingsSet, RenderFrame, RenderViewport, RenderAnimation, CompositorNodeEdit | 1 / 6 |
| Animation | KeyframeList, KeyframeInsert, KeyframeDelete, ActionList, DriverAdd | 2 / 5 |
| File | FileRead, FileWrite, BlendSave, BlendExport, BlendImport, ImageRead, AssetLibraryList, AssetLibraryAppend | 3 / 8 |
| Code | PythonExec, ScriptRun, AddonWrite, AddonList, ExtensionLoad | 1 / 5 |
| Web | WebSearch, WebFetch | 2 / 2 |
| Workflow | Memory, TaskManage, Sleep, SubAgent | 4 / 4 |
| Command | Description |
|---|---|
/compact [N] | Clear history, keep last N messages |
/render [frame] | Render current or specified frame |
/save | Save current .blend file |
/undo [N] | Undo last N agent operations |
/memory [clear] | View or clear persistent memory |
/session [list|save|load|new|branch] | Manage conversation sessions |
/export [format] | Export scene (FBX, OBJ, GLTF, etc.) |
/reload | Hot-reload extensions and skills |
/doctor | Diagnostics check |
/settings | View or modify settings |
/bypass | Toggle bypass mode |
| Mode | Behavior |
|---|---|
| default | Read-only tools auto-approve. Destructive tools prompt for confirmation. |
| plan | Only read-only tools execute. Agent can inspect but not mutate. |
| bypass | All tools execute without confirmation. Headless mode uses this by default. |
Drop a Python file in ~/.blendercode/extensions/ or .blendercode/extensions/:
# ~/.blendercode/extensions/my_tool.pyfromblendercode.agent.toolimportTool, ToolResultclassMyTool(Tool):
name="my_custom_tool"description="Does something custom"input_schema= {"type": "object", "properties": {}}
is_read_only=Truedefexecute(self, params, context):
returnToolResult(success=True, data="done")
defregister(api):
api.register_tool(MyTool())Reload at runtime with /reload.
Two scopes with override precedence:
- Global:
~/.blendercode/settings.json - Project:
.blendercode/settings.json
{
"provider": "anthropic",
"model": "claude-sonnet-4-20250514",
"api_key": "",
"permission_mode": "default",
"max_tokens": 8192
}# Install dev dependencies
pip install httpx pytest pytest-asyncio
# Run pure Python tests (135 tests)
python -m pytest tests/ -v --ignore=tests/tools
# Run full test suite (requires Blender)
blender --background --python run_tests.py- Blender 5.1+ (Python 3.13)
- httpx (async HTTP for LLM providers)
- API key for at least one LLM provider
Claude Code (Anthropic, TypeScript)
→ Python rewrite
→ BlenderCode (this project)
→ GodotCode (GDScript, Godot)
BlenderCode is a direct Python port of the pi-mono architecture. The agent loop, session management, permission system, memory, and extension system are architecturally identical. Only the world interface changes — bpy instead of the filesystem.
MIT