llms.txt

# Bitbybit Monorepo

> 3D CAD algorithms and NPM packages for web-based parametric modeling and visualization, free to use in any project. Build once, run anywhere - no installation required.

This monorepo contains the open-source TypeScript of the Bitbybit npm packages, which integrate 3D CAD capabilities into web applications using BabylonJS, Three.js, or PlayCanvas game engines.

It is written for people and for AI coding agents alike: the whole API is published as an MCP server, as context files and as TypeScript declarations, addressed by exact version. See "AI Context" below.

## Repository

- GitHub: https://github.com/bitbybit-dev/bitbybit
- License: MIT, including the Bitbybit OCCT Kernel that @bitbybit-dev/occt ships; the source of its C++ kernel layer is not published (closed source); OCCT inside it is LGPL-2.1 with the Open CASCADE exception

## Documentation

- Learn Bitbybit: https://learn.bitbybit.dev
- TypeScript API Reference: https://docs.bitbybit.dev
- Main Platform: https://bitbybit.dev

## Quick Start

```bash
npx @bitbybit-dev/create-app my-project
```

Choose your game engine and start coding immediately.

## NPM Packages

### Game Engine Integrations

| Package | Description | NPM |
|---------|-------------|-----|
| @bitbybit-dev/babylonjs | BabylonJS visualization and drawing | https://www.npmjs.com/package/@bitbybit-dev/babylonjs |
| @bitbybit-dev/threejs | Three.js visualization and drawing | https://www.npmjs.com/package/@bitbybit-dev/threejs |
| @bitbybit-dev/playcanvas | PlayCanvas visualization and drawing | https://www.npmjs.com/package/@bitbybit-dev/playcanvas |

### Core Packages

| Package | Description | NPM |
|---------|-------------|-----|
| @bitbybit-dev/core | Combined CAD kernel features | https://www.npmjs.com/package/@bitbybit-dev/core |
| @bitbybit-dev/base | Base algorithms (vector math, transforms) | https://www.npmjs.com/package/@bitbybit-dev/base |

### CAD Kernel Packages (Main Thread)

| Package | Description | NPM |
|---------|-------------|-----|
| @bitbybit-dev/occt | OpenCascade B-rep CAD wrapper | https://www.npmjs.com/package/@bitbybit-dev/occt |
| @bitbybit-dev/jscad | JSCAD CSG modeling wrapper | https://www.npmjs.com/package/@bitbybit-dev/jscad |
| @bitbybit-dev/manifold | Manifold mesh booleans wrapper | https://www.npmjs.com/package/@bitbybit-dev/manifold |
| @bitbybit-dev/ifc | IFC building models (BIM): author, write and read IFC4 files in TypeScript, Node.js and browser (beta) | https://www.npmjs.com/package/@bitbybit-dev/ifc |

### Web Worker Packages (Non-blocking, Recommended)

These packages run geometry computations in web workers for non-blocking UI. Same API as main thread packages, but all operations are asynchronous.

| Package | Description | NPM |
|---------|-------------|-----|
| @bitbybit-dev/occt-worker | OpenCascade via web worker | https://www.npmjs.com/package/@bitbybit-dev/occt-worker |
| @bitbybit-dev/jscad-worker | JSCAD via web worker | https://www.npmjs.com/package/@bitbybit-dev/jscad-worker |
| @bitbybit-dev/manifold-worker | Manifold via web worker | https://www.npmjs.com/package/@bitbybit-dev/manifold-worker |
| @bitbybit-dev/ifc-worker | IFC via web worker (beta) | https://www.npmjs.com/package/@bitbybit-dev/ifc-worker |

### Tooling Packages

| Package | Description | NPM |
|---------|-------------|-----|
| @bitbybit-dev/create-app | CLI that scaffolds a frontend or full-stack CAD Cloud project | https://www.npmjs.com/package/@bitbybit-dev/create-app |
| @bitbybit-dev/cad-cloud-sdk | TypeScript SDK for the CAD Cloud REST API | https://www.npmjs.com/package/@bitbybit-dev/cad-cloud-sdk |
| @bitbybit-dev/mcp | MCP server documenting this API for AI coding agents, version-exact | https://www.npmjs.com/package/@bitbybit-dev/mcp |

## Package Structure

```
packages/
└── dev/
    ├── babylonjs/         # BabylonJS integration
    ├── threejs/           # Three.js integration
    ├── playcanvas/        # PlayCanvas integration
    ├── core/              # Core combining all kernels
    ├── base/              # Base algorithms
    ├── occt/              # OpenCascade wrapper
    ├── occt-worker/       # OCCT web worker
    ├── jscad/             # JSCAD wrapper
    ├── jscad-worker/      # JSCAD web worker
    ├── manifold/          # Manifold wrapper
    ├── manifold-worker/   # Manifold web worker
    ├── create-app/        # Project scaffolding CLI
    ├── cad-cloud-sdk/     # TypeScript SDK for the CAD Cloud REST API
    └── mcp/               # MCP server documenting the API for AI agents
```

## AI Context

For AI coding assistants, use these resources to get comprehensive Bitbybit API knowledge. An agent
working from memory invents plausible function names that do not exist, so give it one of these.
The MCP servers are the best answer where the host supports them; the context files below are for
assistants that cannot connect to one.

### Bitbybit CAD MCP (first party, free, no account) - start here

Answers every question about the API - full signature, parameter defaults, return type, examples -
for the exact version your project has installed, from the index published with each release.
Read-only; it never runs geometry.

