BlenderCode

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.

What It Is

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

Quick Start

Install as Blender Add-on

# Package as ZIP
python -m build

# In Blender: Preferences → Add-ons → Install → select the ZIP

Set API Key

# Option 1: Environment variable
export ANTHROPIC_API_KEY=sk-ant-...

# Option 2: Settings file
mkdir -p ~/.blendercode
echo '{"api_key": "sk-ant-...", "provider": "anthropic"}' > ~/.blendercode/settings.json

Use

1. Open Blender 5.1+
2. Press N in the 3D viewport → BlenderCode tab
3. Type a prompt: "Create a scene with three colored spheres and a camera looking at them"
4. The agent creates objects, sets materials, and positions the camera

Headless Mode

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
  )"

Architecture

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

Tools (55)

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

Slash Commands

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

Permissions

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.

Extensions

Drop a Python file in ~/.blendercode/extensions/ or .blendercode/extensions/:

# ~/.blendercode/extensions/my_tool.py
from blendercode.agent.tool import Tool, ToolResult

class MyTool(Tool):
    name = "my_custom_tool"
    description = "Does something custom"
    input_schema = {"type": "object", "properties": {}}
    is_read_only = True

    def execute(self, params, context):
        return ToolResult(success=True, data="done")

def register(api):
    api.register_tool(MyTool())

Reload at runtime with /reload.

Settings

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
}

Development

# 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

Requirements

• Blender 5.1+ (Python 3.13)
• httpx (async HTTP for LLM providers)
• API key for at least one LLM provider

Lineage

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.

License

MIT