SOMA README

README проекта с github.com/Kai-Jungsthoefel/SOMA. Одним файлом markdown: README.md.

SOMA

Solid Object Modeling with Agents. A desktop app for designing parametric 3D models together with a coding agent.

somacad.app · Download · Video tutorial · Changelog · 简体中文 (AI translation)

https://github.com/user-attachments/assets/3294d1e4-1f06-477d-9770-c91f3470330d

You tell the agent what you need. It writes the model as Python code with 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 is SOMA?

A CAD program where the AI does the CAD and you are the designer. SOMA brings together the three parts this needs: a code workspace with a terminal for your agent, an editor and Git for every version; a 3D viewer that rebuilds the model on every change; and instructions for the agent, with rules, skills and a command line tool.

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.

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.

Install

Download SOMA from somacad.app/download, which offers the right package for your system, or from the releases: an installer or a portable ZIP for Windows, an AppImage or tar.gz for Linux, a dmg for macOS (Apple Silicon). Python, CadQuery, Git and CalculiX are included.

Quick start

  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.

The video tutorial (9 min) shows all of this and more: drawing on the view, parameters, animation, FEM, drawings, skills and export.

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.

Agent apps (Codex app, Claude Desktop)

Instead of an agent in SOMA's terminal you can use a desktop agent app that works on a local folder and can run commands, for example the Codex app or Claude Code in Claude Desktop.

  1. Open the model in SOMA and keep SOMA open.
  2. Click the + above the terminal and choose Copy path for agent app. For a model you opened with Open folder, the path is simply that folder.
  3. In the agent app, open this path as the project folder and tell the agent what you need.

Send to agent also copies its note to the clipboard: paste it into the agent app. A markup note names its picture in .soma/feedback/, which the agent opens itself. A chat without file access and commands does not work.

Features

Screenshots

Explode: take your assembly apart. SOMA works out in which direction each part comes off.

Exploded view of the rover

Animate: bring your models to life. Animations are created by your agent and rendered to video.

Animation of a Strandbeest with its steps and the playback bar

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.

Technical drawing of a wardrobe next to the 3D model

Look at more examples in 3D on somacad.app: a CNC router, a parametric organizer, a walking robot dog and a shelf with FEM.

Status

Early prototype. The current version is on the releases page, changes are in 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. Pull requests are welcome too, see CONTRIBUTING.md.

Running from source

For development. The setup script is for Windows only. Requirements: Windows, Node.js 22, Python 3.12 and uv.

powershell -File python/scripts/setup_env.ps1
cd app
npm install
npm start

More in app/README.md.

License

SOMA is free software under the GNU General Public License v3.0 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 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. The compatibility code that "As CadQuery script" puts into an exported script is also available under the Apache License 2.0.

Third-party components keep their own licenses, see THIRD_PARTY_NOTICES.md.

As seen on Open Source Alternatives

SOMA (Kai-Jungsthoefel/SOMA)

Ищем в базе…

490 ·GitHub
Что это такое?SOMA — это настольное приложение для проектирования параметрических 3D-моделей CAD в CadQuery (Python) вместе с ИИ-агентом для написания кода: вы описываете деталь, агент пишет модель в виде кода, а SOMA собирает и показывает результат, чтобы вы могли его доработать.
SOMA сама является ИИ-агентом или мне нужно подключить агента?SOMA — не собственный агент, а рабочая среда (терминал, редактор кода, Git, 3D-просмотрщик), к которой подключается любой CLI-агент, например Claude Code, OpenCode, Codex CLI или Gemini CLI. Агента вы устанавливаете и входите в него сами.
Как установить SOMA и начать модель?Скачайте пакет для своей ОС с somacad.app/download или со страницы GitHub releases (установщик или портативный ZIP для Windows, AppImage или tar.gz для Linux, dmg для macOS на Apple Silicon), затем нажмите 'New model' и запустите найденного CLI-агента через кнопку + над терминалом.
Нужно ли мне самому устанавливать агента для кода или SOMA его включает?Нужно установить и войти в собственного CLI-агента (Claude Code, OpenCode, Codex CLI или Gemini CLI); SOMA его не поставляет, чтобы ваша подписка и выбор модели оставались вашими. Зато в комплект входят Python, CadQuery, Git и CalculiX.
Насколько стабильна SOMA и есть ли подводные камни при установке?Проект помечен как ранний прототип, и его форматы файлов и API могут меняться между версиями 0.x. Пакеты пока не подписаны, поэтому при первом запуске Windows SmartScreen и macOS Gatekeeper выдадут предупреждение, которое нужно обойти вручную.
Работает ли SOMA на Linux и Mac так же хорошо, как на Windows?Пакеты есть для Windows, Linux (AppImage/tar.gz, нужна glibc 2.31+) и macOS (только Apple Silicon), но разработка и большая часть тестирования шли на Windows, другие платформы использовались заметно меньше.
Нужно ли мне самому знать CadQuery или Python?Нет. Вы описываете деталь обычным языком, а агент пишет для вас код на CadQuery Python; редактировать код самостоятельно нужно только если вы этого хотите.
В какие форматы можно экспортировать готовую модель?STEP, STL, 3MF, DXF и другие, а также технические чертежи в PDF.
Что такое файл .soma?Это один файл, в котором хранятся код модели, её готовый 3D-результат и вся история правок; он работает как родной формат файлов CAD.
С каким агентом SOMA работает лучше всего?По данным проекта, в основном SOMA тестировалась с Claude Code и Claude Opus 5.5, результаты очень хорошие, но и другие CLI-агенты и модели тоже работают.
Какие есть похожие проекты?Amagine3D, text-to-cad, QymCAD, zuse, vicoa, pi-gui, Agentlas-OS, acryl
Размер
15.6 MB
Звёзды
490
Обновлён
КоммитNov 17
Возраст
1 мес
Коммиты · 90 дней