VibeCAD

English | 简体中文

VibeCAD is a FreeCAD expert agent for host agents such as Claude and Codex. It turns design intent into persistent projects, constrained CAD operations, reviewable drafts, and verified FCStd/STEP resources.

VibeCAD neither embeds nor resells a large language model. Reasoning uses the user's own host model and its subscription or API quota; VibeCAD is responsible for CAD contracts, isolated execution, deterministic verification, recovery, and delivery.

What VibeCAD Delivers

• An Agent-native path from design intent to persistent CAD projects and versioned results.
• A real FreeCAD Workbench Alpha for project/task discovery, HEAD and draft preview, verdict, Accept, and Reject.
• Deterministic Task Kernel execution: isolated candidates, explicit review policy, verified FCStd/STEP artifacts, recovery, and replay-safe request semantics.
• A VibeCAD-managed FreeCAD runtime, so users do not need to prepare a compatible system FreeCAD.

Try the FreeCAD Workbench Alpha

The easiest installation path is to give your coding Agent this request:

Install and launch the VibeCAD FreeCAD Workbench Alpha from https://github.com/wangtao9090/VibeCAD. Use commit 91c94f4a2761d19b878f92dc892130a920e7ba85, clone it into a persistent directory, build its wheel, install it with uv tool install --force, keep the checkout and built wheel, and run vibecad --freecad. Do not install or fall back to a system copy of FreeCAD.

The Agent's reproducible procedure is:

git clone https://github.com/wangtao9090/VibeCAD.git VibeCAD
git -C VibeCAD checkout 91c94f4a2761d19b878f92dc892130a920e7ba85
cd VibeCAD
uv build --wheel
uv tool install --force dist/vibecad-0.6.0-py3-none-any.whl
vibecad --freecad

Installation notes:

• Keep the persistent checkout and built wheel at the same path while this Alpha is installed.
• Do not search PATH, /Applications, the normal FreeCAD Mod directory, or install a system FreeCAD fallback. vibecad --freecad owns the verified managed runtime.
• Allow the first launch to download approximately 2–3 GB of locked runtime files; later launches reuse them.
• Success means managed FreeCAD opens with the VibeCAD Workbench and review Dock active. On failure, report the exact launcher error and stop instead of switching runtimes or inventing an alternate installation path.

The Dock can list projects and tasks, refresh selected state, open separate managed HEAD and draft preview documents, show the review verdict, capture exact whole-object or feature SelectorV1 values, and Accept or Reject a fresh draft. Face/edge subelement selection is not claimed.

The current P1 source also provides a sequential manual-finish path after Agent review ends: Open Editable HEAD creates a non-authoritative working copy, normal Save stays local, Checkpoint Edit verifies and publishes a new Revision, and Discard Edit publishes nothing. Agent preview and editable HEAD are mutually exclusive; there is no automatic merge or rebase.

The managed launcher above remains the default and fallback. One additional, deliberately narrow macOS pilot can install the same thin Workbench into an explicitly selected user FreeCAD:

vibecad --freecad-app /Applications/FreeCAD.app --doctor
vibecad --freecad-app /Applications/FreeCAD.app --install-addon
# reversible cleanup
vibecad --freecad-app /Applications/FreeCAD.app --uninstall-addon

This is not general system-FreeCAD support. The current local evidence admits only the exact fingerprinted macOS FreeCAD 1.1.3 host with embedded CPython 3.11 and PySide6 6.8.3. The doctor fails closed for every other host. The installed addon holds no daemon secret and delegates selector construction and unique resolution to the managed Python bridge and the same Task Kernel used by managed mode.

Current Agent-first Workflow

User and host Agent
  → get_capabilities reads the actual capabilities
  → create_project creates an empty project or performs a controlled FCStd import
  → create_task binds the project version and review policy
  → call one direct operation, or submit a multi-step ModelProgram
  → Task Kernel executes and verifies the candidate version in an isolated checkout
  → auto_commit publishes, or require_review waits for Accept/Reject
  → export_task_artifacts returns FCStd/STEP ResourceLinks
  → resources/read reads and verifies the delivered resources

Direct operations and ModelPrograms are not separate execution systems. A direct operation simply compiles one explicit operation into a single-command ModelProgram. Both paths enter the same Task Kernel and share the same project lease, immutable base revision, candidate checkout, verification, draft, commit, reject, rollback, and recovery semantics.

