Skip to content
Back to search

construct

Holographic constructs any AI agent can build: from a description, honestly.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/rtmandreyev/construct with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/rtmandreyev/construct'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rtmandreyev--construct/badge.svg)](/listings/rtmandreyev--construct)

HTML

<a href="/listings/rtmandreyev--construct"><img src="/api/listings/rtmandreyev--construct/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Construct runs from a copy of this repository; there is nothing to install system-wide. Clone it and build the skills for your agent:

git clone https://github.com/rtmandreyev/construct.git
cd construct
python3 construct_hologram/package.py --out dist    # builds the Claude Code and Hermes skills

Then add the skill to your agent, or use Construct directly:

| Host | How to add it | | --- | --- | | Claude Code | `claude --plugin-dir dist/claude-code/construct` for one session, or copy `dist/claude-code/construct/skills/construct` into `.claude/skills/` | | Hermes | `hermes skills install rtmandreyev/construct/skills/construct`, or copy `dist/hermes/construct` into `~/.hermes/skills/` | | Any MCP client | Add `{"mcpServers": {"construct": {"command": "python3", "args": ["/path/to/construct/construct_hologram/server.py"]}}}` | | Any OpenAI-compatible model | `python3 construct_hologram/cli.py author "..." --base-url ... --model ... --key-env ... --out scene.json` | | By hand | The command line below; no model needed |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 471 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Construct
  2. **Give your agent the thing, not another picture of it.**
  3. https://github.com/user-attachments/assets/8c39a196-9910-46a0-9746-4f15965adf15
  4. <p align="center"><sub>Construct in Hermes Agent, in 90 seconds. It works the same way in Claude Code, any MCP client, any OpenAI-compatible endpoint, or the Claude and ChatGPT apps.</sub></p>
  5. **Construct is a tool for AI agents. It turns everything that can be found out about a thing into one exact,
  6. checked description of it: its named parts at their real sizes, how they fit together, open and move, and how
  7. each one is known, measured or guessed.** An agent does the research and writes the description. Construct
  8. checks it and builds from it, and the same description always gives the same result. Put constructs together and
  9. they make a **world**: a room, a street, a whole game level. Inside a world every construct is still whole, with
  10. its own parts, sources and joints, so you can move, reuse or open any of it.
  11. **Describe a thing, or show a place, and your agent makes one construct of it: an object it can keep working
  12. with.** Everything else is a use of that one object: an animated model in lines of light, in the **Measured Light**
  13. style (a single web page you can open anywhere, honest about what is known), a 3D model with named parts and working
  14. joints, stills and films, a print, a model kit, a CAD file, or one piece of a world made with others. Change a part
  15. and rebuild, and every one of them follows.
  16. A world can be asked for in plain words, put together from constructs you already have, or made from a single
  17. picture. Given one picture of a place, it builds the place zero-shot. [Stortorget](examples/worlds/stortorget/),
  18. Stockholm's old square, was made from a single photograph and stands almost exactly as the photograph shows it.
  19. [Rain Harbour](examples/worlds/rain-harbour/) is a game level made from one concept picture, ready to open in Godot,
  20. Unity or Unreal. And a world comes apart again, construct by construct: rearrange it by hand in Hermes, or take any
  21. one construct out to open, export or reuse on its own.
  22. <p align="center">
  23. <a href="https://rtmandreyev.github.io/construct/examples/sainte-chapelle/"><img src="docs/media/assembly-sainte-chapelle.gif" width="32%" alt="The Sainte-Chapelle construct assembling itself"></a>
  24. <a href="https://rtmandreyev.github.io/construct/examples/kestrel/"><img src="docs/media/assembly-kestrel.gif" width="32%" alt="KESTREL, an invented ice tug, assembling itself, its cradle arms opening and radiator wings folding"></a>
  25. <a href="https://rtmandreyev.github.io/construct/examples/toyota-land-cruiser-fj62/"><img src="docs/media/assembly-toyota-land-cruiser-fj62.gif" width="32%" alt="The Toyota Land Cruiser FJ62 construct assembling itself"></a>
  26. </p>
  27. <p align="center">
  28. <a href="https://rtmandreyev.github.io/construct/worlds/rain-harbour/"><img src="docs/media/world-rain-harbour.gif" width="32%" alt="Rain Harbour assembling as a world: the towers of a night street, its neon signs in English and Chinese, then the hero car"></a>
  29. <a href="https://rtmandreyev.github.io/construct/worlds/the-shed/"><img src="docs/media/world-shed.gif" width="32%" alt="The shed and the things around it assembling as a world: the shed with its deck and log store, the VW T1 Samba and the Vespa"></a>
  30. <a href="https://rtmandreyev.github.io/construct/worlds/stortorget/"><img src="docs/media/world-stortorget.gif" width="32%" alt="Stortorget assembling as a world from the photograph's viewpoint: the gabled houses, the Christmas tree, the lamp and the rows of market stalls"></a>
  31. </p>
  32. <p align="center"><sub><b>Constructs</b> (top): the Sainte-Chapelle and the Toyota Land Cruiser FJ62 by Claude Opus 5.5, KESTREL, an
  33. invented ice tug, by GPT-6.1 Sol, each in masterpiece mode. <b>Worlds</b> (below): Rain Harbour, a game level, and Stortorget at
  34. Christmas, each made by GPT-6.1 Sol from one picture; the shed and the things around it, made of constructs from the
  35. gallery. <a href="https://rtmandreyev.github.io/construct/">Open the gallery</a> to orbit them, replay the
  36. assembly and read the labels; <a href="docs/for/invent-from-what-exists.md">how KESTREL was made</a>,
  37. <a href="examples/worlds/stortorget/">how Stortorget was made</a>.</sub></p>
  38. - **Construct for Hermes.** A native Hermes plugin. Ask for a thing in plain words and the construct appears live in the chat, with its 3D model, kit and NetLogo runs beside it. You can also place your constructs together into worlds. `hermes plugins install rtmandreyev/construct#hermes/construct` ([what it does](hosts/hermes/construct/README.md), [Villa Savoye in Hermes, step by step](docs/for/hermes-walkthrough.md), [worlds, step by step](docs/for/worlds-walkthrough.md)).
  39. - **Every piece stays separate.** In a world made from one picture you can still handle each construct on its own: move a car, turn a tower, swap the signs, open a door on its hinge, export it to Blender or Godot, or reuse a building in another level ([Rain Harbour, before and after](examples/worlds/rain-harbour/#changed-by-hand)).
  40. - **Any agent, any model.** Claude Code, Hermes, any MCP client or any OpenAI-compatible endpoint, or by hand.
  41. - **Honest about what is known.** Every part says how it is known, for its size and its shape separately, and every guess is shown in a shade of how firmly it is held. [What each mark means](docs/PROVENANCE.md).
  42. - **One house style.** Models never choose the colours, so every construct looks like it belongs with the rest.
  43. - **It repairs itself.** Every problem comes back with where it is and how to fix it.
  44. - **Nothing to install.** It needs only Python's standard library and a browser. There are no API keys and no network service inside Construct.
  45. ## Find your path
  46. | You… | Construct gives you | Start here |
  47. | --- | --- | --- |
  48. | ***Everyday*** | | |
  49. | want a model of **anything you can describe** | A thing you describe, as a construct you can turn, replay and share | [Make a construct](docs/for/anyone.md) |
  50. | want a **digital copy of something you own** | Your chair, guitar, camera or heirloom in 3D from your photos and whatever its maker publishes, showing what was measured and what was guessed | [Copy your thing](docs/for/copy-your-thing.md) |
  51. | are planning a change to your **home or garden** | Your shed, room or garden as a model to try the change on first: a deck, shelves, an extension, a new layout. A planning model, not a survey | [Try it on a copy](docs/for/home-and-garden.md) |
  52. | want to customise or restore a **vehicle** | Your car, bike or scooter from its published sizes and your photos, your parts told apart from the factory's: try wheels or a new colour, plan a restoration, make a model of it | [Your vehicle](docs/for/your-vehicle.md) |
  53. | need a part that is **missing or broken** | A knob, bracket or cover drawn to the thing it fits, as a print or a CAD file someone can make | [Make the part](docs/for/replace-a-part.md) |
  54. | want **a place from a photo**: a square, a street, a building, your neighbourhood | One photograph is enough to start (Stortorget, from one); more pictures make it closer, up to a digital twin, house by house, each part saying how it is known | [Stortorget, start to finish](examples/worlds/stortorget/) |
  55. | want **your things together in one place** | Your house with your furniture, your car and scooter under it, a ship over the roof: whole constructs placed at real size, arranged by asking or by hand | [Worlds, step by step](docs/for/worlds-walkthrough.md) |
  56. | want a **model kit of your own thing** | Your scooter, house or guitar as a kit to print, glue and paint, with a booklet ([one to open](https://rtmandreyev.github.io/construct/examples/vespa-gs150/kit/assembly.html)) | [A kit of your own](docs/for/a-kit-of-your-own.md) |
  57. | want to **show someone what you mean** | A model a builder, a fabricator or a friend can turn and measure, and a file for their own tools | [Show what you mean](docs/for/show-what-you-mean.md) |
  58. | ***Professionals and creators*** | | |
  59. | are a **maker** with a printer or CAD | A construct as one checked print at your printer's largest size (Tompion's clock: 21 cm on a desktop printer, 10½ hours in PrusaSlicer), a model kit with plates, a booklet and its steps in 3D ([five to open](https://rtmandreyev.github.io/construct/#kits)), and true CAD shapes in FreeCAD and STEP | [Print, kit, CAD](docs/for/makers.md) |
  60. | create **new ships, creatures or places** for a game, film or story | New things designed from real ones: a construct, a 3D model with working parts, a film ([see KESTREL](https://rtmandreyev.github.io/construct/examples/kestrel/), an invented ice tug) | [New things from real ones](docs/for/invent-from-what-exists.md) |
  61. | have **software or a documented system** you wish were a physical product | Its documented functions mapped to controls, displays and the parts inside, what the documents fix kept apart from what is designed (one worked example: a software synthesizer as a 61-key instrument) | [Documentation → product](docs/for/documentation-to-product.md) |
  62. | are a **game developer** | Props in named parts at their real size, with doors and lids on working hinges in Godot, FBX for Unity and Unreal; models of what your game needs instead of stock ones; a whole level from one concept picture ([Rain Harbour](examples/worlds/rain-harbour/): 21 constructs placed 50 times, a hero car, one command to a Godot map) | [Into a game engine](docs/for/game-developers.md) |
  63. | are a **3D artist** | A construct or a whole world in Blender with its build, joints, metal and finish on sliders, painted from a small material map ([the Villa Savoye](examples/villa-savoye/), 396 parts, and [the Villa lived in](https://rtmandreyev.github.io/construct/worlds/villa-savoye-lived-in/), a world of 13, rendered in Cycles); OBJ in quads to model over; FBX and USD | [Into Blender](docs/for/3d-artists.md) |
  64. | make **images or a visual identity** | Designed objects that stay the same from every camera and in every medium, instead of being redrawn for each picture, and that can be combined: stills, profile pictures, loops, a film's sets and screens ([Sonastra](docs/MADE-WITH-CONSTRUCT.md#sonastra): the starship ARGUS in Spotify images and Canvas loops, and in a film as a hologram, a technical drawing and a studio model) | [Made with Construct](docs/MADE-WITH-CONSTRUCT.md) |
  65. | work in **film and motion** | A construct that assembles across your track, pausing, surging and flaring with the music, shimmering with a vocal stem ([three films](https://rtmandreyev.github.io/construct/#films)); keyed reveals in Blender; a world's named views as shots | [Film mode](docs/for/film-and-motion.md) |
  66. | are an **educator or researcher** | An agent-based model's run drawn as a construct, compared, printed, filmed | [Models come alive](docs/for/educators-and-researchers.md) |
  67. | work in a **museum or archive** | Reconstructions where every part says how it is known (measured, traced, seen in a photo, designed), sources cited and the critic's verdict kept: [Tompion's clock](https://rtmandreyev.github.io/construct/examples/tompion-year-going-clock/) from the Royal Collection's record, [Stortorget](examples/worlds/stortorget/) house by house | [Honest reconstructions](docs/for/museums-and-archives.md) |
  68. | are a **developer** | A scene contract that is data, a check that returns each problem with its path and a fix, the same scene always built the same; a command line, an MCP server, skills, and a Hermes plugin with thirteen tools (`construct_world`, `construct_export`…) | [Build on it](docs/for/developers.md) |
  69. ## New in 1.3
  70. Every change with pictures and the commands to try it: **[What's new in 1.3, a walkthrough](docs/NEW-IN-1.3.md)**.
  71. - **Worlds.** Whole constructs placed together in one scene, each keeping its own parts. Put your chair, clock and
  72. synthesizer in your house, your cars under it and a ship over the roof, or build a street, a market square or a game
  73. level. The world's audit says what overlaps, what runs into the house it stands in, and what stands where a door
  74. opens. Six worlds ship to start from. [Worlds, step by step](docs/for/worlds-walkthrough.md) · [the format](docs/WORLDS.md)
  75. - **A world from a picture, in masterpiece mode.** Attach a photo or a concept picture. Hermes plans the pieces,
  76. builds each new construct in its own masterpiece rounds with a fresh critic and places them at real size. Then it
  77. runs the world itself through rounds against the picture. Two worlds were made this way, each from one picture:
  78. [Rain Harbour](examples/worlds/rain-harbour/), a game level, and [Stortorget](examples/worlds/stortorget/),
  79. Stockholm's old square at Christmas.
  80. - **Arranged by hand in Hermes.** Use Arrange on a world's card to drag a construct onto any floor, table or roof,
  81. turn it or lift it, add one from the library, and save, all without calling a model. There is a Worlds tab, with
  82. groups of your own and previews. The plugin ships 24 constructs (16 in 1.2.1) and all six worlds, the two from pictures with their artwork. A level
  83. made from one prompt can be remade by hand: [Rain Harbour, before and after](examples/worlds/rain-harbour/#changed-by-hand).
  84. - **More ways out.** FBX, USD and USDZ (through Blender); a Godot game map, where everything that stays put is one
  85. static body and every hinged or sliding part moves on its own joint; and the Blender add-on imports a world. Every construct now finishes with its own material map, which every export uses by
  86. default, and its artwork (signs, labels, screens) exports as textures in glTF and OBJ.
  87. - **Sturdier masterpiece rounds**, from two long runs: ties recorded, artwork kept in checkpoints, references
  88. carried from round to round, more time on request (`rounds extend`), colour judged in the solid view.
  89. <details>
  90. <summary><b>New in 1.2</b></summary>
  91. Every change with pictures and the commands to try it: **[What's new in 1.2, a walkthrough](docs/NEW-IN-1.2.md)**.
  92. - **Construct for Hermes.** A native Hermes plugin: ask for a thing in plain words, and the construct appears live in
  93. the chat; the 3D model turns in it, a kit steps through in 3D, exports are read back and summarised, long work runs
  94. in the background. `hermes plugins install rtmandreyev/construct#hermes/construct` ([what it does](hosts/hermes/construct/README.md)).
  95. Tested on Villa Savoye, from the request to a printable kit: [step by step →](docs/for/hermes-walkthrough.md)
  96. - **New things from real ones.** [KESTREL](docs/for/invent-from-what-exists.md), an invented 120 m ice tug, from
  97. its brief to its joints in Godot: the studies it reasoned from, thirteen masterpiece rounds, then a more detailed
  98. version that kept all 256 parts and added 242. Both in the gallery, Apache-2.0, with every brief.
  99. - **Documentation → product.** A software synthesizer's 354-page manual made into a 61-key instrument concept in one
  100. 64-minute session, with the prompt and the documents it wrote, and plainly what it showed and what it did not.
  101. [The walkthrough →](docs/for/documentation-to-product.md)
  102. - **Designed to a requirement.** A designed part names the requirement it realises (what you asked for, or what a
  103. document says it does) and stays honestly designed; a new design is captioned ORIGINAL DESIGN.
  104. - **Checked harder.** A part that would tip over (`tips`), a pillar through a window (`crosses-glass`), a solid
  105. left open (`open`), a number in the text that no longer matches its fact (`stale-number`), and pokes confirmed
  106. four times finer.
  107. - **A critic that stands apart.** Sealed critic packets with only the renders, the references and your request; a
  108. blind verdict cannot be rewritten.
  109. - **Cleaner 3D, bigger constructs.** Solids wound outward, so Blender's normals and booleans agree; up to 1,024
  110. parts and 48,000 lines; glued joints inside joints for Godot; kit boards that lie flat.
  111. </details>
  112. <details>
  113. <summary><b>New in 1.1</b></summary>
  114. Every feature with pictures and the commands to try it: **[What's new in 1.1, a walkthrough](docs/NEW-IN-1.1.md)**.
  115. And one construct taken through all of it, step by step: **[A longcase clock, end to end](docs/END-TO-END.md)**.
  116. - **Your own formats.** Adapters: what a construct holds, where to read it and the rules that keep an adapter
  117. honest, with a template that writes a parts sheet and an STL per part. [Write your own →](docs/ADAPTERS.md)
  118. - **Honest in finer shades.** A part's size and its shape known apart, every guess in a shade of how firmly it is
  119. held. Press **P**.
  120. - **See it as a solid.** Press **S** in any construct; `check --fit` names what pokes through or floats.
  121. - **Contact you can trust.** `check` follows support through the solids, not their boxes: a part that only seems
  122. to rest on another, or hangs on a wire-thin strut, is named with the gap and the part to rest it on. Found from a
  123. desk fan two models built; it closed three gaps in the gallery.
  124. - **Cleaner 3D.** Smoother solids, OBJ that subdivides cleanly, triangle quality reports, for Blender and any
  125. 3D program.
  126. - **Ready for game engines.** Glued pieces with working hinges for Godot, pieces that break apart and settle,
  127. colliders, seeded variants.
  128. - **CAD.** True CAD shapes in FreeCAD, with their joints, and STEP for any CAD program.
  129. - **Prints.** One checked print at the largest size your printer takes, voxel or exact, with engraved line art.
  130. - **Model kits.** A construct as a kit to print, glue and paint: numbered plates, a booklet drawn as a kit sheet,
  131. the same steps in 3D, every piece printable on its own. A first version, not yet built by a person.
  132. - **Models come alive.** A NetLogo extension: one command in NetLogo turns a run into a construct, with a replay
  133. bar, a legend and a *How to read it* panel, in views chosen for the data. Runs side by side for a lesson, a
  134. printable worksheet, CSV and *Cite this run*; a run as a film or a 3D model in Blender, or as plates you can
  135. stack. 388 of the Models Library's 445 models record with no edits.
  136. </details>
  137. ## Examples
  138. **Worlds.** Rain Harbour and Stortorget were each made in Hermes from one picture and one request, zero-shot. Rain
  139. Harbour is a game level from a concept picture: 21 constructs placed 50 times, every sign in real English and
  140. Chinese, and a drivable hero car. Stortorget comes from one photograph of Stockholm's old square: eight real houses
  141. researched one by one, one market stall placed 41 times, and the tree, all standing almost exactly as the photograph
  142. shows them. The Villa Savoye, lived in, is made of your own constructs: the house with its furniture, a Braun, a
  143. Revox, a Leica, SERUM, an FJ62 and a DB5 under the pilotis, and KESTREL far off over the roof. [Worlds, step by step →](docs/for/worlds-walkthrough.md)
  144. <p align="center">
  145. <a href="examples/worlds/rain-harbour/"><img src="examples/worlds/rain-harbour/blender-street.jpg" width="98%" alt="Rain Harbour in Blender at night: a wet street between towers, neon signs in English and Chinese reflected in the road, the yellow hero car"></a>
  146. </p>
  147. <p align="center">
  148. <a href="examples/worlds/stortorget/"><img src="examples/worlds/stortorget/reference.jpg" width="49%" alt="The photograph Stortorget was made from: the red and orange gabled houses over rows of red Christmas market stalls and a tall spruce"></a>
  149. <a href="examples/worlds/stortorget/"><img src="examples/worlds/stortorget/blender-photo.jpg" width="49%" alt="Stortorget made from that photograph, in Blender at dusk: the same houses, stalls and spruce from the same place"></a>
  150. </p>
  151. <p align="center"><sub>Left, the one photograph Stortorget was asked from (Ximonic, CC BY-SA 4.0); right, the world made from
  152. it, rendered from the same place.</sub></p>
  153. <p align="center">
  154. <a href="https://rtmandreyev.github.io/construct/worlds/villa-savoye-lived-in/"><img src="docs/media/worlds/blender-villa-dusk.jpg" width="49%" alt="The Villa Savoye, lived in, in Blender at dusk: the Land Cruiser and the DB5 under its pilotis, KESTREL high over the roof"></a>
  155. <a href="https://rtmandreyev.github.io/construct/worlds/villa-savoye-lived-in/"><img src="docs/media/worlds/blender-villa-table.jpg" width="49%" alt="Inside the Villa: a Revox A77, a Braun SK 4 and a Leica M3 on a table in the salon"></a>
  156. </p>
  157. <p align="center"><sub>Every world as it ships, imported into Blender with Construct's add-on, each construct finished
  158. with its own material map.</sub></p>
  159. **Provenance and solids.** On the left, the Duomo di Milano in provenance shades (**P**): verified sizes in cyan, traced
  160. shapes in blue, and every guess a deeper amber the more firmly it is held. On the right, the same Duomo as a solid (**S**),
  161. the way a modelling program shows it. [Museums and archives →](docs/for/museums-and-archives.md)
  162. <p align="center">
  163. <img src="docs/media/provenance-shades-duomo.jpg" width="49%" alt="The Duomo di Milano in the provenance view: verified sizes in cyan, traced parts in blue, inferred parts in shades of amber, with the legend counting each">
  164. <img src="docs/media/solid-duomo.jpg" width="49%" alt="The Duomo di Milano as a solid in its marble, the Madonnina gilded, from the same view">
  165. </p>
  166. **Film mode.** A construct assembling across a piece of music. [Film and motion →](docs/for/film-and-motion.md)
  167. <p align="center">
  168. <a href="https://rtmandreyev.github.io/construct/films/james-webb-space-telescope/"><img src="docs/media/film-james-webb-space-telescope.gif" width="32%" alt="The James Webb Space Telescope assembling across a piece of music"></a>
  169. <a href="https://rtmandreyev.github.io/construct/films/voyager-1/"><img src="docs/media/film-voyager-1.gif" width="32%" alt="Voyager 1 assembling across a piece of music"></a>
  170. <a href="https://rtmandreyev.github.io/construct/films/arecibo-observatory/"><img src="docs/media/film-arecibo-observatory.gif" width="32%" alt="The Arecibo Observatory assembling across a piece of music"></a>
  171. </p>
  172. **Game engines and Blender.** The FJ62 in Godot, knocked apart into its pieces, and the same car going from light to a finished model. [Game developers →](docs/for/game-developers.md) · [3D artists →](docs/for/3d-artists.md)
  173. <p align="center">
  174. <img src="docs/media/godot-fj62-pieces.gif" width="49%" alt="The Toyota Land Cruiser FJ62 in Godot, falling apart into its pieces and settling">
  175. <a href="https://rtmandreyev.github.io/construct/examples/light-to-metal/"><img src="docs/media/pipeline-fj62.gif" width="49%" alt="The FJ62 from lines of light to a plain model of named parts, then the finished model in paint, chrome and glass"></a>
  176. </p>
  177. **Prints and CAD.** An exact print of the FJ62 beside its voxel print; the Yamaha CFX and the Leica M3 in FreeCAD. [Makers →](docs/for/makers.md)
  178. <p align="center">
  179. <img src="docs/media/print-exact-fj62.jpg" width="49%" alt="The FJ62 printed as voxels and as an exact print">
  180. <img src="docs/media/freecad-piano-leica.jpg" width="49%" alt="The Yamaha CFX and the Leica M3 in FreeCAD as true CAD shapes">
  181. </p>
  182. **Model kits.** Four constructs as kits to print, glue and paint: the Yamaha CFX piano (1:12, 54 pieces), Tompion's year-going clock (1:12, 34 pieces), the VW T1 Samba (1:16, 98 pieces) and an owner's Vespa GS 150 (1:12, 28 pieces), each with its steps in 3D and a booklet to print. Open them in your browser, or download their plates: [the kits in the gallery](https://rtmandreyev.github.io/construct/#kits). [Makers →](docs/for/makers.md)
  183. <p align="center">
  184. <a href="https://rtmandreyev.github.io/construct/examples/yamaha-cfx/kit/assembly.html"><img src="docs/media/kit-cfx-guide.gif" width="32%" alt="The Yamaha CFX piano kit's 3D guide at 1:12: the keyboard built at the bench, the piano ghosted around it"></a>
  185. <a href="https://rtmandreyev.github.io/construct/examples/tompion-year-going-clock/kit/assembly.html"><img src="docs/media/tompion-kit-guide.gif" width="32%" alt="Tompion's year-going clock as a 1:12 kit: its fifteen steps in 3D, the dial plate built at the bench"></a>
  186. <a href="https://rtmandreyev.github.io/construct/examples/volkswagen-t1-samba/kit/assembly.html"><img src="docs/media/kit-vw-guide.gif" width="32%" alt="The Volkswagen T1 Samba as a 1:16 kit: from the floor pan, through the cab and body at the bench, to the finished bus"></a>
  187. </p>
  188. <p align="center">
  189. <a href="https://rtmandreyev.github.io/construct/examples/yamaha-cfx/kit/booklet.html"><img src="docs/media/kit-cfx-booklet.jpg" width="49%" alt="Step 3 of the CFX kit in the paper booklet: the keybed built at the bench, each piece numbered and painted polished ebony, drawn exploded"></a>
  190. </p>
  191. **NetLogo runs.** A simulation's whole run as a construct, time as its height. [Educators and researchers →](docs/for/educators-and-researchers.md)
  192. <p align="center">
  193. <a href="https://rtmandreyev.github.io/construct/examples/netlogo-flocking/"><img src="docs/media/netlogo-flocking.gif" width="32%" alt="Flocking: each bird's track rising with time, random near the floor and in parallel streams higher up"></a>
  194. <a href="https://rtmandreyev.github.io/construct/examples/netlogo-wolf-sheep/"><img src="docs/media/netlogo-wolf-sheep.gif" width="32%" alt="Wolf Sheep Predation: the predator-prey cycle rising in time"></a>
  195. <a href="https://rtmandreyev.github.io/construct/examples/netlogo-fire/"><img src="docs/media/netlogo-fire.gif" width="32%" alt="Fire: the fire's front rising as it crosses the forest"></a>
  196. </p>
  197. **Beyond objects.** The same visual language works for ideas and data. Here a classic NetLogo agent-based model, Uri
  198. Wilensky's *Simple Viral Marketing*, was rebuilt to run live in the browser and drawn as a construct: five hundred
  199. people, one product, word of mouth and a little advertising. The floor is the social network, and each person rises
  200. to the moment they adopted, so you can watch an idea spread and see who it reaches last, and why.
  201. <p align="center"><a href="https://rtmandreyev.github.io/construct/examples/netlogo-viral-marketing/"><img src="docs/media/netlogo-viral-marketing.gif" width="100%" alt="The Simple Viral Marketing model running: adoptions spread through the social network on the floor and rise as lines of light, the gold ring marking now, while the counters climb to 500 of 500"></a></p>
  202. <p align="center"><sub><a href="https://rtmandreyev.github.io/construct/examples/netlogo-viral-marketing/">Open the live model</a> to build new networks, run them tick by tick and compare a hundred runs with NetLogo's own. The model is © 2012 Uri Wilensky; this example is under CC BY-NC-SA 3.0 (see <a href="#license">License</a>).</sub></p>
  203. ## Used beyond the gallery
  204. - **[Sonastra](https://open.spotify.com/artist/2sZD4kxpyZt6QhkxhXZLEt)** is the author's music project, and Construct
  205. runs through its visual identity for the album *Unseen/Seen* and its film. The same constructs appear in the
  206. Spotify gallery, the Canvas loops and the film's Blender scenes, as holograms, technical drawings and on-screen
  207. graphics. The starship ARGUS shows it best: one construct, seen as a gallery image, a hologram over a cabin
  208. projector, a general-arrangement drawing on the wall, a studio model on a lab bench and a ship on the film's
  209. displays. Its lander docks to it and stays a construct of its own. Every picture is a new camera on the same object,
  210. not a new generation. The gallery, the Canvas loops and the film are all on the
  211. [Made with Construct](docs/MADE-WITH-CONSTRUCT.md#sonastra) page.
  212. - **[CUDA Compatibility](https://cudacompat.com)** runs newer CUDA on older NVIDIA GPUs. The project is about GPUs, not
  213. Construct, but its site opens on a construct of its GM200 reference card assembling itself, part by part.
  214. <p align="center"><a href="docs/MADE-WITH-CONSTRUCT.md#sonastra"><img src="docs/media/sonastra-argus.jpg" width="100%" alt="Sonastra's starship ARGUS, one construct six ways: a Spotify gallery image in lines of light, its general-arrangement drawing, a hologram over a cabin projector, a studio model on a lab bench, VELA's recon display, and docked with its lander over a planet's rim"></a></p>
  215. <p align="center"><sub>One ARGUS, six ways. Top: a Spotify gallery image, the general-arrangement drawing and the hologram
  216. from <i>Void Drift</i>. Below: the studio model in <i>Arrival</i>, the recon display in <i>The Source</i> and the gallery's
  217. <i>Safe Harbor</i>, docked with its lander.</sub></p>
  218. ## How it works
  219. A scene is data, never code: the agent says what the thing is, and Construct decides how it
  220. looks. That split is what keeps every construct honest and in one style. In masterpiece mode the
  221. review becomes a loop, judged by a critic that never saw the authoring.
  222. ```mermaid
  223. flowchart LR
  224. A["you ask"] --> S["the agent writes<br/>a scene"]
  225. S --> C["Construct<br/>checks it"]
  226. C -- "problems, with fixes" --> S
  227. C --> B["Construct builds<br/>construct.html"]
  228. B --> R["the agent reviews<br/>its pictures"]
  229. R -- "masterpiece: another round" --> K["the critic compares<br/>with the best so far"]
  230. K -- "better: keep it" --> S
  231. K -- "not better: keep the best" --> S
  232. R --> D["you get the best version"]
  233. ```
  234. - **You can see how each part is known.** Press **P** in any construct and every part is coloured
  235. by whether it is verified, supplied by you, inferred or decorative. Press **S** to see it as a solid,
  236. the way a modelling program or a print shows it.
  237. - **The check runs to zero.** Floating parts, claims without evidence and details too fine to see
  238. are reported, with fixes, before anything is built.
  239. - **The critic is independent.** It is a fresh model that compares each new version with the best
  240. so far without knowing which is which. Only a better version is kept.
  241. - **Masterpiece stops when it stops improving:** after two rounds without a better version, after
  242. 12 rounds, or after two hours. In the author's own blind comparisons, on two subjects, there was
  243. no visible improvement after about round 12, so more rounds mostly cost time.
  244. <p align="center"><img src="docs/media/rounds-sainte-chapelle.jpg" alt="The Sainte-Chapelle at round 1, round 8 and round 15 of a long run: the flèche gains its tiers, and the window tracery, buttresses and pinnacles fill in"></p>
  245. <p align="center"><sub>The critic at work: the Sainte-Chapelle at rounds 1, 8 and 15 of a run by Claude Opus 5.5, made before masterpiece had its 12-round cap. The flèche gains its tiers, and the window tracery, buttresses and pinnacles fill in.</sub></p>
  246. The whole process, with a construct improving round by round, is in
  247. **[How a construct is made](docs/HOW-IT-IS-MADE.md)**. What you see in a construct, and why
  248. models never choose its colours, is in **[The Measured Light style](docs/STYLE.md)**.
  249. ## Install
  250. Construct runs from a copy of this repository. There is nothing to install system-wide. Clone it
  251. and build the skills for your agent:
  252. ```sh
  253. git clone https://github.com/rtmandreyev/construct.git
  254. cd construct
  255. python3 construct_hologram/package.py --out dist # builds the Claude Code and Hermes skills
  256. ```
  257. Then add the skill to your agent, or use Construct directly:
  258. | Host | How to add it |
  259. | --- | --- |
  260. | Claude Code | `claude --plugin-dir dist/claude-code/construct` for one session, or copy `dist/claude-code/construct/skills/construct` into `.claude/skills/` |
  261. | Hermes, the plugin | `hermes plugins install rtmandreyev/construct#hermes/construct`: thirteen tools, the construct live in the chat, worlds, 3D models, kits and NetLogo runs in Hermes Desktop ([Construct for Hermes](hosts/hermes/construct/README.md)) |
  262. | Hermes, the skill alone | `hermes skills install rtmandreyev/construct/skills/construct`, or copy `dist/hermes/construct` into `~/.hermes/skills/` |
  263. | Any MCP client | Add `{"mcpServers": {"construct": {"command": "python3", "args": ["/path/to/construct/construct_hologram/server.py"]}}}` |
  264. | Claude Desktop, the MCP server | Open the `.mcpb` file from the [latest release](https://github.com/rtmandreyev/construct/releases/latest): Claude Desktop installs it with a double-click (Python 3.10 or newer) |
  265. | Any OpenAI-compatible model | `python3 construct_hologram/cli.py author "..." --base-url ... --model ... --key-env ... --out scene.json` |
  266. | By hand | The command line below; no model needed |
  267. | Blender | `python3 scripts/build_blender_extension.py`, then **Edit → Preferences → Get Extensions → Install from Disk** with the zip in `dist/` |
  268. ## Quick start
  269. **In the Claude or ChatGPT app, no terminal.** Download Construct, give the app its folder and your photos, and ask.
  270. The Claude app's Cowork and the ChatGPT app's Codex both read the skill and build the construct for you.
  271. [Construct in the Claude or ChatGPT app →](docs/for/in-the-apps.md)
  272. **In your agent,** just ask in plain words: *"a masterpiece of the Sydney Opera House"*, or *"a masterpiece
  273. construct of my guitar from these photos"*. The agent does the rest and tells you what it is doing. The
  274. constructs at the top of this page were all made in masterpiece mode, rounds judged by a second, independent model:
  275. ask for it for anything you care about.
  276. To try Construct without a model, fill in a ready-made template by hand:
  277. ```sh
  278. C=construct_hologram/cli.py
  279. python3 $C params book --variant paperback --output book.json # fill in the facts you know
  280. python3 $C check book.json # audit: PASS, or paths and fix hints
  281. python3 $C build book.json --out out # out/construct.html: open it in any browser
  282. python3 $C review book.json --out out # out/review/*.png: stills to judge it by
  283. ```
  284. Once a construct is open, drag to orbit and scroll to zoom. **R** replays the assembly, **L** shows
  285. the labels, **T** hides the text on its surfaces, **P** shows how each part is known, **S** shows it as a solid,
  286. and **1**–**6** move between views.
  287. ## Modes
  288. A mode sets how much effort goes into a construct. Say one in your request, or say nothing and
  289. the skill picks one and tells you why before it starts.
  290. | Mode | What it does | When it stops | Rough cost | Use it for |
  291. | --- | --- | --- | --- | --- |
  292. | **fast** | One pass with self-review | About 10 minutes (30 for a richer subject) | Cents with DeepSeek V4.1 Flash | Generic subjects, simple objects, quick requests |
  293. | **masterpiece** | Rounds judged by an independent critic, each version compared with the best so far | Two rounds without a win, 12 rounds, or 2 hours of active work | Up to 2 hours of frontier-model tokens | A named car, landmark or building whose likeness matters |
  294. | **timeboxed** | Masterpiece in 2 hours in all: the critic's time counts too | Two rounds without a win, 12 rounds, or 2 hours in all | Up to 2 hours, fewer rounds when the critic is slow | When you want masterpiece done within two hours |
  295. | **unbounded** | The same rounds, with no cap and no time limit | Only after two rounds without a win | Many rounds and hours, a high token cost | Only when you ask for it by name |
  296. Masterpiece's two hours count only the agent's own work. The critic's turns come on top, so a
  297. run with a slow critic can take three hours or more. **timeboxed** stops at two hours in all. The
  298. skill never picks timeboxed or unbounded on its own, because the critic finds an improvement almost every
  299. round, so a run can go on for hours. Every round is reported, so you can stop it whenever you like.
  300. ## Models
  301. Any capable model can make a construct, but some subjects need a stronger one. From the
  302. evaluation runs:
  303. - **Named subjects in masterpiece mode** (a car model, a landmark): a Sol or Opus class model
  304. (tested: GPT-6.1 Sol, Claude Opus 5.5). A smaller model given such a subject says so and
  305. recommends them.
  306. - **Simpler objects in fast mode:** DeepSeek V4.1 Flash does as well as those on objects such as a
  307. tape deck, a watch or a camera (a toy xylophone with its own finish map: about nine minutes).
  308. - **Worlds:** placing and arranging works with any of the models above. A world from a picture in
  309. masterpiece mode is long work for a strong model: Rain Harbour and Stortorget were each about a day
  310. of GPT-6.1 Sol, every construct built by its own subagent. Say "fast" for one pass each. Worlds were
  311. also tested in Hermes Desktop with DeepSeek V4 Pro.
  312. - **Small models** (tested: MiniMax M3.1 Flash, Thinking Machines Inkling, NVIDIA Nemotron 3.5
  313. Super VL) are not recommended: in about half of their runs they did not save a scene, and they
  314. made scale errors.
  315. ## Requirements
  316. Construct is deliberately small. You need:
  317. - Python 3.10 or newer. Nothing else to install: no packages, no virtual environment.
  318. - For review stills, a Chromium-family browser you already have (Chrome, Chromium, Edge, Brave).
  319. - For video, ffmpeg.
  320. - For the Blender add-on, Blender 4.2 or newer (the film of a run: checked in Blender 5.2); for the
  321. NetLogo bridge, NetLogo 6 or 7 (the extension: NetLogo 7, and NetLogo 3D 7).
  322. - For CAD, FreeCAD 1.0 or newer (STEP needs nothing more); for game engines, any glTF 2.0 importer
  323. (glued joints and worlds as game maps: tested in Godot 4.7). FBX and USD come through Blender.
  324. - For Hermes, the Construct plugin needs Hermes 0.22 or newer; a world from a picture in masterpiece
  325. mode needs `delegation.max_spawn_depth: 2` in Hermes's config (an orchestrator subagent per
  326. construct).
  327. ### What is tested where
  328. Every change runs the whole test suite (about 550 tests) on macOS, Linux and Windows, with Python 3.10 and the
  329. current Python, in continuous integration. What needs an outside program is tested where that program is:
  330. | Path | Needs | Tested |
  331. | --- | --- | --- |
  332. | Checking, building, exports (glTF, OBJ, 3MF, STL), kits, worlds, the MCP server | Python only | CI on macOS, Linux and Windows |
  333. | Review stills, gallery images, world captures | a Chromium-family browser | CI on macOS, Linux and Windows (headless Chrome) |
  334. | Films | a browser and ffmpeg | on macOS, before each release |
  335. | FreeCAD files and STEP | FreeCAD 1.0+ | on macOS, before each release |
  336. | The Blender add-on, FBX and USD | Blender 4.2+ | on macOS, before each release |
  337. | The NetLogo bridge and extension | NetLogo 7 | CI on Linux and Windows with NetLogo 7.0.4 |
  338. | The Hermes plugin | Hermes 0.22+ | its tests in CI on all three; end to end in Hermes Desktop on macOS |
  339. A path marked "on macOS" has no known platform problem elsewhere; it is just not run on the others before a
  340. release. If it fails for you on Linux or Windows, please open an issue.
  341. ## Documentation
  342. | If you want to… | read |
  343. | --- | --- |
  344. | see everything new in 1.3, the worlds one by one | [What's new in 1.3](docs/NEW-IN-1.3.md) |
  345. | make a world, in Hermes or by hand, and the format | [Worlds, step by step](docs/for/worlds-walkthrough.md) and [Worlds](docs/WORLDS.md) |
  346. | see how a world was made from one picture | [Rain Harbour](examples/worlds/rain-harbour/) and [Stortorget](examples/worlds/stortorget/) |
  347. | use constructs and whole levels in a game | [Construct for game developers](docs/for/game-developers.md) |
  348. | see everything new in 1.2, with examples | [What's new in 1.2](docs/NEW-IN-1.2.md) |
  349. | see everything new in 1.1, with examples | [What's new in 1.1](docs/NEW-IN-1.1.md) |
  350. | see how a construct is made, step by step | [How a construct is made](docs/HOW-IT-IS-MADE.md) |
  351. | know what you are looking at, and the keys | [The Measured Light style](docs/STYLE.md) |
  352. | run it every way, from a first construct by hand to Claude Code and Hermes | [Using Construct](docs/USING.md) |
  353. | fix something that went wrong | [Troubleshooting](docs/TROUBLESHOOTING.md) |
  354. | start from a ready-made template (a book, a CD, a guitar, a car) | [Archetypes](docs/ARCHETYPES.md) |
  355. | make mountains, routes and planets from real elevation data | [Terrain](docs/TERRAIN.md) |
  356. | turn a construct into a film with music | [Film mode](docs/FILM.md) |
  357. | see work made with Construct beyond the gallery: a music project's visual identity and film, a research project's site | [Made with Construct](docs/MADE-WITH-CONSTRUCT.md) |
  358. | export a 3D model or a world, plain or finished from its own material map | [3D export](docs/EXPORT.md) and the [Blender add-on](hosts/blender/README.md) |
  359. | print it, or make it a model kit | [3D printing and kits](docs/PRINTING.md) |
  360. | open it in CAD | [FreeCAD and STEP](docs/FREECAD.md) |
  361. | put it in a game engine | [Godot](docs/GODOT.md) |
  362. | draw a NetLogo model's run | [The NetLogo bridge](docs/NETLOGO.md) and [the extension](hosts/netlogo/README.md) |
  363. | teach with it, or show it in a museum | [In a classroom and a museum](docs/CLASSROOM.md) |
  364. | compare models, or score your own | [Evaluation](docs/EVALUATION.md) |
  365. | build on it or test the code | [Development](docs/DEVELOPMENT.md) and [the scene contract](CONTRACT.md) |
  366. | write your own adapter (a format, an engine, a machine) | [Adapters](docs/ADAPTERS.md) |
  367. | use it in Hermes, from the request to a printable kit | [Villa Savoye in Hermes, step by step](docs/for/hermes-walkthrough.md) and [Construct for Hermes](hosts/hermes/construct/README.md) |
  368. | design something new from real things (a ship, a creature, a vehicle) | [New things from real ones](docs/for/invent-from-what-exists.md) |
  369. | design a physical product from a system's documentation | [Documentation → product](docs/for/documentation-to-product.md) |
  370. | see how reconstructing, modifying and inventing are one pipeline | [The design-freedom continuum](docs/for/documentation-to-product.md#the-design-freedom-continuum) |
  371. | know where the method comes from | [About](docs/ABOUT.md) |
  372. | see what changed | [CHANGELOG.md](CHANGELOG.md) and the [1.3.0](docs/releases/v1.3.0.md), [1.2.0](docs/releases/v1.2.0.md), [1.1.0](docs/releases/v1.1.0.md) and [1.0.0](docs/releases/v1.0.0.md) release notes |
  373. The full index is in [docs/README.md](docs/README.md).
  374. ## Contributing
  375. See [CONTRIBUTING.md](CONTRIBUTING.md). Run the tests with
  376. `python3 -m unittest discover -s construct_hologram -t . -p 'test_*.py'`. Security reports:
  377. [SECURITY.md](SECURITY.md).
  378. ## License
  379. [Apache-2.0](LICENSE) — Copyright (c) 2026 Artyom Andreyev (see [NOTICE](NOTICE)); versions up to 0.3.0 were MIT. The NetLogo example folders
  380. (`examples/netlogo-*`: [viral marketing](examples/netlogo-viral-marketing/), [flocking](examples/netlogo-flocking/),
  381. [wolf sheep](examples/netlogo-wolf-sheep/), [fire](examples/netlogo-fire/), [fireflies](examples/netlogo-fireflies/),
  382. [virus on a network](examples/netlogo-virus-on-a-network/) and [virus compare](examples/netlogo-virus-compare/)) derive from Uri
  383. Wilensky's NetLogo models and are under CC BY-NC-SA 3.0 instead (see each LICENSE). The
  384. [Stortorget](examples/worlds/stortorget/) world, made from a CC BY-SA 4.0 photograph that it includes, is under CC BY-SA
  385. 4.0 (see its [LICENSE](examples/worlds/stortorget/LICENSE)). The [Blender
  386. add-on](hosts/blender/) is under GPL-3.0-or-later, as Blender's extensions platform requires; what
  387. you make with it is yours.
  388. Construct's working method is inspired by [Anatomy](https://github.com/wheresryan22/anatomy)'s
  389. truth-first construction (MIT); it shares the method, not code. Product, vehicle and place names
  390. in the examples belong to their owners: each example is an independent reconstruction from
  391. public references, not an official model. See [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.