design-os-3d-blender

design:os · 3D Blender · agent operating system

An AI agent that builds parts natively in Blender, and shows its evidence.

Agent skills, a verified bpy knowledge base, an AGENT_OK / AGENT_FAIL execution contract and a production gate for Blender 5.2 LTS. Every worked build below ships with what was checked and what was not.

Live site · Worked builds · Install and use · Tools and skills · design:os ecosystem · Evidence boundaries

Native renders from the worked builds

DC-01 desktop companion	CK-001 reference keyboard	Robot arm

Rendered in Blender, no added captions or banners. Names, development status and evidence limits live next to each build. Media provenance · the full set on the live site.

Worked builds

Two builds ship a public review page with the delivered package beside it.

Mechanical products

Geothermal ORC components

ORC images are derivatives of native renders; their source models are not in this public checkout.

The plant layout uses an illustrative 1:15 scale. Catalogue dimensions and installation manuals support specific modeling decisions; they do not establish a selected vendor package, plant capacity or as-built engineering design. A component gallery is not evidence that the complete site has been integrated or qualified.

Reusable parts

Instrument families and mounting details show the parts shared across assemblies. Reuse requires a defined local origin, a mounting interface, supported parameters and verification in the receiving assembly.

Install and use

Requirements: Blender 5.2.x, Python 3.10+, macOS or Linux. The host-side tests use the Python standard library only.

1 · check the install. Point the scripts at your Blender binary, verify the knowledge catalogue, run the host tests.

git clone https://github.com/jangtrinh/design-os-3d-blender.git && cd design-os-3d-blender
export BLENDER_BIN=/Applications/Blender.app/Contents/MacOS/Blender
python3 scripts/blender-knowledge.py check
python3 -m unittest discover -s tests/execution

The rest of the host suites, and the contract tests that import bpy and therefore run inside Blender:

for suite in production-gate knowledge hq-coverage native-pipeline native-review pass-coverage; do
  python3 -m unittest discover -s "tests/$suite"
done
python3 -m unittest tests/boilerplates/test_parametric_contract.py
for t in animation geonodes evaluated_mesh; do
  bash scripts/headless-run.sh "tests/boilerplates/test_${t}_contract.py"
done

2 · run a pass headless. Every pass runs in an isolated Blender process and ends with a sentinel; success is AGENT_OK on the last line, never the exit code.

bash scripts/headless-run.sh my-pass.py

3 · or interactively over MCP. Open the blender-mcp addon in Blender's sidebar (N → BlenderMCP → Connect), then run the same pass through the runtime from your agent CLI. <ROOT> is the absolute path of this checkout.

import sys
sys.path.insert(0, "<ROOT>/scripts")
import agent_runtime as rt
rt.run_file("<ROOT>/builds/<slug>/pass-01.py")

4 · gate a printable part. Write the spec before detailing; the gate checks the scene against it and writes a report. A digital gate does not establish physical fit, load, pressure, thermal duty or a successful print.

mkdir -p builds/my-part && cp specs/examples/bracket-m3.spec.json builds/my-part/spec.json
python3 scripts/production-gate.py \
  --scene builds/my-part/part.blend \
  --spec builds/my-part/spec.json \
  --report builds/my-part/gate-report.json

See specification and gate behavior. Reading packs for a task come from the knowledge workbench:

python3 scripts/blender-knowledge.py list
python3 scripts/blender-knowledge.py route native-hard-surface --topic session-retrospective
python3 scripts/blender-knowledge.py route render-export-delivery --topic public-review-publication

Tools and skills

The .claude/skills directories mirror the local skill sources. Antigravity setup is in the setup guide. Vendored img2threejs keeps its Apache-2.0 license; production reconstruction uses native Blender geometry. Native agent iteration documents the reviewed Meshy, Dream-loop and Text-to-CAD mechanisms and their local implementations; the upstream hosted-generation, B-rep and device stacks are not installed.

The design:os ecosystem

This repository is the Blender member of design:os — one agent operating system per craft, each with its own knowledge base, gates and worked examples.

Evidence boundaries

The worked-build READMEs carry the detailed receipts and exclusions. The knowledge catalogue also includes small execution examples; the full private ORC development history and the source reference images are not shipped.

What the builds taught us

Both full product builds converged on one loop — build → numeric assert ending in the sentinel → immutable run directory → an independent re-open of the saved artifact → a named review report → freeze by SHA — and the incidents that cost the most are recorded with their evidence files:

1. Specify the construction. A wheel, cabinet or gauge name is an inventory item; a brief needs profile, thickness, transitions, layers, mounting and a visible condition that would reject the result.
2. Model and gate the mating interface before any presentation work. Missing receivers cost a whole revision of a finished-looking keyboard.
3. A sampled predicate is not a bound. Re-check at the exact extremes and both sides of every join: 3.198 mm sampled, 2.9964 mm true.
4. Motion belongs in the media contract. A film that renders 120 poses at 5 poses per second passes every gate and still fails the owner.
5. Verify the artifact and the verifier. A surprising measurement gets a disproving probe before any geometry changes; qualify a renderer by pixel identity, never by speed.
6. Bind delivery to the actual revision. Freeze source, camera and settings, keep old media under its own identity, and record manual checks separately from automated gates.

Read the two-build distillation, the CK-001 retrospective, the ORC component lessons with their public journal, and start a new project from the product workflow template. Specialised reading: geometry diagnosis, native media delivery, manufacturing evidence, publishing a review page.

The C03/E02 source package adds full-stroke cap clearance, mechanical retention, acrylic collars, corrected LED polarity and an explicitly incomplete physical pilot ledger. The public Revision-B gallery remains historical media for B, not an approval of C03.

License

MIT. Vendored dependencies retain their own licenses.