A project can currently begin only from an empty project or a single FCStd file. An FCStd import must be non-empty, and every object in it must be either Part::Box or Part::Cylinder. Mixed or other object types are rejected. General FCStd import belongs to P1; STEP/STL import, reverse engineering, and simulation are not yet integrated. Upstream engines for photo/video-to-mesh or STL conversion, 2D sketch recognition, and similar tasks may be connected later as external tools. VibeCAD focuses on the intermediate orchestration and verification of editable CAD.

Current Public Capabilities (0.6.0)

The MCPB manifest and runtime project the same frozen contract, which currently exposes 31 tools. Each tool has a concise description, a strict input schema, and side-effect annotations. A host should call get_capabilities first instead of inferring capabilities from the number of tools or from general model knowledge.

A successful export_task_artifacts call returns a canonical result and two typed ResourceLink values:

• FCStd: application/vnd.freecad.fcstd;
• STEP: model/step.

The host can retrieve binary content only by calling resources/read with the returned URI, then checking its format, size, and SHA-256. The interface does not provide arbitrary-path export or arbitrary file reads.

For an accepted Revision, create_release generates a previewable A3 assembly PDF, flat BOM, manifest, validation report, and an immutable seven-file delivery ZIP. The host must present the exact ZIP SHA-256 before calling approve_release; only the approved Release exposes the ZIP ResourceLink. Release approval is separate from Revision acceptance and never changes project HEAD.

Why the Model Does Not Execute FreeCAD Python Directly

FreeCAD is the geometry engine and execution environment, but “the code runs” does not mean “the design matches the intent.” The primary path accepts only versioned ModelPrograms with a bounded operation set and bounded budgets. It does not accept arbitrary Python/FreeCAD code generated by the model, nor does it use such code as a fallback channel after failure.

The Task Kernel provides the following guarantees for every write:

• Inputs pass strict schema, selector, budget, and AcceptanceSpec validation.
• Execution occurs in an isolated candidate copy rather than modifying the user's source file in place.
• Results are bound to the base revision, task generation, verification evidence, and an immutable revision.
• auto_commit publishes only after verification succeeds and HEAD has not drifted.
• require_review creates a persistent draft; Accept publishes it, while Reject leaves HEAD unchanged.
• Delivery state, provenance, hashes, and sizes are verified again during export and read.

Before calling create_task, the host must generate and persist a task_create_ request key. If the response outcome is unknown, replay create_task with exactly the same key, project, and review policy. The Task Kernel returns the current generation of the same task rather than creating a second task.

The first cancel_task call must use the task generation that was just read. For an idle task in created, needs_plan, program_ready, or needs_input, it immediately persists cancelled with CAS. If the cancellation response is unknown, the exact same request can be replayed to obtain the same cancellation result. A running task persists its cancellation state. When the current task returns next_action=reconcile, the host must first read the task, then call resume_task once with the generation just returned. It must not guess whether the Worker has stopped or fabricate a future generation. A draft awaiting review must be handled with reject_draft.

Idle cancellation changes only the task record. It does not start CAD/runtime, construct artifact/export components, acquire the project write lease, or modify project HEAD, source files, or the delivery directory. MCP notifications/cancelled cancels only one transport request; it is not persistent task cancellation.

Use paginated list_projects discovery only when the project id is unknown, then call get_project to read the current authoritative HEAD. list_revisions returns only committed ancestors of that project's current HEAD. Results are sorted by canonical revision id rather than by time; reconstruct the commit chain from the returned head by following base_revision. Draft, candidate, and abandoned revisions are not returned as committed history. If any paginated cursor returns conflict, discard the cursor and restart from the first page.

compare_revisions revalidates the manifests and actual FCStd/STEP files of two committed revisions. It reports only lineage, file presence, and differences in identity, SHA-256, and size; semantic diffs for geometry, solids, and parameters are explicitly unsupported. Before delivery, call the read-only get_artifact_manifest. If a verified PUBLISHED delivery already exists, it directly returns two ResourceLinks. Otherwise it returns materialized=false without creating, copying, or cleaning any delivery file; only then should export_task_artifacts be called.

Installation: The MCP Service and Agent Skill Are Separate

The current MCPB product declaration covers only the verified macOS (Darwin) path. Installing VibeCAD.mcpb installs the MCP service, but the bundled Skill is archive content and is not activated automatically. The host must separately copy or link skills/vibecad-agent/, then restart or reload the host.

