BlendProof

A local-first Blender agent runtime for previewed, evidence-backed scene changes.

BlendProof combines a Codex plugin, reusable Blender production skills, a small host-neutral MCP surface, a Blender 5.2 LTS extension, and a versioned project ledger. Instead of giving an agent an unrestricted Python console and hoping a render looks right, BlendProof turns work into an Evidence-Carrying Scene Patch (ECSP):

intent -> typed operations -> preconditions -> isolated preview
       -> semantic diff + SceneTruth + optional Blender evidence
       -> commit or rollback

The target system is designed to be inspectable, reproducible, and reversible across Blender domains. The current alpha is intentionally narrower: it proves the ledger, orchestration, and a safe static-creation bridge before broader authoring domains graduate.

Status: v0.2 alpha, active development. The patch kernel now carries exact Blender candidates and evidence through preview, commit, and rollback. See Roadmap for the exact maturity of each domain; alpha capabilities are not production claims.

What v0.2 actually runs

• The host-neutral runtime provides the 17 fixed MCP tools, canonical records, branch compare-and-swap, offline planning, staged scripts, and staged provider jobs.
• The Blender bridge executes seven allowlisted operation families: scene object create/delete, mesh primitive creation, object transforms, material assignment, camera configuration, and light configuration.
• Headless previews create a full checkpoint, extract SceneTruth, enforce assertions, render deterministic evidence, and ingest the candidate .blend, checkpoint, checkpoint SceneTruth, manifest, and views into the local SHA-256 content-addressed store. A passing compare-and-swap commit publishes the exact candidate at .blendproof/candidates/<sha256>.blend without overwriting the working file.
• For a Blender-backed commit, rollback appends a revision and physically republishes the base revision's candidate, or the committing preview's checkpoint when the base predates physical candidates. Semantic-only commits remain truth-only.
• The Blender extension includes a bounded, read-only Proof Browser for branches, patches, proofs, revisions, checks, and proof-bound evidence.
• SceneTruth includes normalized pairwise AABB metrics and strict distance, gap, overlap, classification, alignment, proportion, and mirror assertions.
• Experimental local CLI workflows compile a narrow declarative Scene IR and bind bounded Verified Repair plans and gates into the existing patch lifecycle. They add no MCP tools and never commit automatically.
• project_status derives an auditable Project Memory snapshot from ledger sources: branch heads, accepted decisions, rejected checks, current validations, and revision provenance. Agents cannot write free-form recollections into this truth view.
• Other catalog domains are planning-only in the current alpha and report blender_bridge: false; they are benchmark targets, not working Blender authoring claims. Provider polling/download/import and arbitrary-script execution are not exposed by the public MCP.

Why BlendProof

Most Blender agent integrations expose hundreds of imperative tools or an arbitrary bpy execution escape hatch. That is powerful, but it makes failure hard to diagnose and state hard to trust. BlendProof adds a transaction and evidence layer between the agent and Blender:

• Compact orchestration API: a fixed alpha tool set; operation schemas are discovered dynamically with capability_search.
• SceneTruth: deterministic object transforms, dimensions, hierarchy, material/light summaries, world-space AABBs, and normalized pair metrics supplement screenshots. These are AABB facts, not BVH mesh-distance, collision, topology, or simulation proof.
• Atomic revisions: commits use compare-and-swap against base_revision; stale patches cannot silently overwrite newer work.
• Proof bundles: canonical SceneTruth, semantic diffs, validation checks, candidate/checkpoint hashes, checkpoint SceneTruth, evidence manifests, and rendered views are first-class, content-bound artifacts for physical previews.
• Reversible ledger: semantic inverse operations and checkpoint fallback protect preview; accepted candidates and physical rollback are published as immutable content-addressed files while history remains append-only.
• Proof Browser: the Blender UI can inspect ledger records and re-verify or safely reveal proof-bound evidence without approving proofs or changing refs.
• Source-backed memory: bounded snapshots carry source IDs, truncation reasons, and a canonical hash instead of trusting an agent-authored notebook.
• Provider quarantine: an internal helper validates caller-supplied bytes by size, MIME, hash, and structure. Provider polling, download, and import remain later milestones.
• Host-neutral core: Codex gets the richest packaged experience, while the MCP protocol and CLI remain usable by other compatible agents.

