Desktop app for designing parametric 3D models in CadQuery together with the coding agent of your choice
TypeScript 3d-modeling3d-printing3d-printing-toolsagentagentic-aiai-cadcadcadqueryclaude-codecodexelectronfemllmmacdmakeropencodeparametric-designpythonsteptext-to-cad
Doku: README gestrafft, Bilder zu Animation und Zeichnung
Kai-Jungsthoefel56fb1779186d
diff --git a/README.md b/README.mdindex dd9ed84..4d99ad0 100644--- a/README.md+++ b/README.md@@ -2,107 +2,60 @@**Solid Object Modeling with Agents.** A desktop app for designing parametric 3D models together with a coding agent.-+<!-- Trailer: upload the MP4 in the GitHub web editor and put the user-attachments link here, the hero image moves to Screenshots -->You tell the agent what you need. It writes the model as Python code with [CadQuery](https://github.com/CadQuery/cadquery), SOMA builds it and shows the result. You look at it, measure it, point at what is wrong, and the agent changes the code.## What it is-SOMA puts a few things into one window:+It's vibe coding, but for CAD. Made for makers and tinkerers who need a case, a bracket or a mount for their project and don't want to spend hours in a CAD program to get it. Describe or sketch the part, check the result, export it, print it. You don't have to know CadQuery. The code is there if you want to change a dimension yourself.-- **3D viewer** for the model the agent builds, with measuring, sections and exploded views-- **IDE**: terminal for the agent, code editor, file tree and version history-- **Sketch tool**: draw on the view or on a photo of a hand sketch to show the agent what you mean-- **Instructions for the agent**: `AGENTS.md` and `CLAUDE.md` with the rules of the project, plus skills for 3D printing, CNC, tolerances and more-- **Helper tools**: the `soma` command line for building, analysis, rendering and standard parts+SOMA is not an agent of its own. Any CLI agent that can read files and run commands works: Claude Code, OpenCode, Codex CLI, Gemini CLI or whatever comes next. It runs in a normal terminal inside the model folder, SOMA detects the common ones and can start them. You install and log in to them yourself, so your subscription, your model choice and your permission settings stay yours. SOMA gives the agent a command line tool (`soma build`, `soma analyze`, `soma render` …) and an `AGENTS.md` with the rules of the project.-## Who it is for+## Install-Makers and tinkerers who need a case, a bracket or a mount for their project and don't want to spend hours in a CAD program to get it. Describe or sketch the part, check the result, export it, print it.+Download the package for your system from the [releases](https://github.com/Kai-Jungsthoefel/SOMA/releases): an installer for Windows, an AppImage or tar.gz for Linux, a dmg for macOS (Apple Silicon). Python, CadQuery, Git and CalculiX are included.-It's vibe coding, but for CAD. You don't have to know CadQuery. The code is there if you want to change a dimension yourself.+- You need a CLI agent installed and logged in, for example Claude Code, OpenCode, Codex CLI or Gemini CLI. SOMA does not bring one+- The installed app takes over 1 GB of disk space, most of it for Python, CadQuery and OpenCascade+- The packages are not signed yet. On Windows, SmartScreen warns on the first start ("More info" > "Run anyway"). On macOS, open the app the first time with right-click > Open+- Linux needs glibc 2.31 or newer+- There is no automatic update. Download a new version from the releases page-## Use the agent you already have+## Quick start-SOMA is not an agent harness of its own. The agent runs in a normal terminal inside the model folder. SOMA gives it a command line tool (`soma build`, `soma analyze`, `soma render` …) and an `AGENTS.md` with the rules of the project.+1. Start SOMA and click **New model** on the start page. It starts from a small example, a box with a lid.+2. Start your agent with the **+** above the terminal on the right. SOMA lists the agents it found on your computer.+3. Tell the agent what you need, for example *"A case for a Raspberry Pi 5 with vents in the lid, printed in PETG"*. SOMA builds the model on every change and shows it.+4. Click parts, measure, or draw on the view and send it to the agent until it fits. Then export it from the menu, for example as STL or 3MF.-Any CLI agent that can read files and run commands works: Claude Code, OpenCode, Codex CLI, Gemini CLI or whatever comes next. SOMA detects the common ones and can start them. You install and log in to them yourself, so your subscription, your model choice and your permission settings stay yours.+Press F1 in the app for a short guide with numbered screenshots. The agent knows the same guide, so you can also just ask it how something works.## Features-**Modeling**-- Models are Python files (`model.py`, optional `parts/`) using CadQuery and a small helper library-- Builds on every change, errors point to file and line-- Named parts, groups and sub-assemblies, STEP import of single parts and whole assemblies-- Standard parts (ISO/DIN screws, nuts, washers, heat-set inserts) with matching holes and nut traps-- Parameters: the agent marks the values you may change (`param()`), you change them in a panel and can always reset them to the agent's value-- Extra Python packages: the agent runs `pip install`, SOMA records them in `requirements.txt` and reinstalls them on another machine--**Looking at the result**-- Click a part to jump to the line of code that created it-- Mouse navigation like in SolidWorks, Fusion 360, Onshape, Creo or Rhino, perspective or orthographic view-- Exact measurements on the B-rep, not on the mesh: faces, edges, distances, hole spacing-- Section views, exploded views with a disassembly analysis, transparency and isolation per group-- Analysis: overhangs, wall thickness, clearance between parts, strength with FEM (CalculiX), also with contact between parts and preloaded bolts-- Animations written in Python, rendered to images and MP4--**Feedback to the agent**-- Send a selection, a measurement or a section to the agent with one click-- Draw on the 3D view, or drop in a photo of a hand sketch and draw on that, then hand the image to the agent-- `soma render` lets the agent look at its own work as images or contact sheets-- Skills: optional rule sets per model (3D printing, resin and powder printing, CNC, laser cutting, sheet metal, tolerances, joints, FEM …), switched on always or on demand. Edit them or add your own in the settings-- A short built-in guide with numbered screenshots (F1). The agent gets the same guide as a skill, so you can also just ask it how the app works--**Project**-- A model is a single `.soma` file (a ZIP archive) with code, result and history. ZIP files open too, and the export menu writes the whole model as a ZIP-- Every commit of the agent shows up on a timeline below the view, old states can be previewed and restored-- Export to STEP, STL, 3MF, glTF, DXF, SVG and more-- Technical drawings as PDF and DXF: the agent writes them in Python with views, sections, details and dimensions measured from the model, and checks the result as an image+- **Models as code:** Python with CadQuery, rebuilt on every change+- **One file per model:** a `.soma` file holds code, result and history, like a CAD file+- **Point, measure, draw:** click a part, measure exactly or sketch on the view, and send it to the agent+- **Parameters:** change the values the agent made adjustable, without touching the code+- **History:** every step of the agent on a timeline, preview and restore old states+- **Skills:** rule sets for the agent, such as 3D printing, CNC, laser cutting, sheet metal and tolerances, switched on per model. Edit them or add your own+- **Analysis and animation:** overhangs, wall thickness, strength with FEM, animations as video+- **Export:** STEP, STL, 3MF, DXF and more, technical drawings as PDF## Screenshots-Click a part and SOMA shows where it comes from in the code.----Exploded view. SOMA works out in which direction each part can be removed.+**Explode:** take your assembly apart. SOMA works out in which direction each part comes off.-Overhang analysis of a 3D printed part, the lid of a Raspberry Pi 5 case seen from below. The agent ran `soma analyze` in the terminal, the critical underside is marked red.----## What a model looks like--```python-import cadquery as cq-from soma import add_part, param--LENGTH = param(60.0, "Length", min=30, max=200, unit="mm") # adjustable in the app-WIDTH, HEIGHT, WALL = 40.0, 25.0, 2.0+**Animate:** bring your models to life. Animations are created by your agent and rendered to video.-body = (- cq.Workplane("XY")- .box(LENGTH, WIDTH, HEIGHT, centered=(True, True, False))- .edges("|Z").fillet(3.0)- .faces(">Z").shell(-WALL)-)-add_part("Body", body, color=(0.25, 0.45, 0.75))-```--`soma build` runs the file and writes `output/model.step` with every part named, plus the data for the viewer. `param()` puts a value into the Parameters panel of the app.+-## Install+**Draw:** technical drawings from the model. The agent writes them in Python, with views, sections and dimensions measured on the model, as PDF and DXF.-Download the package for your system from the [releases](https://github.com/Kai-Jungsthoefel/SOMA/releases): an installer for Windows, an AppImage or tar.gz for Linux, a dmg for macOS (Apple Silicon). Python, CadQuery, Git and CalculiX are included. You only need a CLI agent.--- You need a CLI agent installed and logged in, for example Claude Code, OpenCode, Codex CLI or Gemini CLI. SOMA does not bring one-- The installed app takes over 1 GB of disk space, most of it for Python, CadQuery and OpenCascade-- The packages are not signed yet. On Windows, SmartScreen warns on the first start ("More info" > "Run anyway"). On macOS, open the app the first time with right-click > Open-- Linux needs glibc 2.31 or newer-- There is no automatic update. Download a new version from the releases page+## Status@@ -114,6 +67,10 @@ Early prototype, version 0.6.2. See [CHANGELOG.md](CHANGELOG.md).> **Note:** SOMA itself is vibe coded. Most of the code was written by coding agents (mainly Claude Code) under human direction and review. It has tests, but expect rough edges.+## Feedback++Bug reports, ideas and experiences with different agents are very welcome as [issues](https://github.com/Kai-Jungsthoefel/SOMA/issues/new/choose). Pull requests are not accepted for now, see [CONTRIBUTING.md](CONTRIBUTING.md).+## Running from sourceFor development. The setup script is for Windows only. Requirements: Windows, Node.js 22, Python 3.12 and [uv](https://github.com/astral-sh/uv).@@ -127,20 +84,10 @@ npm startMore in [app/README.md](app/README.md).-## Repository--| Path | Content |-|---|---|-| `app/` | Electron app (TypeScript): terminal, viewer, project format, tests |-| `python/soma/` | Helper library and command line tool used by the agent |-| `design/` | UI drafts |-| `docs/` | Images for this page, results of the first prototype |-| `.github/workflows/` | Builds, tests and releases for Windows, Linux and macOS |-## LicenseSOMA is free software under the [GNU General Public License v3.0](LICENSE) or any later version. You can use, change and share it. If you distribute a changed version, its source code has to be open under the same license.What you design with SOMA is yours. The [SOMA Model Exception](MODEL-EXCEPTION.md) lets you license your model files under any terms you like, even though they import `soma`. Exported files like STEP or STL are not affected by the GPL at all.-Third-party components keep their own licenses. Among them are CadQuery (Apache-2.0), OpenCascade (LGPL-2.1), Git (GPL-2.0), gmsh (GPL-2.0-or-later), CalculiX (GPL-2.0-or-later) and pdf.js (Apache-2.0).+Third-party components keep their own licenses, see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).diff --git a/docs/images/analysis.png b/docs/images/analysis.pngdeleted file mode 100644index 4194661..0000000Binary files a/docs/images/analysis.png and /dev/null differdiff --git a/docs/images/animation.png b/docs/images/animation.pngnew file mode 100644index 0000000..5f7e3daBinary files /dev/null and b/docs/images/animation.png differdiff --git a/docs/images/code.png b/docs/images/code.pngdeleted file mode 100644index 63fa798..0000000Binary files a/docs/images/code.png and /dev/null differdiff --git a/docs/images/drawing.png b/docs/images/drawing.pngnew file mode 100644index 0000000..fd1bc70Binary files /dev/null and b/docs/images/drawing.png differ