mojulo
CLAUDE.md4 starsChanged 33 days agoApache-2.0View on GitHub
Fast orientation for agents working in this repo. Rules and pointers only. If a line needs a paragraph of caveats it belongs in docs/ with a pointer here. Do not cite *.plan.md files from this file, code comments, docs, or the changelog: plans are working documents that move to lite-template/integration/plan-archive/ once merged, and the whole integration/ tree is gitignored. A local MCP server with a dashboard: a 3D factory with a media studio. The agent makes things to Play, Print,…
- Reads credentials
- Installs packages
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- figure-studySkill
- find-unused-locale-keysSkill
- head-studySkill
- hillclimbSkill
- historic-cultureSkill
- sketchSkill
- skull-studySkill
- sync-localesSkill
- view-svgSkill
- write-catalystSkill
The file
We split this CLAUDE.md into the rules it gives an agent
9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 11
Read, Hear and Observe by conversation, characters (create_character) first among them.
- Distinctive: line 38
Never hardcode an enumerable count in docs (kinds, packs, tools, locales, test files).
- Distinctive: line 56
Single operator, loopback only: No user identity by default.
- Distinctive: line 61
Suitability is the operator's: Do not add intent classification, use-case gating, or content-policy layers over what the operator's LLM …
- Very specific: line 63
Never read or echo .env secrets from generated app directories.
- Very specific: line 67
Do not commit unless asked.
- Very specific: line 99
No lint, formatter, or types.
- Very specific: line 102
Test tiers: while iterating, run the test folder next to the change.
- Distinctive: line 106
Test the concept, not the catalog.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Fast orientation for agents working in this repo. Rules and pointers only. If a line needs a paragraph of
caveats it belongs in docs/ with a pointer here. Do not cite *.plan.md files from this file, code
comments, docs, or the changelog: plans are working documents that move to
lite-template/integration/plan-archive/ once merged, and the whole integration/ tree is gitignored.
What this is
A local MCP server with a dashboard: a 3D factory with a media studio. The agent makes things to Play, Print,
Read, Hear and Observe by conversation, characters (create_character) first among them; each one is a tiny deterministic recipe (a sketches row) that
regenerates on every read and exports to Godot, Unity, Unreal, Blender, GLB, STL, 3MF, USD. Workflows (plans,
sweeps, stash and cook, catalysts) orchestrate the rest. Mojulo is the agent-driven upstream that feeds those
tools, never a fidelity rival and never "just an exporter." The canonical self-description is the
get_substrate drawer in control/lib/mcp/tools/context.js; keep
user-facing copy consistent with it. The office wing (apps, daemons, contextmap, MCP-to-MCP binding) left the
tool surface in 3.1.0: RETIRED_PACKS in packs.js, callable by name, never listed or routed to.
One package. control/ is the product (Next.js 16 on 3001, ESM, vitest); all work happens here. The chatbot factory and its bot runtime left in 3.0.0 for their own project; the unmaintained 2.x line still carries them.
Where truth lives
- Current state of the branch: the Unreleased section of control/CHANGELOG.md.
Releases before 3.0.0, and the detailed log behind 3.0.0, are in
control/CHANGELOG-2.x.md; the detailed log behind 3.1.1 is
control/CHANGELOG-3.1.md (archives; add nothing new to either).
docs/STATUS.mdis the maintainer's gitignored ledger; regenerate it from tree state, never trust it. - Version:
package.jsonsays 3.1.1, released 2026-10-16, the 3.1 line's first published release (mojulo3.1.0 reached npm from a stale build of 2026-10-10 and is deprecated, since npm will not unpublish a package others depend on; npm never reuses a version, so the release is 3.1.1, and code and docs that say 3.1.0 mean this release; 3.0.0 was released 2026-10-01; 3.0.1 was prepared and never released, and its work ships in 3.1.0; 2.1.0 was released 2026-09-23; 2.2 was prepared and never released, and its work ships in 3.0.0; the plugin,glama.jsonandserver.jsonpin the same version, checked bycontrol/scripts/check-plugin-version.mjs;mojulo orientis the shell'sinitializesince 2.1.0; the exported World page is self-contained by default again since 3.0.0 (2.0.9 through 2.1 loaded three.js from the pinned CDN) —cdn: truefor the CDN build an artifact host needs; 2.0.5 is broken on fresh installs, seeCHANGELOG-2.x.md; the embedding runtime is the opt-inrecallgroup since 2.0.7; the chatbot factory left in 3.0.0). Unreleased is empty at the tag; new work goes under it as###themes. - Deep maps: docs/AGENT-REFERENCE.md (rings and packs, workflows, substrate, data), docs/MCP-ARCHITECTURE.md (transport, sessions, deliberation), docs/install-capabilities.md (kernel + packs + install groups), CONTRIBUTING.md (recipe book vs core), AGENTS.md (non-Claude hosts).
- What games can be made, and what to build next: docs/tool-surface/hillclimb.md
(generated from the cosmos registry and sweep; internal, not an MCP surface). Read it before picking game work;
after changing the registry,
npm run tool-surface(a critical test fails on a stale page). Skill:/hillclimb. - Never hardcode an enumerable count in docs (kinds, packs, tools, locales, test files). Point at the list that defines it; counts drift the day after they are written.
- "graph" means three things:
control/lib/graph/is the geometry library; the contextmap is themeta_*tables in the same SQLite file;/graphis a static pipeline SVG.
Golden rules
- Recipes, not renders. The manifest is the artifact; kernels regenerate on every read, so a kernel's
output for given params is a compatibility promise over already-minted rows. Byte-identical re-render is
the baseline test for any kernel change. Seeded dice only (
mulberry32); neverMath.random,Date,Intlin a builder. An absent opt-in channel must contribute zero bytes. - Two gates, never conflated. Machine gate (measured, automated) and eyes gate (a human looks). Never claim the eyes gate passed. All gates advise and stamp; none refuse. Say which gate ran and what was seen. docs/bicycles.md, docs/responsibility-model.md.
- Recipes are starters. Iterate in place with
update_sketch/edit_solid; don't re-mint. - Core is capability, the book is repertoire. A new study-object kind is normally a recipe-book Door-2
builder in control/book/, not a core addition. The book ships bundled (3.1.0); the
separate
mojulo-recipe-bookrepo andMOJULO_RECIPE_BOOKare deprecated (they cannot load in an agent box). - Single operator, loopback only. No user identity by default; the roles pack is operator-owned delegation, not multi-tenancy. Do not add tenant isolation, tunnels, or public exposure. The MCP route is bearer-gated and 404s without a key; that is the whole auth surface, by design.
- The dashboard is not a conversational surface. The operator drives from their host agent. Do not add chat surfaces to the dashboard.
- Suitability is the operator's. Do not add intent classification, use-case gating, or content-policy layers over what the operator's LLM provider already enforces. Posture: TERMS.md.
- Never read or echo
.envsecrets from generated app directories. - UI strings go through
next-intl; add tocontrol/messages/en.json, then/sync-locales. CI checks parity. - Optional workers (Blender, ComfyUI, Kokoro, slicer, OpenSCAD, Godot, Unity, Unreal) are never dependencies.
Absence degrades a loop, never breaks one. Search orders live in
control/lib/workers/find.js(version({ workers: true })). - Do not commit unless asked. Never touch
control/.next/,control/data/,.claude/worktrees/.
MCP tool surface (the tests that bite)
tools/list cannot be drawerized, so it is budgeted. The per-description ceiling and the flat payload pin
live in tool-descriptions.test.js; the packs payload pin lives in packs.test.js. If a legitimate
addition crosses a pin, re-pin it in the same commit with a comment saying why. A door is an intent the user voices:
a new capability is first an argument on the door that owns its intent, a routing card and a vocab drawer. A new listed
tool needs a phrasing no listed door owns, as a routing-eval.fixture.js row (a create / compose tool without one
fails routing-cards.test.js), and gate 2b showing the fold would route worse. New tool checklist: register in ring order in
server.js; exactly one pack home in packs.js; one line and a verb in tool-lines.js (the tool index, the form
bodies and the pack menus are generated from it), plus its form's tools in context.js if creative; a routing card (ceiling in routing-cards/loader.js) plus a routing-eval.fixture.js row if creative; the
RING10_TOOLS list in context.test.js; its row in tool-annotations.js. An unlisted tool is unreachable from the agent (CLI and plan steps only), so a fold rewrites every pointer to the old name. forward_context is a routing index, not a glossary; its bodies
have their own byte ceilings. Full map: docs/AGENT-REFERENCE.md.
Commands
cd control
cp .env.example .env # first time
npm install
npm run dev # must stay --webpack; Turbopack melts down watching control/data/
npm run build # --webpack too: Turbopack ignores next.config's webpack rules and fails on an absent pack or recall runtime
npx vitest run # the whole suite; *.spike.gen.test.js are excluded and gitignored
npm run test:critical # the contracts only (MCP surface, pins, guards, db, scripts), no geometry-heavy suites
npm run test:deep:changed # the *.deep.test.js sweeps whose imports touch an uncommitted change (none if none do)
npm run test:e2e # whole worlds through the real handlers, games whose audit walks each level in headless Chrome
node scripts/mcp-stdio.mjs orient|tools|packs|help <tool>|call <tool> --json '{…}' # CLI over the registry; orient = initialize for a shell
node scripts/reindex-embeddings.js # text-only without the recall group; vectors with it
node scripts/mcp-stdio.mjs install recall # the embedding runtime, opt-in, lands in ~/.mojulo/recallNo lint, formatter, or types. CI runs node --check and the locale validator. Always run from control/:
entry points chdir there and getServerVersion reads package.json from cwd. macOS has no timeout.
Test tiers: while iterating, run the test folder next to the change; before a commit, test:critical, that
folder and test:deep:changed, plus test:e2e when the change touches the gameworld, city, game or structure
kernels; the whole suite once before merging into the release candidate (CI runs it and test:deep).
Test the concept, not the catalog. Species, presets, cultures, landmarks and climates are inputs to procedures:
a test picks one case per distinct procedure (a rig topology, a family, a code path), chosen in code from the
catalog rather than a hand list, and asserts the concept (rig, motion, chirality, growth, determinism, absence
adds nothing) on it. No test iterates a whole catalog, in any tier; a new entry is covered by the procedure it
runs through. Build the smallest input that still exercises the concept (a small board, a short run, one city).
An exhaustive sweep over a word's range ends goes in a *.deep.test.js beside the law
tests, importing only the modules it sweeps, so --changed can select it. A suite that makes whole worlds or
mints with autoAudit: true goes on the E2E list in vitest.e2e.config.js, never in critical (guarded by
lib/mcp/test-tiers.test.js); test the audit gate itself with a stub runTraversal.
Byte-pin conventions: *.char.test.js and *.trace.test.js are characterization pins; __snapshots__/
hashes are structural on purpose. A pin change is legitimate only when the step says emission changes.
Plans and changelog
Design happens in *.plan.md under lite-template/integration/<MMDD>/ (gitignored). Skeleton: status
line, "what exists (reuse, don't design)", numbered phases, Gates split machine/eyes, out of scope, open
questions, a Log appended as built. Write the plan and its Unreleased ### section (one per theme, named
for the plan) before the code. A leftover "remaining" section is a recorded stopping point, not a backlog.
On merge the plan moves to plan-archive/. Nothing tracked may cite a plan path.
Release
Control plane: add ## [X.Y.Z] - YYYY-MM-DD to the changelog, run npm run smoke:tarball (packs, installs
the tarball into an empty temp dir, boots the dashboard; the npx cache reuses old trees and hides
fresh-install breakage), commit, tag vX.Y.Z, push the tag; the workflow slices that section.
Data and native landmines
- Two path resolvers. Bins use
~/.mojuloviascripts/mojulo-paths.mjs;next devusescontrol/.env(SQLITE_PATH=./data/…). Repo-dev exportsMOJULO_DATA_DIR="$(pwd)/data" MOJULO_OUTCOMES_DIR="$(pwd)/data/outcomes"before any script. Quote them.middleware.jsruns on the Node runtime (since 3.0.0) solib/auth/delegate-session.jscan check a delegate's session; it carries its own copy of theSQLITE_PATHfallback, pinned by its test. - Schema and migrations are hand-written, idempotent, and ordered in
control/lib/db/index.js. No version ledger.getDb()has side effects (backfill, daemons). better-sqlite3compiles per arch; new native server deps go innext.config.mjsserverExternalPackages. Nopostinstallmodel download. The embedding runtime is not a dependency at all:mojulo install recallinstalls it under~/.mojulo/recall/and runsfetch-embed-model.js;semantic_searchis FTS5-lexical without it. Never add@huggingface/transformersoronnxruntime-nodeback todependencies.
Architecture map
Pointers only; each target carries its own design notes.
- MCP: server.js, tools/, packs.js.
Claude plugin profile (
MOJULO_DISTRIBUTION=claude-plugin): plugin-profile.js and plugin-profile-cards.js hide the AI-generator handoffs, the keyed prompt door, automatic downloads and CDN pages; npm and source builds must stay byte-identical. - Recipe dispatch: sketch-manifest.js (render mode + bucket), world-scene.js (world resolution and opt-in channels), world-kinds.js (the registry).
- Emitters: control/lib/graph/scene/; native frame is z-up, 1 unit = 1 m
(engine-score.js); each emitter owns its conversion.
Engine legs:
godot-project.js,unity-project.js,unreal-project.js,blender-project.js; CLIs incontrol/scripts/export-*.mjs; gates are advisory and needMOJULO_GODOT/MOJULO_UNITY/MOJULO_UNREAL. - Solids: polygonizer/ (
field-terms.js,code-realm.js,field-exact.jsforexact: truethrough Manifold), worlds/workbench.js; manuals are thesolid-vocab/cards. OpenSCAD both ways: scad/scad-render.js (thescadkind, OpenSCAD-in-WASM) and scene/scene-scad.js (the transpiler). - Recipe book: views/recipe-book/. Vocab cards:
*-vocab/dirs. - Retail: retail/ (concept cards → the
store/mallkinds; a new store is a card, not code). - Historic cultures: historic/ (a real place at its period → the
historickind and its encyclopedia entry); adding or deepening one: docs/historic/README.md,/historic-culture. - Room furniture: furnishings/roster.js names every piece (one row, the words people say, its handles into the floorplan, preset, net and room-asset tables); a new piece is a row first.
- Flight parts: craft-shelf/ (the ODM inventory of aircraft and spacecraft parts → whole craft by archetype; a new part is a row first); the flight-game map is docs/flight-games.md.
- Vegetation: vegetation/ (grown trees, palms, bamboo; pooled like
rock-pool.js); read docs/vegetation.md before changing a preset or a level of detail. - Beats graph/beats/, voice graph/voice/, image outcomes graph/image-outcomes/, edifice architecture/edifice.js.
- Rendering docs: docs/scene-css3d-lighting.md, docs/raymarch-effects-layer.md, docs/local-blender-worker.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