Skill discovery paths are:

The release asset vibecad-agent-skill-0.6.0.zip contains exactly one top-level vibecad-agent/ directory after extraction. That directory can be copied as a whole to any path listed above. The Python wheel contains the server and the FreeCAD Workbench addon, while the managed runtime contains the matching server environment. Neither package activates the Agent Skill.

On first launch, the extension needs network access to fetch locked Python packages and, when needed, install approximately 2–3 GB of FreeCAD runtime files. Later launches reuse the verified cache. The default macOS data root is typically:

~/Library/Application Support/VibeCAD/

Runtime and project data are separate. uninstall_runtime first presents a preview and then requires explicit confirmation. It deletes only the managed runtime while preserving project, revision, draft, and artifact data. The host settings can then remove the extension itself.

Local Development

uv sync --frozen
PYTHONPATH=src uv run --frozen pytest
uv run --frozen ruff check .
VIBECAD_AUTO_INSTALL=0 uv run --frozen python -m vibecad.server

FreeCAD is not a normal Python dependency; the runtime installer manages it separately. Real runtime integration tests must be enabled explicitly:

VIBECAD_RUN_INTEGRATION=1 PYTHONPATH=src uv run --frozen pytest -m slow

What “Host-ready” Means Precisely

The 0.6.0 release has verified the MCP protocol, Skill package structure, FCStd/STEP and Release ResourceLinks, managed FreeCAD E2E, and 31-tool discovery, so it can be described as protocol/package host-ready. This phase has not consumed the user's external-model quota to perform acceptance on WorkBuddy or another second host, so it cannot yet be described as host-verified; actual cross-host model calls remain a separate residual.

Architectural Boundaries and Roadmap

The current domain path is MCP transport/server → same-user authenticated local daemon → single Agent application → Task Kernel → CAD execution port → managed killable FreeCAD Worker. The public Workbench client likewise enters the Application/Task Kernel through the daemon. Runtime maintenance and stateless discovery remain local responsibilities of the MCP server and do not form a second domain-write path. The daemon provides same-user authentication and constrained, one-time file grants; it does not create a second commit system.

S3-8, P0-B core, the package/managed-runtime closeout, bounded G1 Workbench Alpha, P1 sequential editing, and P2 rigid mechanical delivery are complete for 0.6.0. The next integration slice is WorkBuddy host verification:

• P0-B core (backend complete): task/project/version discovery, file-level comparison, verified forward revert, cancellation/reconcile, authenticated daemon, file grants, source liveness, and the managed killable FreeCAD Worker all enter the same Task Kernel;
• G1 (Alpha complete): preview, verdict, exact object/feature selector capture, and Accept/Reject are available in the real FreeCAD Qt Workbench UI; one fingerprinted external FreeCAD 1.1.3 pilot is evidenced, while managed mode remains the default;
• P1/G2 (complete boundary): the narrow sequential editable-HEAD/manual-checkpoint slice is implemented in the current source; Sketcher/PartDesign, controlled import, and broader single-part production capability remain;
• P2 (complete boundary): rigid 2–10 component assemblies, interference verification, flat BOM, deterministic assembly PDF, immutable Release approval, and an exact delivery ZIP; native joints, editable manufacturing drawings, GD&T, PLM, and enterprise delivery chains remain;
• WorkBuddy (next): certify local stdio MCP, strict schemas, durable task recovery, and Release PDF/ZIP resources with explicit model profiles.

The G1 Workbench Alpha packages the real FreeCAD Qt UI and its deterministic managed launcher. It includes one Workbench and Dock, daemon-backed refresh, separate HEAD/draft preview, verdict, exact object/feature selector capture, Accept/Reject, and asynchronous client/thread shutdown. The daemon is a reusable managed background service; update and uninstall retire it through the authenticated maintenance path. The thin external pilot reuses those state machines through one bounded managed-Python bridge and does not add a second write authority. Face/edge selection, STEP/STL import, photo reconstruction, and simulation are not currently supported.

Further reading in the source repository: User Guide, Acceptance Tests, Overall Architecture, Agent Architecture, and the Product Capability Roadmap. See the Integrated Product and Technical Strategy for the unified decisions on product positioning, open-source strategy, multiple CAD backends, the AutoCAD/domestic CAD roadmap, and the evaluation framework.

License

MIT