npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

brepjs-cad

v0.194.1

Published

brep CLI, MCP server, and agent skills that let coding agents write brepjs CAD parts and verify them on a real kernel

Readme

brepjs-cad

A brainstorm → design → author → verify → polish pipeline for authoring parametric CAD with brepjs, plus the brep CLI that runs each part on a real geometry kernel and reports what it measured.

It ships as two cooperating pieces on two rails; install both.

1. The skills (Claude Code plugin)

Five composable, individually-improvable skills — brepjs:brepjs-brainstorm (scope a request into a spec) → brepjs:brepjs-design (decompose it into a build sequence) → brepjs:brepjs-implement (author the .brep.ts) → brepjs:brepjs-verify (judge it by the report) → brepjs:brepjs-polish (make it look designed, then export) — plus a wait-gated /brepjs:cad command that drives the whole pipeline and brepjs-implementer/verifier/polisher worker agents it fans out to. The geometry-producing skills self-heal via /heal-skill <target>. Each skill also auto-triggers standalone. Delivered via the brepjs marketplace (git), not npm — Claude Code discovers skills from plugins, never from node_modules:

/plugin marketplace add andymai/brepjs
/plugin install brepjs@brepjs

Or non-interactively from a terminal: claude plugin marketplace add andymai/brepjs && claude plugin install brepjs@brepjs.

Then ask for a part in plain English and Claude reaches for the pipeline on its own, or drive it explicitly: /brepjs:cad "a wall bracket for a 40 mm pipe with two M4 holes" runs the full gated pipeline; /brepjs:brepjs-brainstorm … /brepjs:brepjs-polish run a single phase.

2. The runtime (npm)

