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):

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 -e ".[dev]"        # core + pytest, no kernel needed
pytest                          # runs against the pure-Python null kernel
pip install -e ".[occt]"        # 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:

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 -e ".[dev,occt]"
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.