Installing a Mod

A Mod is a single .oomu file that adds material to OOMU. It can carry three kinds of thing, and nothing else:

• Knowledge: text, Markdown, or JSON reference files the assistant can read.
• Saved data: a few named values the Mod keeps between sessions, for one project or everywhere.
• Short instructions: a paragraph of guidance, such as a house style or a review procedure.

A Mod never carries code, and nothing in it runs. 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.

If your organization manages this Mac, its policy can limit which Mods may be installed, or refuse unsigned ones.

---

Step 2: Read the card

Each installed Mod shows two things: whether it is ready to use, and who stands behind it.

Readiness is the status pill at the top of the card:

Trust is shown under the byline, as long as the files still verify:

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

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. Details lists everything the Mod declares, in plain language. Anything it declares that OOMU does not implement is listed too, marked Not supported in this Beta 2 build (the app's label for any feature from the older formats).

---

Step 3: Know which kind it is

A Mod works in one of two ways, and the card tells you which.

Ambient Mods: guidance that is always on

An ambient Mod is marked Always Active: "Applies automatically when selected for an agent." It carries only short instructions, at most 600 characters, and no files or tasks. A house writing style is the typical example. Once you select it for an agent, every chat with that agent follows it without you asking.

Tagged Mods: tasks you call by name

A tagged Mod does nothing until you mention it with @ in the composer: "Type @ in chat to use a Mod, or add one to any agent." It can offer named tasks under its tag. A supplier review Mod, for example, might offer @audit.guide to read its checklist, @audit.save to save audit notes, and @audit.notes to read them back.

Notes a tagged Mod saves are usually kept per project, so notes from one client never appear in another client's project.

---

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 or select specific ones. All enabled Mods makes every enabled Mod's @ tags available to that agent; it does not switch on every ambient Mod's guidance. Select an ambient Mod individually if that agent should always follow it.

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

---

Step 5: Tidy up the tags

Two installed Mods can want the same short tag. Tag settings on the card handles that:

• Short alias: "Use 1 to 8 letters or numbers. System tags are reserved." Names such as @mail, @calendar, and @search belong to OOMU and cannot be taken.
• Default for: "Choose which Mod a shared short tag opens. A project choice takes priority." Set a default for all projects, or for one project in particular.

Every Mod also keeps a full tag that includes its publisher, such as @oomu:audit, which always reaches that exact Mod.

---

Step 6: Remove it

Remove takes the Mod out of OOMU and deletes its installed files.

---

What a Mod cannot do

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

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. Files must sit under knowledge/ or content/ and end in .txt, .md, or .json. Saved data is limited to the keys the Mod declared, and read and write must declare the same keys, so a Mod cannot quietly write to something it never showed you it could read. A task can use only the actions the Mod declared up front.

---

Where to go next

• Building a Mod: the developer's guide to packaging an .oomu file.
• Mod package specification: the exact archive format, manifest, and limits.
• Privacy & security: where Mods sit in the overall model.