Battenmark

Battenmark provides a typed, backend-neutral interface for creating, editing, inspecting, validating and exporting authoritative CAD geometry across interchangeable CAD backends. Callers request create_hole — never PartDesign::Hole. No transport owns the model; one canonical service does.

Verified client evidence

As of September 7, 2026, three agent/client paths have published end-to-end Battenmark CAD proof rather than being treated only as compatibility targets. Hermes also has separate stock-client protocol interoperability evidence.

ChatGPT Work on macOS — full-fidelity + physical-output proof

ChatGPT Work on macOS
        │
        ▼
    Battenmark
        │
        ▼
FreeCAD 1.1.3 / OpenCascade
        │
        ├── FCStd
        ├── STEP
        ├── STL
        └── 3MF

ChatGPT Work has been exercised through Battenmark with real geometry creation, parametric rebuilds, worker restart/recovery, export, validation and persistence. It also produced a successfully printed 60 × 25 × 4 mm calibration coupon with nominal 3 / 4 / 5 mm through-holes.

The harder corrected two-piece Orange Pi 4 Pro enclosure now also passes its full benchmark through Battenmark:

• base: 96 × 63 × 22 mm;

• lid: 96 × 63 × 6 mm;

• hollow friction rim: 90.6 × 57.6 mm outer / 85.8 × 52.8 mm inner / 2.4 mm walls;

• six true 2.4 × 55 mm through-vents;

• final 3MF: 2 watertight manifold objects;

• boundary edges: 0 / 0;

• non-manifold mesh edges: 0 / 0;

• corrected analytical lid volume: 13,138.56 mm³;

• exported lid mesh volume: 13,138.560000 mm³;

• combined 3MF mesh volume: 41,281.246683 mm³;

• difference from Battenmark export volume: 0.109317 mm³ / 0.000265%;

• fresh-process persistence/reopen: PASS;

• direct FreeCAD bypass: NO.

Overall corrected Orange Pi benchmark: PASS.

Claude via MCP — end-to-end CAD workflow proof

Claude has also been validated through Battenmark's MCP surface into the same authoritative FreeCAD/OpenCascade backend.

A tiny interoperability proof discovered 75 tools, created a 20 × 15 × 5 mm solid, rebuilt it as 1 valid solid / 1,500 mm³, and cleaned up without direct FreeCAD bypass.

Claude then completed the original 50-revision two-piece Orange Pi 4 Pro enclosure workflow entirely through Battenmark. That first hard result was correctly published as PARTIAL because it exposed real lid-rim and vent defects. Those defects became the correction benchmark that was subsequently completed to PASS in ChatGPT Work.

OpenCode + local LLM — end-to-end CAD + slicer proof

OpenCode backed by the tested local model setup independently drove Battenmark into FreeCAD/OpenCascade to create an Xbox controller holder. The authoritative workflow reported 1 valid solid / 458,252 mm³, exported STL and 3MF, and the STL was successfully opened and sliced in ELEGOO Slicer for an ELEGOO Centauri with a 0.4 mm nozzle.

Observed slicer result: 171.21 g model filament, 174.22 g total filament, 3 h 39 min total estimated print time. The holder was intentionally not printed, so this proves CAD execution/export/slicer interoperability — not physical controller fit or ergonomics.

See client validation evidence, the OpenCode local-LLM slicer proof, and the corrected Orange Pi hard benchmark.

Battenmark is intentionally provider-neutral. Other LLM clients/providers should remain compatibility targets until equivalent evidence is published for them. Protocol discovery alone is not treated as proof of autonomous CAD quality.

Related MCP server: freecad-tool-server

Architecture

AI agents / IDE agents / custom software clients
                    │
         MCP / HTTP / Python / CLI
                    │
                    ▼
              Battenmark Core
                    │
         typed CAD operations / CAD IR
                    │
             Backend Registry
                    │
      ┌─────────────┼──────────────────┐
      ▼             ▼                  ▼
   FreeCAD        JSCAD          future adapters
 authoritative    preview      build123d/CadQuery/etc.
   B-rep

• FreeCAD / OpenCascade — authoritative B-rep kernel (headless JSON-lines worker)

• JSCAD — in-process preview/envelope backend (not the source of truth)

Quickstart

Prerequisites: Node.js ≥ 20 and npm. FreeCAD is optional for the core service and required only for the authoritative B-rep backend.

npm install
npx tsc --noEmit   # type check
npm test           # fast kernel-free suites (parametric, selectors, registry)

FreeCAD backend

sh scripts/bootstrap-macos.sh      # macOS: discovers /Applications/FreeCAD.app
sh scripts/install-freecad.sh      # Linux: installs headless 1.0.2 AppImage (no FUSE)
npm run test:freecad               # proves the real worker end-to-end

Discovery order: $AGENTCAD_FREECAD_CMD → macOS FreeCAD.app bundles → Homebrew → extracted Linux AppImage → PATH. See docs/MACOS.md and docs/LINUX.md.

