agentleFS
zombicozombico/mojulo/CLAUDE.md

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

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
  1. Very specific:

    Read, Hear and Observe by conversation, characters (create_character) first among them.

    line 11
  2. Distinctive:

    Never hardcode an enumerable count in docs (kinds, packs, tools, locales, test files).

    line 38
  3. Distinctive:

    Single operator, loopback only: No user identity by default.

    line 56
  4. Distinctive:

    Suitability is the operator's: Do not add intent classification, use-case gating, or content-policy layers over what the operator's LLM …

    line 61
  5. Very specific:

    Never read or echo .env secrets from generated app directories.

    line 63
  6. Very specific:

    Do not commit unless asked.

    line 67
  7. Very specific:

    No lint, formatter, or types.

    line 99
  8. Very specific:

    Test tiers: while iterating, run the test folder next to the change.

    line 102
  9. Distinctive:

    Test the concept, not the catalog.

    line 106

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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.md is the maintainer's gitignored ledger; regenerate it from tree state, never trust it.
  • Version: package.json says 3.1.1, released 2026-10-16, the 3.1 line's first published release (mojulo 3.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.json and server.json pin the same version, checked by control/scripts/check-plugin-version.mjs; mojulo orient is the shell's initialize since 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: true for the CDN build an artifact host needs; 2.0.5 is broken on fresh installs, see CHANGELOG-2.x.md; the embedding runtime is the opt-in recall group 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 the meta_* tables in the same SQLite file; /graph is 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); never Math.random, Date, Intl in 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-book repo and MOJULO_RECIPE_BOOK are 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 .env secrets from generated app directories.
  • UI strings go through next-intl; add to control/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/recall

No 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 ~/.mojulo via scripts/mojulo-paths.mjs; next dev uses control/.env (SQLITE_PATH=./data/…). Repo-dev exports MOJULO_DATA_DIR="$(pwd)/data" MOJULO_OUTCOMES_DIR="$(pwd)/data/outcomes" before any script. Quote them. middleware.js runs on the Node runtime (since 3.0.0) so lib/auth/delegate-session.js can check a delegate's session; it carries its own copy of the SQLITE_PATH fallback, 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-sqlite3 compiles per arch; new native server deps go in next.config.mjs serverExternalPackages. No postinstall model download. The embedding runtime is not a dependency at all: mojulo install recall installs it under ~/.mojulo/recall/ and runs fetch-embed-model.js; semantic_search is FTS5-lexical without it. Never add @huggingface/transformers or onnxruntime-node back to dependencies.

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 in control/scripts/export-*.mjs; gates are advisory and need MOJULO_GODOT / MOJULO_UNITY / MOJULO_UNREAL.
  • Solids: polygonizer/ (field-terms.js, code-realm.js, field-exact.js for exact: true through Manifold), worlds/workbench.js; manuals are the solid-vocab/ cards. OpenSCAD both ways: scad/scad-render.js (the scad kind, 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 / mall kinds; a new store is a card, not code).
  • Historic cultures: historic/ (a real place at its period → the historic kind 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.