Architecture

flowchart TD
    U["User intent"] --> H["Codex or another MCP host"]
    H --> S["BlendProof workflow skills"]
    S --> M["Static MCP orchestration surface"]
    M --> L["Project ledger and patch kernel"]
    L --> B["Blender headless bridge"]
    B --> P["Isolated preview scene"]
    P --> T["SceneTruth and assertions"]
    P --> E["CAS candidate, checkpoint, and evidence"]
    T --> D{"Proof accepted?"}
    E --> D
    D -->|yes| C["CAS candidate publication + atomic branch commit"]
    D -->|repair| R["New patch or rollback"]
    C --> O["Immutable candidate, revision, and ProofBundle"]
    R --> M

Loading

This lifecycle is implemented for the allowlisted Blender bridge subset. Offline previews remain semantic-only. Branch merge currently produces and proves merged SceneTruth, but it does not synthesize a physical three-way .blend merge. The binary CAS also has no garbage collector yet.

See Architecture and Protocol for the complete design.

Repository layout

.agents/plugins/marketplace.json       local/repository marketplace
plugins/blendproof/
  .codex-plugin/plugin.json            Codex plugin manifest
  .mcp.json                            bundled MCP launcher
  skills/                              umbrella + domain workflows
  mcp/                                 host-neutral runtime, CLI, tests
  blender-extension/                   Blender UI and execution bridge (GPL)
docs/                                  architecture, protocol, roadmap, security
examples/                              inspectable patch and benchmark examples

Quick start for contributors

Prerequisites:

• Blender 5.2 LTS
• Python 3.11+
• uv
• Codex desktop/CLI for the packaged plugin experience

Install and test the runtime:

cd plugins/blendproof/mcp
uv sync --all-groups
uv run pytest
uv run blendproof --help

Validate the complete repository:

make check

On Windows, where make may not be installed, PowerShell 7.3+ can run the same make check gates. Native-command failures are promoted to terminating errors, and replay output is always removed:

$ErrorActionPreference = "Stop"
$PSNativeCommandUseErrorActionPreference = $true

$rootPythonFiles = @(
  "scripts/validate_repo.py",
  "scripts/validate_python_distribution.py",
  "scripts/validate_blender_extension_package.py",
  "examples/run_proof_pedestal.py",
  "plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_report.py",
  "plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_replay.py"
)
$smokeResults = Join-Path ([System.IO.Path]::GetTempPath()) ("blendproof-smoke-{0}.jsonl" -f [guid]::NewGuid())
$patchKernelResults = Join-Path ([System.IO.Path]::GetTempPath()) ("blendproof-patch-kernel-{0}.jsonl" -f [guid]::NewGuid())

try {
  uv run --project plugins/blendproof/mcp python plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_report.py validate benchmarks/smoke-v0.1.jsonl --kind suite
  uv run --project plugins/blendproof/mcp python plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_report.py validate benchmarks/patch-kernel-v0.2.jsonl --kind suite
  uv run --project plugins/blendproof/mcp python scripts/validate_repo.py
  uv run --directory plugins/blendproof/mcp ruff check .
  uv run --directory plugins/blendproof/mcp ruff format --check .
  uv run --project plugins/blendproof/mcp ruff check @rootPythonFiles
  uv run --project plugins/blendproof/mcp ruff format --check @rootPythonFiles
  uv run --directory plugins/blendproof/mcp pytest --cov=blendproof --cov-report=term-missing --cov-fail-under=75

  uv run --project plugins/blendproof/mcp python plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_replay.py benchmarks/smoke-v0.1.jsonl --output $smokeResults
  uv run --project plugins/blendproof/mcp python plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_report.py validate $smokeResults --kind results
  uv run --project plugins/blendproof/mcp python plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_replay.py benchmarks/patch-kernel-v0.2.jsonl --output $patchKernelResults
  uv run --project plugins/blendproof/mcp python plugins/blendproof/skills/blendproof-benchmark/scripts/benchmark_report.py validate $patchKernelResults --kind results
} finally {
  Remove-Item -LiteralPath $smokeResults, $patchKernelResults -Force -ErrorAction SilentlyContinue
}

