- Rust 67.5%
- TypeScript 30.6%
- Shell 0.9%
- Makefile 0.6%
- CSS 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .claude | ||
| demo/docker | ||
| docs | ||
| public | ||
| scripts | ||
| src | ||
| src-tauri | ||
| .env.local.example | ||
| .gitignore | ||
| AGENTS.md | ||
| BACKLOG.md | ||
| CLAUDE.md | ||
| index.html | ||
| Makefile | ||
| package-lock.json | ||
| package.json | ||
| postcss.config.cjs | ||
| README.md | ||
| tsconfig.json | ||
| tsconfig.node.json | ||
| vite.config.ts | ||
Mirrored on GitHub — development happens here: https://git.hauptstadt.monster/manzari/BenchVault
BenchVault
A cross-platform (Linux-first) desktop app for organizing 3D-printing projects. Each Object groups the STL parts, OpenSCAD sources, sliced gcodes, images, and notes that belong to one thing you print — with slicer metadata parsed automatically and everything searchable.
BenchVault owns a managed library on disk (human-readable folder layout), so your files stay plain files you can browse, back up, or take with you.
Screenshots
Regenerating these screenshots
make shots builds a throwaway demo library inside Docker (your real library is never in reach) and drives the actual binary through tauri-driver to capture docs/screenshots/.
The demo library is seeded by importing real things from Thingiverse through the same "Import from URL" code path the app ships, so the screenshots show genuine models, covers, authors and licenses rather than placeholder geometry. That needs a Thingiverse API token:
-
Create an app at https://www.thingiverse.com/developers/apps (any type — you only need its App Token).
-
Put it in the repo-root
.env, which is gitignored:THINGIVERSE_TOKEN=your-app-token
make shots picks it up from there and passes it into the container; the seeder clears it from the demo database again once the imports are done. Same token works for the app's own "Import from URL" — paste it into Settings.
make build # release binary
make seed-bin # demo seeder
make shots # seed + capture into docs/screenshots/
Workflow
BenchVault sits at the centre of a print project — from CAD source to a printed part — keeping every artifact filed against the Object it belongs to.
flowchart LR
A["<b>Design</b><br/>OpenSCAD · FreeCAD ·<br/>Blender · any 3D tool"] -->|export STL| B
B["<b>BenchVault</b><br/>organize into an Object:<br/>models · CAD scripts ·<br/>images · docs · tags"]
B -->|open .scad in GUI /<br/>render preview| A
B -->|slicer hand-off| C["<b>OrcaSlicer</b><br/>slice → gcode"]
C -->|auto-ingest gcode<br/>+ parsed metadata| B
B -->|USB sync<br/>+ manifest| D[("<b>USB drive</b>")]
D --> E["<b>3D printer</b><br/>print the part"]
classDef hub fill:#2b6cb0,stroke:#1a365d,color:#fff;
class B hub;
- Design a part in OpenSCAD (or FreeCAD, Blender, …) and export an STL — or import from a URL (Thingiverse, a GitHub/GitLab/Codeberg repo, MyMiniFactory).
- Organize it in BenchVault: models (STL/OBJ/STEP/3MF), CAD scripts (
.scad, CadQuery.py), images, markdown docs and notes all live under one Object. Open.scadfiles back in the OpenSCAD GUI or render previews in-app. - Slice by handing an asset straight to OrcaSlicer; the resulting gcode is auto-ingested with its slicer metadata parsed.
- Sync the gcodes to a mounted USB drive with a manifest.
- Print — feed the USB stick to the printer.
Features
- Library organization — nested folders, objects with cover images, tags, manual sort order, breadcrumb navigation.
- 3D preview — interactive three.js viewer for STL and OBJ; snapshot any angle as the object's cover image.
- Model geometry — triangle/vertex counts, bounding-box size, volume, surface area, and watertightness computed on import for STL, OBJ, and 3MF; 3MF also carries its declared units, document metadata, and an embedded thumbnail that auto-fills the object cover.
- Docs & CAD scripts — keep markdown notes (rendered as GitHub-flavored markdown) and CadQuery/OpenSCAD scripts filed alongside the part.
- Gcode metadata — slicer, profile, print time, filament usage parsed on import. Supports the PrusaSlicer family (PrusaSlicer, SuperSlicer, OrcaSlicer, BambuStudio) and Cura.
- OpenSCAD support — open
.scadsources in the OpenSCAD GUI, render previews via the OpenSCAD CLI (cached on disk), and see extracted customizer parameters, dependencies, and module/function names in the CAD Scripts list. - Slicer hand-off — open assets directly in OrcaSlicer.
- Import from URL — one field, source auto-detected from the link:
- Thingiverse — title, author, license, and cover image; with an API token the model files are downloaded too.
- Git hosts — GitHub, GitLab, or Codeberg repositories (or a
/tree/<branch>/<folder>subfolder link) are downloaded and every model/gcode/image inside is parsed into the object; any other.gitURL is cloned. Optional per-host tokens unlock private repos. - MyMiniFactory — title, author, license, and cover image via an API key (file downloads require their OAuth login, not yet supported).
- USB sync — detect mounted drives and sync gcodes to them with a manifest, for printers fed by USB stick.
- Auto-ingest — a background watcher picks up files dropped into the library directory and files them automatically.
- Full-text search — SQLite FTS5 across the library.
- AI access (MCP) — an optional local MCP server lets Claude Code (or another MCP client) browse, search and, if you allow it, organize the library. Folders and objects marked Hide from AI are left out. See AI access (MCP).
Supported formats
Everything you import is stored as a plain file in the managed library. The table shows what BenchVault does beyond storing it — parse metadata, preview in 3D, render, or hand off to the slicer.
| Format | Stored | Metadata | Preview | Render | Hand-off |
|---|---|---|---|---|---|
STL (.stl) |
✅ | ✅ geometry | ✅ | — | ✅ to orca |
OBJ (.obj) |
✅ | ✅ geometry | ✅ | — | — |
3MF (.3mf) |
✅ | ✅ | — | — | ✅ to orca |
G-code (.gcode, .gco, .g) |
✅ | ✅ | — | — | ✅ to usb drive |
G-code binary (.bgcode) |
✅ | — | — | — | ✅ to usb drive |
OpenSCAD (.scad) |
✅ | ✅ static | ✅ via render | ✅ | — |
CadQuery (.py) |
✅ | — | — | — | — |
Markdown (.md, .markdown) |
✅ | — | ✅ via render | ✅ | — |
Text (.txt) |
✅ | — | ✅ verbatim | — | — |
CAD / STEP (.step, .stp, .iges, .igs, .f3d, .sldprt) |
✅ | — | — | — | — |
Images (.png, .jpg, .jpeg, .webp, .gif, .bmp, .svg) |
✅ | — | ✅ some formats | — | — |
Anything else (.pdf, .zip, …) |
✅ | — | — | — | — |
Models (STL/OBJ/STEP/3MF) share one Models section; STL and OBJ render directly in the in-app 3D viewer, while STEP and 3MF are stored and listed (3MF still gets its geometry and metadata parsed on import). OpenSCAD and CadQuery scripts share a CAD Scripts section (OpenSCAD sources also render to a previewable mesh, and their parameters/dependencies are listed). Markdown files render as formatted notes in a Docs / Notes section, and plain .txt files render verbatim there too. Images double as object cover art (snapshot the 3D viewer, set any imported image, or let a 3MF's embedded thumbnail fill in). STL parts are the only assets sent to OrcaSlicer.
AI access (MCP)
BenchVault can run an MCP server inside the app, so an AI assistant such as Claude Code can look through your library and, if you allow it, organize it. The server is off until you turn it on.
Hide from AI
Any folder or object can be marked Hide from AI. Hidden items never appear in anything the MCP server returns: listings, search results, tags, file contents. Asking for a hidden item by id gives the same "not found" error as an id that doesn't exist. The app itself is unchanged; you still see and edit everything.
- Folders: click the robot icon on the folder's row in the library sidebar. A lock icon marks a hidden folder.
- Objects: use the Hide from AI switch under AI access in the object's sidebar. Hidden objects get a lock next to their name and a "Hidden from AI" badge on their card.
Hiding is inherited. A hidden folder hides every subfolder and object inside it; those show a dimmed lock. Files follow their objects: a file attached to a hidden object is hidden, even if it is also attached to a visible one. Tags used only on hidden items are not listed.
Moving an object out of a hidden folder to a visible place asks for confirmation, because the object becomes visible. To keep it hidden, turn on its own Hide from AI switch before moving it; the switch stays usable while the object is hidden through its folder. Deleting a hidden folder keeps the subfolders and objects that drop to the root hidden.
Connecting Claude Code
-
Open Settings → AI access (MCP) and turn on Enable MCP server. The first time, BenchVault creates an access token.
-
Pick an access level (see below). The default is read-only.
-
Copy the command from the card (it includes the token) and run it once in a terminal:
claude mcp add --transport http benchvault http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <token>"
The server speaks Streamable HTTP at http://127.0.0.1:<port>/mcp, port 47821 unless you change it. It listens on 127.0.0.1 only, every request needs the bearer token, and requests that carry an Origin header (that is, from web pages) are refused. Other MCP clients that support Streamable HTTP with a custom header can use the same URL and header.
Changing the port restarts the server. Regenerate replaces the token and the old one stops working at once. After either, update your client with the new URL or token. Changing the access level takes effect immediately, also for clients that are already connected. Turning the server off keeps the token. If the port is in use, the card shows "failed to start" with the error.
Read-only and read & write
Read-only (the default) offers seven tools:
| Tool | What it does |
|---|---|
list_folders |
Every visible folder, with its path and object count |
list_objects |
Pages through objects; filter by folder, root only, or tag |
get_object |
One object: notes, source URL, author, license, tags, and its files with gcode or mesh metadata |
search |
Full-text search over object names and notes, folder names and file names; name matches come first, then alphabetical (not ranked by relevance) |
list_tags |
Tags in use on visible items, with counts |
read_asset_text |
Text from the start of a markdown, text, OpenSCAD, CadQuery or gcode file (64 KiB by default, at most 1 MiB) |
get_asset_image |
An image file, up to 5 MiB |
Read & write adds eleven:
| Tool | What it does |
|---|---|
create_folder, rename_folder, move_folder |
Create, rename and move folders |
create_object, update_object, move_object |
Create objects, change their name, notes, source URL, author or license, and move them |
add_tag, remove_tag |
Tag or untag an object |
write_doc |
Replace the whole text of an existing markdown or text file |
add_file_from_path |
Copy a file from your computer into an object |
import_from_url |
Import a Thingiverse thing, MyMiniFactory object or GitHub, GitLab or Codeberg repository as a new object (https links only) |
There are no delete tools; nothing can be deleted through MCP. The write tools can still overwrite things: update_object replaces fields (an empty value clears one), write_doc replaces a document's content, and remove_tag untags. The assistant can't see or change the Hide from AI flag, can't touch hidden items, and anything it creates is visible to AI. Its changes show up in the open app right away.
Limitations
- The server only runs while BenchVault is open. Clients that can only launch a local stdio server (such as Claude Desktop's local config) can't connect yet.
- Hide from AI only controls what the MCP server returns. Library files are plain, unencrypted files, and the database next to them holds every name and note. Both live in BenchVault's data directory (
~/.local/share/dev.manzari.benchvaulton Linux). An assistant that can read your filesystem directly can still read hidden items. If yours can, deny it read access to that directory. In Claude Code that is a deny rule such asRead(~/.local/share/dev.manzari.benchvault/**)in~/.claude/settings.json. Such a rule covers Claude Code's file tools and the shell commands it recognizes, likecat, but not a script that opens files itself; for that, use Claude Code's sandbox. - With read & write access,
add_file_from_pathcan copy any file your user account can read, given its absolute path, into the library, where the assistant can then read it. The file must have a supported extension (models, gcode, OpenSCAD, CadQuery, markdown/text, CAD, common images), be at most 100 MiB, and lie outside BenchVault's data directory. - With read & write access,
import_from_urlmakes BenchVault download from the internet using the tokens and API keys saved in Settings. The credentials themselves are never returned to the assistant. It accepts only https links to Thingiverse, MyMiniFactory, GitHub, GitLab and Codeberg; other Git URLs (any.gitlink) can be imported from the app itself, not by the assistant. - If the assistant adds a tag whose name is used only on hidden items, BenchVault gives that tag a new id and the color the assistant asked for (or none), so it can't tell that hidden items use it. The hidden items keep the tag but lose its old color.
Stack
- Tauri 2 — Rust backend + system webview
- React 18 + TypeScript + Vite + Mantine 7 + TanStack Router + Zustand
- SQLite via
sqlxwith versioned migrations and FTS5 search - three.js via
@react-three/fiberfor STL/OpenSCAD previews - specta + tauri-specta — TypeScript bindings generated from the Rust command signatures, so the IPC contract can't drift
Install
Build from source (see below) and install the resulting bundle, or on Debian/Ubuntu let the Makefile do both:
make install-host # builds the .deb and installs it via apt
Prerequisites (building from source)
Install once on Linux:
# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Node (via your favourite manager — fnm shown here)
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 20
# Tauri system deps (Debian/Ubuntu)
sudo apt update
sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
Optional integrations: OpenSCAD for .scad previews, OrcaSlicer for slicer hand-off. Both are auto-detected; paths can be overridden in Settings.
Develop
npm install # or pnpm / bun
npm run tauri dev # Vite + Rust with hot reload on both sides
The first launch creates <app_data>/library/ and benchvault.db, and runs all migrations.
make help lists the other targets (check, clippy, test, bindings, …).
Build
npm run tauri build
Produces .deb / .rpm / .AppImage on Linux. Windows/macOS targets build but aren't tested or gated by CI yet.
Architecture
The Rust backend follows a strict commands → service → repository → db layering; the frontend talks to it through generated typed bindings.
src-tauri/src/commands/— thin Tauri command handlerssrc-tauri/src/mcp/— the embedded MCP server, a second front-end next tocommands/that may only callservice::ai, the layer that applies Hide from AIsrc-tauri/src/service/— business logic (file ingestion, imports, USB sync, external tools)src-tauri/src/repository/— all SQL, one module per table familysrc-tauri/src/parsers/— pure gcode/STL parserssrc-tauri/migrations/— versioned SQL, run automatically on startsrc/— React frontendsrc/lib/bindings.ts— generated by specta (make bindings) — do not hand-edit
The schema is intentionally polymorphic (assets, tags + entity_tags, entity_links, one FTS5 index keyed by entity kind), so future entity types — printers, filaments, print jobs, slicer profiles, costs — drop in without re-architecting. See CLAUDE.md for the full contributor guide.

