Metadata-Version: 2.4
Name: vibecad
Version: 0.6.0
Summary: Chat-native parametric CAD via FreeCAD MCP — build, modify, and export 3D models through natural language.
Project-URL: Homepage, https://github.com/wangtao9090/VibeCAD
Project-URL: Repository, https://github.com/wangtao9090/VibeCAD
Author-email: Wang Tao <wangtao9090@gmail.com>
License: MIT
License-File: LICENSE
Keywords: 3d-modeling,3d-printing,ai,cad,freecad,mcp,parametric
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.12
Requires-Dist: hatchling==1.28.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: mcp==1.27.2
Requires-Dist: numpy>=1.26
Requires-Dist: pygltflib>=1.16.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# VibeCAD

**[English](README.md)** | [简体中文](README.zh-CN.md)

[![CI](https://github.com/wangtao9090/VibeCAD/actions/workflows/ci.yml/badge.svg)](https://github.com/wangtao9090/VibeCAD/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org)

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:

```bash
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:

```bash
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

```text
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.

| Category | Tools |
|---|---|
| Service and runtime | `ping`, `get_runtime_status`, `ensure_runtime`, `uninstall_runtime` |
| Capability discovery | `get_capabilities` |
| Projects and versions | `create_project`, `get_project`, `list_projects`, `list_revisions`, `compare_revisions`, `revert_project` |
| Tasks and drafts | `create_task`, `list_tasks`, `get_task`, `get_task_events`, `submit_model_program`, `resume_task`, `cancel_task`, `accept_draft`, `reject_draft` |
| Delivery | `get_artifact_manifest`, `export_task_artifacts`, `create_release`, `get_release`, `approve_release` |
| Direct operations | `create_box`, `create_cylinder`, `inspect_model`, `modify_parameter`, `move_part`, `rotate_part` |

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:

| Host | User-level path | Project-level path |
|---|---|---|
| Current Codex installer path | `$CODEX_HOME/skills/vibecad-agent`; defaults to `$HOME/.codex/skills/vibecad-agent` when unset | — |
| Published Codex discovery path | `$HOME/.agents/skills/vibecad-agent` | `.agents/skills/vibecad-agent` |
| Claude Code | `$HOME/.claude/skills/vibecad-agent` | `.claude/skills/vibecad-agent` |

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:

```text
~/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

```bash
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:

```bash
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](https://github.com/wangtao9090/VibeCAD/blob/main/docs/USER_GUIDE.md),
[Acceptance Tests](https://github.com/wangtao9090/VibeCAD/blob/main/docs/ACCEPTANCE_TESTS.md),
[Overall Architecture](https://github.com/wangtao9090/VibeCAD/blob/main/docs/ARCHITECTURE.md),
[Agent Architecture](https://github.com/wangtao9090/VibeCAD/blob/main/docs/AGENT_ARCHITECTURE.md),
and the
[Product Capability Roadmap](https://github.com/wangtao9090/VibeCAD/blob/main/docs/PRODUCT_CAPABILITY_ROADMAP.md).
See the
[Integrated Product and Technical Strategy](https://github.com/wangtao9090/VibeCAD/blob/main/docs/PRODUCT_STRATEGY.md)
for the unified decisions on product positioning, open-source strategy, multiple CAD backends,
the AutoCAD/domestic CAD roadmap, and the evaluation framework.

## License

[MIT](LICENSE)