- Remote (Streamable HTTP): https://mcp.bitbybit.dev/mcp
- Local (stdio): npx -y @bitbybit-dev/mcp
- Package: https://www.npmjs.com/package/@bitbybit-dev/mcp
- Guide: https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/bitbybit-mcp

Claude Code:
```bash
claude mcp add --transport http bitbybit https://mcp.bitbybit.dev/mcp
```

VS Code (`.vscode/mcp.json`) - the `type` is required:
```json
{
    "servers": {
        "bitbybit": { "type": "http", "url": "https://mcp.bitbybit.dev/mcp" }
    }
}
```

Cursor (`.cursor/mcp.json`):
```json
{
    "mcpServers": {
        "bitbybit": { "url": "https://mcp.bitbybit.dev/mcp" }
    }
}
```

Every answer carries a tier: `oss` runs in these MIT packages anywhere, `platform-pro` inside the
bitbybit.dev editors, `cloud-pro` only on CAD Cloud with a key.

### Bitbybit CAD Cloud MCP (first party, API key)

Runs the geometry instead of only describing it: operations, pipelines, parametric models, STEP to
glTF conversion and the Pro algorithms, on CAD Cloud, with the results returned as download links.

- Remote: https://api.bitbybit.dev/mcp
- Guide: https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/cad-cloud-mcp

```bash
claude mcp add --transport http bitbybit-cloud https://api.bitbybit.dev/mcp --header "X-API-Key: <your key>"
```

### Where geometry should run

Guidance an agent should follow when it chooses between the packages and CAD Cloud:
https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/agentic-cad

### Overview of all AI options

https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/intro

### AI Prompt Context Files (v1.6.1)

#### Beginner Context (Monaco Editor)
For online TypeScript editor at bitbybit.dev:
- Full Context (116k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-babylon-monaco-ai-context.md

#### BabylonJS Context
- Full (116k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-babylon-ai-context.md
- Lite (114k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-babylon-no-comment-min-ai.md

#### Three.js Context
- Full (95k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-three-ai-context.md
- Lite (82k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-three-no-comment-min-ai.md

#### PlayCanvas Context
- Full (94k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-playcanvas-ai-context.md
- Lite (82k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-playcanvas-no-comment-min-ai.md

### TypeScript Declaration Files (.d.ts)

For AI agents that struggle with dictionary translation, use these full TypeScript type definitions:

#### BabylonJS Declarations
- With Comments (~500k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-babylon-formatted.d.ts
- Without Comments (~180k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-babylon-formatted-no-comments.d.ts

#### Three.js Declarations
- With Comments (~420k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-three-formatted.d.ts
- Without Comments (~150k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-three-formatted-no-comments.d.ts

#### PlayCanvas Declarations
- With Comments (~420k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-playcanvas-formatted.d.ts
- Without Comments (~150k tokens): https://git-cdn.bitbybit.dev/v1.6.1/ai-context/bitbybit-playcanvas-formatted-no-comments.d.ts

### Context7 MCP (third party)

Indexes the documentation site and works with Claude, Gemini and Grok. A reasonable addition when
you already use Context7; it does not know the API as exactly as the two first-party servers above.

Add to your `.vscode/mcp.json`:

```json
{
    "servers": [
        {
            "command": "npx",
            "args": ["-y", "@upstash/context7-mcp@latest"],
            "env": {
                "DEFAULT_MINIMUM_TOKENS": "10000"
            }
        }
    ]
}
```

- Context7 Library: https://context7.com/bitbybit-dev/bitbybit
- Integration Guide: https://learn.bitbybit.dev/learn/using-ai-with-bitbybit/mcp/context-7

## Integration Guides

- Three.js: https://learn.bitbybit.dev/learn/npm-packages/threejs
- BabylonJS: https://learn.bitbybit.dev/learn/npm-packages/babylonjs
- PlayCanvas: https://learn.bitbybit.dev/learn/npm-packages/playcanvas
- Engine Agnostic: https://learn.bitbybit.dev/learn/npm-packages/game-engine-agnostic

## Geometry Kernels

### OpenCascade (OCCT)
Industrial-grade B-rep kernel:
- Boundary representation for exact geometry
- Boolean operations (union, difference, intersection)
- Fillets, chamfers, shell, offset operations
- STEP/IGES import/export
- Sweeps, lofts, pipes, revolutions

### JSCAD
JavaScript-based CSG modeling:
- Constructive solid geometry operations
- Lightweight for simple shapes
- STL export for 3D printing

### Manifold
Fast mesh boolean operations:
- Optimized for real-time operations
- GPU-accelerated
- Ideal for interactive applications

## Example Applications

- Laptop Holder: https://github.com/bitbybit-dev/app-examples/tree/main/angular/laptop-holder
- Cup Configurator: https://github.com/bitbybit-dev/app-examples/tree/main/react/cup
- Live Demos: https://app-store.bitbybit.dev

## Contributing

- Contributing Guide: CONTRIBUTING.md
- Code of Conduct: CODE_OF_CONDUCT.md
- Unit Testing Guide: UNIT_TESTING_GUIDE.md

## Community

- Discord: https://discord.gg/GSe3VMe
- YouTube: https://www.youtube.com/@bitbybitdev

## Support the Project

Your contributions allow this project to exist:

- Silver/Gold Plans: https://bitbybit.dev/auth/pick-plan
- 3D Bits Shopify App: https://apps.shopify.com/3d-bits-1
- Crafts Shop: https://crafts.bitbybit.dev

## Related llms.txt Files

- Main Platform: https://bitbybit.dev/llms.txt
- Documentation: https://learn.bitbybit.dev/llms.txt