ES Install

A module is one file.

A module is a new feature for MADRE, written in a single file. Nothing to compile, no packages to install, nothing to sign up for: you write an .mjs —or ask your AI to—, copy it to a folder, and it shows up in MADRE with its switch.

Read the technical guide

Based on docs/SDK.md · MADRE 0.4.1

Get started

From zero to your command, in three steps.

  1. Copy the file

    To ~/.pulse/modules/ for every room, or to .madre/modules/ inside a project for that project only.

  2. Reload

    In the room, MODULES → RELOAD MODULES. If something fails, the card names the file and the exact line.

  3. Use it

    Switch it on and type /your-command. Change the file, reload, done: no need to restart the room.

hello.mjs
export default {
  id: 'hello',            // kebab-case
  name: 'HELLO',
  summary: 'What it does, in one sentence.',
  settings: { enabled: false, greeting: 'hola' },
  async status(ctx) {
    return { status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? 'on' : 'off' } };
  },
  slash: [{
    name: 'hello',
    usage: '/hello [name]',
    summary: 'Says hello.',
    async execute(ctx, args) {
      return { ok: true, title: 'HELLO', text: `${ctx.settings.greeting}, ${args[0] ?? 'crew'}` };
    },
  }],
};
A complete module. A switch, one setting and the /hello command. The full example, commented, is in the repository. See hello-module.mjs

Capabilities

What a module can do.

You declare what you need and MADRE takes care of the rest.

  • Commands in the room. Your / commands run on the server and answer as a card that you and the agents read.

  • Tools for the agents. Give an agent extra tools (MCP servers) for its turn only, isolated from the rest, and MADRE tells it what it got.

  • Settings, no drawing. Declare selects, switches and fields: MADRE draws them on the card and saves them in your config.

  • Your own addresses. Your module can answer on its own web addresses (HTTP routes), always under /api/x/your-module/.

  • Listen to the room. It hears everything that happens in the room —every message, every turn— and can react.

  • Versions kept current. If your module uses an outside program, MADRE watches its version and shows you the update command before running it.

  • Diagnostics. Teach MU/TH/UR to recognise new problems and how to fix them on each system.

  • Share it. Publish your file: whoever uses it gets GET A NEWER FILE, and MADRE verifies the new copy before replacing the installed one.

The card

You declare; MADRE builds the card.

Every card in MODULES has the same five parts, in the same order. That is why your module’s card reads just like the ones that ship with MADRE.

  1. Who it is

    Name, ON or OFF, author, version and the button to look for a newer one.

  2. What it does

    One sentence. Not three.

  3. What it touches

    What it writes and what it needs, folded, with its count beside it.

  4. Settings

    Your selects, switches and fields.

  5. The switch

    Install, enable or disable. Alone, and always at the bottom.

With your AI

Let the room build its own module.

With the #2 CREATE permission or higher, ask an agent for the module you need. It writes it; you decide whether it gets installed.

  1. You ask

    “Create a module that gets my emails ready to review.” The agent already knows where the guide and the example are.

  2. It writes

    A single file, <id>.module.mjs, in its draft folder. Never in your module folders.

  3. You review

    MADRE recognises it and puts a card in the room: INSTALL FOR EVERY ROOM or INSTALL FOR THIS PROJECT.

  4. You install

    One click. MADRE validates it in a separate copy and it appears in MODULES tagged DEV.

House rules

What makes a good module.

  • Nothing leaves on its own. If your module talks to a service, its card says so, and it only does it when the person asks.

  • No credentials. It uses the sessions already on the machine; it keeps no keys.

  • It does not write the project. That is what the agents’ modes are for. If it installs something, it shows the command before running it.

  • It fails softly. An error never breaks an agent’s turn: the card says so and the room carries on.

  • It talks like MADRE. Short uppercase labels and notes that say what does not leave the machine.

  • It comes out just as easily. A module of yours is removed from its card and its file is deleted. The ones that ship with MADRE are switched off.

Plainly

A module runs with your permissions.

MADRE checks that it loads and stays inside its pen. What the code intends, only you can check: install only what you have read.

Its routes live under /api/x/<id>/.
One that tries another path does not load: none can impersonate a MADRE route.
It cannot take another id.
Not a built-in module’s, not one already loaded.
It cannot forge turns or messages.
The log rejects the reserved event types.
It receives no credentials.
Like MADRE, it uses the machine’s sessions.

Try it on a project you already know.

npx @jossuealcala/madre start

Back to MADRE