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 是一款桌面应用,配合 AI 编程代理,使用 CadQuery(Python)设计参数化三维 CAD 模型:你描述零件,代理把模型写成代码,SOMA 再生成并展示结果,方便你继续修改。
SOMA 自己是 AI 代理吗?还是我要另外接入一个?SOMA 本身不是代理,而是一个工作区(终端、代码编辑器、Git、三维查看器),Claude Code、OpenCode、Codex CLI、Gemini CLI 等任意命令行代理都可以接入其中。代理需要你自己安装并登录。
我怎么安装 SOMA 并开始建模?从 somacad.app/download 或 GitHub Releases 下载适用于你系统的安装包(Windows 为安装程序或免安装 ZIP,Linux 为 AppImage 或 tar.gz,macOS Apple Silicon 为 dmg),然后点击 'New model',再从终端上方的 + 中启动已识别的命令行代理。
编程代理要我自己装吗?SOMA 自带吗?你需要自行安装并登录命令行代理(Claude Code、OpenCode、Codex CLI 或 Gemini CLI);SOMA 不附带代理,以便你的订阅和模型选择由你自己决定。但它确实内置了 Python、CadQuery、Git 和 CalculiX。
SOMA 稳定吗?安装时有什么需要注意的地方吗?它被标注为早期原型,文件格式和 API 在 0.x 版本之间可能仍会变化。安装包尚未签名,因此首次启动时 Windows SmartScreen 和 macOS Gatekeeper 会发出警告,你需要手动绕过。
在 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 文件?一个单独的文件,包含模型的代码、生成的三维结果以及完整的编辑历史,其作用类似于原生的 CAD 文件格式。
哪个代理与 SOMA 配合得最好?项目方表示,目前主要使用 Claude Code 和 Claude Opus 5.5 进行测试,效果很好,不过其他命令行代理和模型也可以使用。
有哪些类似的项目?Amagine3D, text-to-cad, QymCAD, zuse, vicoa, pi-gui, Agentlas-OS, acryl
大小
15.6 MB
星标
490
更新
提交Nov 17
时长
1个月
提交 · 90 天