OOMU
← All documentation

Tutorials

Installing a Mod

Install and manage extensions from files you choose.

A Mod is a single .oomu file that adds material to OOMU. In Beta 2 that means two specific things, and nothing else: knowledge content the assistant can read, and saved data the Mod can keep between sessions.

That is a deliberate narrowing. Read What a Mod cannot do before you assume otherwise.

Step 1: Install

Go to Mods and choose Install Mod. The macOS file picker opens, filtered to .oomu files. Anything else is declined rather than guessed at.

Browse marketplace opens oomu.io in your browser. It is blocked while Air-Gap Mode is on, like every other outbound action.

Before installing, OOMU checks the archive: it must be a well-formed ZIP with manifest.json at the root, at most 256 entries, and at most 200 MB uncompressed. It hashes the payload, checks any signature, and stages the extraction so a failed install leaves nothing behind.

Step 2: Read the badge

Each installed Mod shows one status pill. Two different questions are being answered, and OOMU keeps them apart.

If the package files verify, the pill shows its trust state:

BadgeWhat it asserts
OOMU reviewedThe package carries a valid review signature from OOMU's own key. OOMU has looked at it.
Verified publisherThe package carries a valid publisher signature. This tells you who built it: not that it is safe.
UnsignedNo signature at all. The card adds: "Local package without a signature. OOMU verifies its files before use."

If the files no longer match what was installed, the pill shows an integrity problem instead, and the Mod cannot be enabled:

BadgeMeaning
ChangedThe files on disk no longer match the recorded package digest.
MissingThe installed files are gone.

A signature proves provenance, not safety. Verified publisher means the publisher's key signed this exact payload. It says nothing about whether the contents are good for you. Install Mods from people you would trust with the same material in any other form.

Verify re-checks a Mod's files against its recorded digest at any time.

Step 3: See what it declares

Expand {count} features on the card. Each declared capability is listed in plain language with its current state:

FeatureCapability
Knowledge contentmods.asset.read: text, markdown, or JSON files under the Mod's knowledge/ or content/ folder.
Saved Mod datamods.state.read: read the specific keys it declared.
Update saved Mod datamods.state.replace: write those same keys.

State is either Active or Available when enabled. Anything the Mod declares that Beta 2 does not implement is listed too, marked Not supported in this Beta 2 build.

Step 4: Enable it, then give an agent access

Enabling is one toggle on the card. But enabling alone does not change any conversation. A Mod affects work only when an agent is allowed to use it.

Open Chat → Agents, edit an agent, and under Mods either choose All enabled Mods ("Newly enabled Mods are available to this agent automatically") or select specific ones.

Mods run only on this Mac. An agent pinned to Cloud cannot use Mods. Choose Automatic or On this Mac if the agent needs them.

Step 5: Remove it

Remove takes the Mod out immediately and shows an Undo for ten seconds. After that the files are gone.

What a Mod cannot do

If you used Beta 1, or you are porting a package, this is the part that changed. A Beta 2 Mod supplies content. It does not execute.

Not supported
JavaScript entry pointNo Mod code runs.
Prompt customizationA Mod cannot inject a system prompt or rewrite instructions.
Background tasks and hooksNo hook registry, no interception of your turns.
Slash commands and automatic triggersNo semantic triggers.
Network accessA Mod cannot reach a host, declared or otherwise.
Beta 1 capability bundlesThe older bundle format is not executed.

A Beta 1 package still installs, and OOMU lists exactly which of its features it will not honor rather than failing silently or pretending.

The declared surface is also tightly bounded: at most three capabilities, at most 64 declared assets or keys each. Assets must sit under knowledge/ or content/ and end in .txt, .md, or .json. Read and write must declare identical key sets, so a Mod cannot quietly write to something it never showed you it could read.

Where to go next