gitcad

Agent-first, headless, git-native CAD.

gitcad is a boundary-representation CAD system designed from the ground up to be driven by agents over MCP, with git as the source of truth and a browser as the (optional) viewer. It leans on the mature OpenCASCADE geometry kernel via cadquery-ocp rather than reinventing b-rep math — the value lives in the layers around the kernel:

• an intent-based API agents can author without visualizing raw NURBS,
• a verification/render loop so agents model by checking, not hoping,
• associative 2D drawings derived from the 3D model (mechanical drafting),
• a git-native text format so models diff, branch, and merge like code, and
• a privacy-preserving bug loop where failures are auto-reduced to minimal, synthetic, shareable repros.

Website: gitcad.xyz

Why this exists

Agents fall back to shelling out to FreeCAD for anything with complex curves — not because that's good, but because it's what's in the training distribution, and they model blind. gitcad's thesis: wrap the same proven kernel (OCCT) in an intent API plus a deterministic inspect/render loop, make the model text so git works, and make MCP the primary interface so the product is agent-legible from day one.

The six seams

Everything swappable lives behind a small, stable interface (gitcad.seams):

Seam	Responsibility	Default backend
Kernel	b-rep geometry ops	OCCT via cadquery-ocp (gitcad.kernel.occt)
IdentityService	stable entity IDs (topological naming)	lineage-hash (gitcad.identity)
DocumentModel	the feature tree + text (de)serialization	gitcad.document
Renderer	headless tessellate → image/glTF	stub
DrawingEngine	3D → 2D HLR projection + dimensions	stub
Storage	git-backed model + artifact store	stub

A "major architecture change" should mean replacing one backend, not a rewrite.

Layout

src/gitcad/
  seams.py         # the six Protocol interfaces — the load-bearing boundaries
  errors.py        # structured errors that double as bug-repro payloads
  identity.py      # IdentityService: stable IDs from construction lineage
  document.py      # DocumentModel: feature tree + canonical text format
  kernel/
    null.py        # pure-Python test backend (no OCCT dependency)
    occt.py        # OCCT via cadquery-ocp (the real kernel)
  report/
    fingerprint.py # deterministic failure fingerprints (for dedup)
    reduce.py      # delta-debug reducer: proprietary model -> minimal synthetic repro
  mcp/
    server.py      # the MCP tool surface (the PRIMARY interface)
docs/adr/          # architecture decision records (the durable intent)
tests/
  invariants/      # permanent, architecture-independent properties
  golden/          # curated user-visible contracts
  regression/      # auto-generated, second-class, expirable

Quick start

pip install --no-deps -e packages/gitcad-core -e packages/gitcad-mech -e packages/gitcad-ecad -e packages/gitcad && pip install pytest
pytest                          # runs against the pure-Python null kernel
pip install cadquery-ocp        # add the real OCCT kernel (~large wheel)

The test suite runs with no geometry kernel installed — the null backend covers identity, document round-tripping, and reduction. Tests that need real geometry are marked @pytest.mark.occt and skip when cadquery-ocp is absent.

Status — v0.1

Manufacturing outputs work end to end. From a text model, gitcad produces files you can send to a manufacturer today:

Domain	Outputs
Mechanical	STEP (ISO 10303-21) · STL · dimensioned 2D drawings (SVG + PDF, third-angle front/top/right/iso via OCCT HLR)
Electrical	Gerber X2 (copper ×2, mask ×2, silk, profile) · Excellon drill · pick-and-place CSV · manifest

Working: OCCT kernel (primitives, booleans, fillets, transforms, validation, measurement, entity enumeration) · drawing engine · 2-layer board model with fab-readiness validation · MCP tools for all of it · deterministic, byte-stable outputs (same source → identical Gerbers).

Try it:

pip install cadquery-ocp   # after the editable installs above
python examples/bracket.py   # → bracket.step, bracket.pdf, bracket.svg, bracket.stl
python examples/blinky.py    # → full Gerber/drill/PnP fab package

Next: the cross-domain part standard (interfaces, ports, lockfile versioning), schematic capture + ERC, DRC engine, associative feature-level dimensions, the component registry. See docs/adr/ for the reasoning, docs/research/ for the competitive feature map, and CLAUDE.md for the rules agents must follow.

License

Apache-2.0. The OCCT kernel it binds is LGPL-2.1-with-exception; see NOTICE.