Transports

Python client example:

from agentcad import AgentCad

c = AgentCad(base_url="http://127.0.0.1:8787", token="secret-token")
pid = c.project_create("demo")["project_id"]
c.create_box(pid, 80, 50, 12)
print(c.rebuild(pid)["data"]["volume_mm3"])   # 48000

Golden smoke model

The canonical release smoke test is an 80 × 50 × 12 mm box = 48,000 mm³, verified through JSCAD, FreeCAD, HTTP, CLI, MCP and the Python client (test:transport-parity). Do not change this fixture casually.

Capabilities

• Backend-neutral typed CAD operations with explicit schema (agentcad_schema_version: 2)

• FreeCAD/OpenCascade authoritative B-rep; JSCAD preview

• Scalar parameter expressions and dependency evaluation

• Semantic face/edge selectors (top_perimeter, …) that re-resolve after edits

• Persistent geometry references (gref) with explicit lost/ambiguous errors

• Through / blind / counterbore / countersink holes

• Fillets and chamfers · linear and rectangular patterns

• STEP / FCStd / STL interchange · four-view PNG previews

• Dynamic backend registry with per-backend capability discovery

• One serialized FreeCAD worker with kill/restart recovery

• Assemblies: component definitions, persistent instances, grounded frames, face mates, axis/concentric alignment, distance & angle constraints (see docs/ASSEMBLIES.md)

Platform status

Known limitations

This is pre-1.0 alpha software; APIs may change.

• Assemblies support the current rigid subset; nested assemblies, assembly patterns, and advanced joint types remain unsupported

• No circular patterns

• Threads are cosmetic metadata, not helical solids

• Imported STEP is geometry import — not automatic parametric reconstruction

• Native FCStd documents keep historical PartDesign feature shapes; Battenmark measures the final Body Tip (summing historical solids double-counts)

• Bodies carrying non-manifold-edge warnings can produce unreliable B-rep volume integrals; benchmark evidence should cross-check mesh/analytical volume rather than treating a raw OpenCascade volume number as ground truth in that condition

• The Orange Pi correction exposed an unresolved feature-history discrepancy tracked in issue #26. A focused real-FreeCAD regression on current main shows ordinary existing-pocket depth edits rebuild, export and survive worker restart correctly. The remaining investigation is specific to the benchmark's multi-profile vent sketch and surrounding feature history; it is not currently established as a generic Battenmark worker-synchronization defect.

• One serialized FreeCAD worker (no pooling)

• Preview rendering is JSCAD, not OCC hidden-line

• Complete topological naming is not solved; persistent gref mitigates it

Full list: docs/LIMITATIONS.md.

Documentation

Compatibility identifiers

Public branding is Battenmark. Historical engineering identifiers remain on purpose and are a compatibility surface, not a second brand: AgentCadService, agentcad_schema_version, AGENTCAD_* environment variables, the agentcad / agentcad-mcp binaries. The internal service version 0.5.6 intentionally differs from the release tag; see docs/VERSIONING.md.

Contributing & security

See CONTRIBUTING.md and SECURITY.md. Code of Conduct: CODE_OF_CONDUCT.md.

Phase 8B Release Candidate Evidence

Qualified candidate SHA: 31ee9369fe84b35d83932e86bf9fd0b64564aedd

This SHA passed:

• All 9/9 CI jobs (exact-main matrix)

• FreeCAD discovery and validation

• TypeScript strict check

• Full test suite (kernel-free + FreeCAD + gref + transport parity)

• User Trial 001 (42/42 HTTP operations, USB + microSD holder, 305,698.91 mm³)

• Repository hygiene & legal/release docs review

• Five canonical demos (A–E)

Five Canonical Demos

*Demo D: Body/multi-body geometry and export were performed over HTTP; full assembly constraints and DOF diagnostics used the MCP transport. The demo met its designed acceptance criteria by intentionally using MCP for the assembly portion.

User Trial 001: docs/demos/user-trial-001.md

Each demo summary page contains: purpose, prompt summary, result, validation, exact candidate SHA, and a link to the full Drive evidence archive.

Media Assets

Key Technical Findings (Preserved)

• Demo A: Face selector ambiguity after boolean union is avoided by creating features on individual bodies before union.

• Demo B: STEP import requires workspace path (not raw base64); boolean operation is boolean_cut.

• Demo D: Full assembly constraint/DOF path uses MCP; HTTP supports body/multi-body geometry/export only.

• Demo E: Three resolution paths (face enum, centroid_near spatial selector, created_by feature reference) converge on identical geometry.

License

Apache-2.0 for this repository. FreeCAD/OpenCascade are invoked as a separate LGPL process (the worker scripts run inside FreeCADCmd). See LICENSE, NOTICE and THIRD_PARTY_NOTICES.md.