Run the MCP server directly:

cd plugins/blendproof/mcp
uv run blendproof-mcp

For local plugin development, add this repository as a Codex marketplace and install its plugin:

codex plugin marketplace add /absolute/path/to/blender-max-power
codex plugin add blendproof@blendproof

Use a native absolute path in PowerShell as well. The bundled .mcp.json starts the local server from the plugin directory and requires uv on the Codex process PATH. Plugin packaging and extension installation instructions are tracked in docs/development.md.

MCP surface

BlendProof deliberately keeps orchestration small:

project_init       project_status       scene_query
capability_search  patch_create         patch_preview
patch_get          patch_commit         patch_rollback
branch_create      branch_compare       branch_merge
evidence_capture   asset_generate       job_get
job_cancel         script_stage

Every stateful request uses explicit project_id, branch_id, patch_id, or job_id handles. This avoids relying on transport sessions and supports both interactive and headless hosts.

The runtime defaults to a deterministic offline SceneTruth simulator so tests never launch Blender unexpectedly. To preview supported operations in a real isolated Blender worker, configure:

export BLENDPROOF_EXECUTION_MODE=blender
export BLENDPROOF_BLENDER_PATH=/absolute/path/to/blender

PowerShell:

$env:BLENDPROOF_EXECUTION_MODE = "blender"
$env:BLENDPROOF_BLENDER_PATH = "C:\Program Files\Blender Foundation\Blender 5.2\blender.exe"

The worker strips provider credentials from its environment, disables .blend auto-execution, uses the extension's allowlisted bridge, and returns structured errors rather than publishing a failed preview. The live bridge currently maps the safe static-creation subset; unsupported domains fail before launch.

Run the real Blender proof-pedestal preview with:

uv run --project plugins/blendproof/mcp python \
  examples/run_proof_pedestal.py --blender /absolute/path/to/blender

The same command works in PowerShell when written on one line.

Safety model

BlendProof is local-first and telemetry is off. Network access is not required for core scene work. Public-MCP asset_generate only stages Meshy/Tripo requests and cannot spend credits; remote CLI/internal submission additionally requires credentials and an externally issued grant bound to the exact request hash. Arbitrary Python is not a normal operation: script_stage only creates a reviewable, scanned artifact. The public MCP cannot approve or execute it.

A Blender-backed patch_commit re-hashes all bound CAS artifacts, publishes the accepted candidate under its SHA-256 name, and advances the branch head in one recoverable compare-and-swap transaction. patch_rollback similarly publishes the exact prior candidate or checkpoint and appends a new revision. Neither operation overwrites the user's working .blend. Repair gates are proof inputs, never permission for an automatic commit.

Do not open untrusted .blend files, scripts, extensions, or generated assets outside an isolated environment. Read SECURITY.md and the threat model before enabling providers or staged code.

License

The host-neutral core, plugin metadata, workflows, documentation, and CLI are licensed under the MIT License. Files under plugins/blendproof/blender-extension/ are separately licensed under GPL-3.0-or-later; see that directory's LICENSE. Contributions retain the license of the directory in which they are made. The path-level boundary is summarized in LICENSES.md.

Contributing

BlendProof is intentionally evidence-driven: new operations need typed schemas, failure tests, proof expectations, rollback behavior, and benchmark coverage. Start with CONTRIBUTING.md.