Skip to content

CLAUDE.md

Latest commit

 

History

History
66 lines (47 loc) · 4.25 KB

CLAUDE.md

File metadata and controls

66 lines (47 loc) · 4.25 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Status

Pre-implementation. The only file is BLENDERCODE_PYTHON_SPEC.md — the full specification for BlenderCode v0.1.0. All implementation starts from scratch following that spec.

What BlenderCode Is

A Blender add-on that presents a chat panel as the primary UI. An LLM agent operates inside Blender's Python runtime with full bpy access — meshes, modifiers, materials, rendering, animation, compositor, everything. The 3D viewport surfaces only when visual output needs display.

Not a scripting helper. An AI-native content pipeline running inside Blender's interpreter.

Architecture

Port of the pi-mono architecture (TypeScript → Python). The lineage: Claude Code → Python rewrite → BlenderCode.

blendercode/
├── ai/              # Unified multi-provider LLM API (Anthropic, OpenAI, Google)
│                    # Core abstraction: StreamFn — callable yielding text_delta/tool_call/message_end events
├── agent/           # AgentLoop (raw loop) → Agent (loop + state + queuing + events)
│                    # Tool base class with execute(input, context) → ToolResult
│                    # Parallel tool execution via asyncio.gather; per-object mutation queues
├── session/         # SessionManager (JSONL tree with branching), ContextBuilder, ResourceLoader, SettingsManager
│                    # Two-scope settings: global (~/.blendercode/) overrides project-local (.blendercode/)
├── permissions/     # Three modes: default (confirm destructive), plan (read-only), bypass (no confirmation)
├── memory/          # Markdown files in ~/.blendercode/memory/, injected into every system prompt
├── undo/            # Wraps bpy.ops.ed.undo(), session-scoped, max depth 100
├── tools/           # Organized by category: scene/, mesh/, materials/, render/, animation/, file/, code/, web/, workflow/
├── commands/        # Slash commands: /compact, /render, /save, /undo, /memory, /session, /export, /reload, /skills, /doctor, /settings, /bypass
├── ui/              # Single bpy.types.Panel in the N-panel. Immediate-mode rendering. bpy.app.timers for streaming updates.
└── extensions/      # Extensions register via register(api: ExtensionAPI) — can add tools, commands, event handlers, and Blender operators

Naming Conventions

  • Internal module prefix: bc
  • Classes: PascalCase (no prefix)
  • Tools: *Tool suffix
  • Commands: *Command suffix
  • Blender operators: BLENDERCODE_OT_*
  • Blender panels: BLENDERCODE_PT_*
  • Blender properties on WindowManager: bc_ prefix

Adding New Components

Tool: Extend Tool, set name/description/input_schema/is_read_only, override execute(input, context) → ToolResult, register in blendercode/tools/__init__.py.

Slash command: Extend Command, implement name/description/execute(args, context), register in blendercode/commands/__init__.py. Or drop a .py implementing register(api) into .blendercode/commands/.

Extension: Python module in ~/.blendercode/extensions/ or .blendercode/extensions/ implementing register(api: ExtensionAPI). Hot-reloadable via /reload.

Key Design Decisions

  • The world interface is bpy — not the filesystem. pi-mono talks to files/shell; BlenderCode talks to Blender's scene graph.
  • Context compaction: when history nears the context limit, a summary is generated and older messages pruned.
  • Steering (agent.steer(msg)) and follow-up (agent.follow_up(msg)) allow mid-flight course correction.
  • Sessions persist as JSONL in ~/.blendercode/sessions/ with tree-structured branching.
  • Headless mode: blender --background + --python-expr "import blendercode; blendercode.run_headless(...)". Same tool surface, no UI, bypass implied.
  • BLENDERCODE.md in the project directory is injected into every system prompt (like CLAUDE.md).

LLM Provider Details

Uses httpx for async HTTP and SSE streaming. Providers: Anthropic, OpenAI, OpenAI-compatible endpoints, Google. Cross-provider handoffs are transparent — conversations can switch providers without reformatting at the call site. CostTracker accumulates token usage and maps to provider pricing.