The CLI the skill invokes. Install it in your project, where brepjs + the WASM kernel resolve (Node module resolution is project-local, so the runtime can't live in the plugin dir):

npm i -D brepjs-cad brepjs occt-wasm

API reference

The package bundles brepjs's full API reference for offline/agent use: the complete export surface with signatures and examples:

  • reference/llms-full.txt: every export, full signatures (the deep reference)
  • reference/llms.txt: the same content as a quicker index

Point your agent at node_modules/brepjs-cad/reference/llms-full.txt for anything the skill's curated references don't cover.

The .brep.ts contract

A model is a module whose default export is a zero-arg function returning a shape (or a Result<shape>):

// bracket.brep.ts
import { box } from 'brepjs';
export default () => box(40, 20, 10, { centered: true });

Usage

npx -y -p brepjs-cad brep part.brep.ts --step part.step --json report.json   # primary STEP + deterministic report
npx -y -p brepjs-cad brep part.brep.ts --snapshot shots/                     # iso/front/top/right PNGs
npx -y -p brepjs-cad brep part.brep.ts --serve                               # preview server + opens the viewer in your browser
npx -y -p brepjs-cad brep part.brep.ts --serve --no-open                     # preview server; just print the URL (no browser)

--snapshot/--serve use the bundled viewer (shipped under viewer/dist, including the OCCT WASM). It renders in brepjs's native Z-up coordinates: Z is up, the XY plane is horizontal, and models are never rotated to fit the renderer's convention. The --serve link is interactive: a toolbar offers view presets + fit, solid/wireframe/x-ray modes, edge/grid toggles, a turntable, click-to-inspect face picking, a section/clipping plane, a measurements panel, and an in-browser PNG screenshot. --snapshot loads the same page with ui=0 to suppress the toolbar, and burns the bounding-box size into each PNG (dims=1) so the agent can read scale from the image.

--serve prints the viewer URL and, in an interactive terminal, opens it in your default browser. Auto-open is skipped when it would be unwanted: when the server is reused (a tab is already open), under CI, when output is piped (non-TTY, e.g. agent runs), or on Linux with no display server. Pass --no-open to always suppress it.

CLI reference

The brep bin is a multi-command CLI. verify is the default command, so brep part.brep.ts runs it directly.

| Command | What it does | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | brep verify <files...> | Default command. Loads the part, runs deterministic checks, prints the JSON report. Flags: --check, --json <out\|->, --step <out>, --glb <out>, --snapshot <dir>, --serve, --no-open, --expect-code <CODE> / --expect-invalid (assert a known-bad part fails the right way — for fixtures/eval). Multiple files or a quoted glob → a validity-only JSON array. Exits non-zero when not ok (unless --serve). | | brep init <name> | Scaffolds a parameterized <name>.brep.ts + tsconfig.json + README.md into ./<name> (or --out <dir>). Never overwrites existing files. | | brep watch <file> | Re-verifies on every save until Ctrl-C (debounced; watches the parent dir to survive editor rename-on-save). | | brep preview <file> | Element-aware live viewer for a model module (families element tree, resolved tree, or plain shape): key-path picking, failed elements listed, real edges. --watch re-evaluates on save and pushes to the open tab; --write-only (CI), --glb <out>, --json <out>, --port <n>, --no-open. | | brep export <file> | Batch artifacts behind a validity gate: --step, --glb, --stl, or --all; --3dm writes an element-aware Rhino file (one named object per element, layered; needs the optional rhino3dm install; not combinable with the other formats); --out <dir> (default .). Exits non-zero on failure. | | brep publish <file> | Writes a static page for the part into --out <dir>: one control for each parameter it declares, a 3D view, STEP/3MF/STL downloads, and its source. The page builds the part in the browser, needs no server or special headers, and works on any static host. --title <text>, --force (write into a directory that holds other files). Verifies the part first; exits non-zero and writes nothing when it is not ok. | | brep measure <a> [b] | Measurements for one part; with a second module, the distance between the two parts. | | brep diff <a> <b> | Compares the measurements of a baseline and a comparison module. | | brep snapshot <file> | Standalone multi-view PNG capture (no report assertions): --out <dir>, --label <tag> (subfolder, for pre/post A/B pairing). Renders on a private ephemeral server so parallel snapshots don't contend. Requires the optional puppeteer/Chrome dependency; degrades with a clear message when absent. (Also available inline via verify --snapshot <dir>.) | | brep verify --serve | Preview server with a ?dir=&file= deep link, surfaced via verify --serve. Auto-opens the browser in an interactive terminal (suppressed under CI / non-TTY / no display, or with --no-open). |

Every command writes a single machine-readable JSON document to stdout; diagnostics (paths, kernel chatter, watch notices) go to stderr.

verify, export, snapshot, and watch take --param <name=value> (repeatable). It sets a parameter that the part declares with export const params = defineParams({ ... }), and the report lists the values in use as params. A value outside its limits, or a name that is not declared, stops the build with an error code.

MCP server

brep-mcp is a stdio MCP server that exposes the verify substrate to MCP-capable agents (Claude Code, Claude Desktop, any MCP client).

Parts

| Tool | Input | Returns | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | run_program | { code: string, timeoutMs?: number } | Executes the brepjs .brep.ts source in an isolated, timeout/OOM-bounded sandbox and returns the verification report (validity, measurements, topology) as JSON. isError is set when the part fails checks, times out, or crashes. | | export_part | { code, outDir, formats?: { step, glb, stl }, timeoutMs? } | Builds the part in the sandbox and writes STEP, GLB and STL files to outDir, returning the written paths. |

This is the closed build → verify loop as a single call: the agent sends part source, gets back the deterministic report. The program runs in a separate process with a wall-clock timeout and a memory cap, so a runaway part can't hang the agent.

BIM sessions

The session tools open a building model and keep it built, so an agent can find elements, edit the program, and see exactly what its edit changed. A model is a brepjs-families program (a .tsx or .ts module whose default export is an element tree) or an .ifc file. Families elements are addressed by key path (ground/south/voids:entry), IFC elements by GlobalId.

| Tool | Does | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | open_model | Builds a program (type-checked first) or imports an IFC file in a sandboxed worker. Returns a sessionId, a buildHash, and element counts by category, storey and family. | | list_sessions | Open sessions. A session is stale when its source files changed since the last build. | | close_model | Stops the session's worker. | | rebuild | Rebuilds after an edit and diffs against the last good build: added and removed ids, prop and pset before/after values, geometry, volume and bounds changes. A rebuild that fails to build, or whose geometry newly fails for an element that built before, keeps the last good build. | | get_diff | Pages through the last rebuild's diff when it is longer than the 100 entries per list a rebuild returns. | | query_elements | Finds elements by category, family, storey, name or id glob, prop and pset predicates, and bounds. Returns ids plus counts by category, storey and family. | | get_elements | Identity, props, psets, quantities, material, classification, relationships, children and geometry for the given ids, plus the file and line that author each families element. | | list_schedulable_fields | The fields a selection carries for a schedule (built-ins, props, psets, quantities), with each one's type and how many elements have it. | | schedule | A schedule of the selected elements: one row per element, or grouped with counts and sums, sorted and totalled, optionally written as CSV. Families quantities come from an in-memory IFC export, so they match export_ifc. | | validate_model | Runs brepjs-bim's checks (referential integrity, schema, round trip, gherkin rules, solid geometry) and returns findings mapped to key paths or GlobalIds, 200 at a time. A families model is checked as its IFC export would be written. | | compare_models | Diffs two sessions of the same kind by element identity, such as two revisions of an IFC file, including families quantity sets. | | create_issue | Raises a BCF 3.0 issue on elements (by IFC GlobalId) with a render_view camera and snapshot, into a new .bcf file or one it adds to. A families session needs export_ifc first. Needs puppeteer. | | read_issues | Reads a .bcf file's topics, comments and viewpoints, resolving each GlobalId to a session's element id when given a session. | | plan_view | Draws a storey plan: a cut 1200 mm over the floor (or cutHeight), cut elements on CUT-<category> layers and what lies below on BEYOND, by hidden-line projection. Returns a PNG preview and saves SVG, DXF or PNG with outPath. | | section_view | Draws a vertical section square to x or y, cut elements by category and what lies beyond, the same way. | | get_spaces | Lists spaces with floor area, perimeter, volume and outline measured from each solid, beside the IFC base quantities recorded for them. | | export_cobie | Writes a families session's COBie 2.4 sheets (CSV per sheet, or JSON) from the BIM projection export_ifc uses. | | show_model | Opens the build in an interactive viewer the user can orbit and click: inline in clients that support MCP Apps (served as ui://brep-mcp/viewer), a local preview URL otherwise. Takes highlight, isolate and colorBy. | | select_elements | Selects elements (ids or globs) in the open viewer. | | show_elements | Frames the open viewer's camera on elements and selects them. | | get_viewer_selection | Returns what is selected in the viewer: what the user last clicked, or the agent last selected. | | render_view | Renders the current build to 1200 x 900 PNGs, returned as images. highlight draws the given ids or globs in orange over a ghosted model, isolate draws only them, colorBy colors by category, storey or family with a legend, and plan draws one storey from above, cut 1200 mm over its floor. Needs puppeteer. | | export_ifc | Writes a families session's current build to an .ifc file through brepjs-bim's validated export, returning the validation report by key path, any proxied elements, and each key path's GlobalId. Asks before replacing an existing file. | | search_reference | Searches the bundled reference (the brepjs API reference, the brepjs-families docs, and the families-to-IFC guide) and returns the best-matching sections. Needs no session. | | eval_in_session | Runs agent TypeScript against a session's live build (records, the resolved tree, B-rep shapes, or the imported IFC model) and returns the JSON result and console output. Listed only when the server starts with --allow-code. |

Each session also serves brep://sessions/{sessionId}/tree (the element tree) and brep://sessions/{sessionId}/elements/{elementId} (one element) as resources, every bundled reference file is a brep://reference/... resource, and the families starter registry is brep://families/registry (each family with its npx brepjs add command) and brep://families/registry/{name} (its source). Prompts walk an agent through common jobs: inspect-building opens and summarizes a model, edit-and-verify makes one checked edit, quantity-takeoff schedules a category's quantities per storey, compare-revisions summarizes and shows what changed between two models, ifc-review checks an IFC file and raises its problems as BCF issues, model-check validates a families model and fixes what it can, including BCF issues raised on its export, and export-deliverables writes a checked model's IFC, COBie, plans and schedules. Query tools take an optional expectBuild: pass the buildHash you queried against and the call fails if the model was rebuilt since. Up to four sessions can be open at once. Opening or exporting an .ifc file needs brepjs-bim and web-ifc installed in the project. An opened IFC file can be queried and rendered but not exported again.

Connect (local build)

Build the package, then register the server by absolute path. Run both commands from the package root (packages/brepjs-cad), where dist/ is emitted. $(pwd) is resolved by your shell at that location:

npm run build   # emits dist/mcp/server.js
claude mcp add brep -- node "$(pwd)/dist/mcp/server.js"

Once the package is published to npm, the same server is available without a local build:

claude mcp add brep -- npx -y --package brepjs-cad brep-mcp

The server runs locally as a child process of your agent (stdio); geometry never leaves your machine.

Examples gallery

Few-shot examples live under skills/brepjs-implement/examples/<name>.brep.ts, each with a <name>.expected.json baseline. Grouped by category:

  • Primitives + booleans: mounting-bracket, flanged-coupler, transform-bracket
  • 2D sketch → solid: extruded-bracket (extrude), revolved-pulley (revolve), swept-gasket (sweep)
  • Modifiers: rounded-block (fillet), chamfered-block (chamfer), hollow-enclosure (shell)
  • Gridfinity primitives: gridfinity-baseplate, gridfinity-bin, gridfinity-divider

For larger programs, see the playground examples. Each page has the full code of one model.

Eval / scorecard

npm run eval (bench/run.ts) replays every skills/brepjs-implement/examples/*.brep.ts with a sibling *.expected.json through the public runPart runtime, compares measured volume/area/validity/shape-type against the recorded baseline within each file's tolerance (default 0.5%), prints a PASS/FAIL scorecard, and exits non-zero on any regression. It is deterministic (no LLM or API key) so it runs in CI as the package's regression net. Refresh a baseline by re-recording the example's *.expected.json after an intentional geometry change.

Manual skill eval (/eval-skill)

The fast iteration loop — run on your Claude subscription, no API key, no billing. The /eval-skill slash command drives the same bench/prompts.ts corpus through the current Claude Code session: Claude authors each part from the deployed SKILL.md, runs verify --check --snapshot, judges the rendered snapshots against each prompt's rubric, emits the two-signal scorecard, and proposes SKILL.md fixes from the failures. This is the recommended way to answer "did my SKILL.md edit help?" — see .claude/commands/eval-skill.md.

Live eval (npm run eval:live)

The automated / isolated counterpart to /eval-skill — opt-in and billed. An SDK harness sends the bench/prompts.ts prompts to a model with the deployed SKILL.md as the system prompt (so it measures the skill in isolation, not inside a Claude Code session), then verifies each generated part two ways:

  • Auto (objective): runPart --check → valid solid + any pinned dims within tolerance.
  • Judge (intent): a multimodal Claude call looks at the rendered iso/front/top/right snapshots and decides whether the part matches the request + rubric.

The scorecard reports per-category valid / judge / both rates and stamps the model + resolved brepjs version + date (so trend lines don't mix kernel versions).

ANTHROPIC_API_KEY=sk-... npm run eval:live -w brepjs-cad          # opus by default
ANTHROPIC_API_KEY=sk-... npm run eval:live -w brepjs-cad -- --model claude-sonnet-4-6
#   --only <id|category>   run a subset      --keep   keep the generated parts

Opt-in and billed (real API calls), so it does not run in CI; the deterministic replay above is the CI gate. Snapshots (hence the judge) need puppeteer/Chrome; without them the run scores on auto-verify alone and notes the skipped judge.

Programmatic API

import { runPart, runChecks, serializeReport } from 'brepjs-cad';

const { shape, report, step } = await runPart('part.brep.ts', { step: true });
console.log(serializeReport(report)); // { ok, shapeType, checks, measurements, errors }

How verification works

Deterministic checks are the source of truth (validity brands (validSolid), measureVolume/measureArea, and bounding box) surfaced as a JSON report. Multi-view PNG snapshots are a diagnostic layer, never a substitute for a measurement. STEP is the primary, validated artifact; GLB/STL are derived previews.