ES Install

Add your own features to MADRE.

A module adds something to MADRE, like a new command, a tool for your agents or an integration. It all fits in a single file. You can ask an agent for it with /module or write it yourself. You don’t compile anything, it installs no packages and it doesn’t ask you to sign up.

Read the technical guide

Based on docs/SDK.md · MADRE 1.1.3

In short

  • A module adds something to MADRE: a command, a tool for your agents or an integration. It is one file.
  • You do not have to write it: type /module and what you want, and an agent writes it.
  • Nothing installs on its own. MADRE shows you what it does and what it touches, and you decide.
  • If the module has a mistake, MADRE tells you instead of installing it halfway.

Let an agent write it

Ask an agent with /module.

Type /module and what you want it to do. MADRE hands the agent the guide and the example, and it writes the module. Your part is reviewing it and installing it.

MADRE 1.1, a new chat with the message “#2 /module a /todos command that lists the TODO comments in the project files, with file and line. @opencode”. #2, /module and @opencode show marked, and the mode says #2 Create.
The request, in the text box. #2 is the Create permission, /module is the request and @opencode, who makes it.

  1. You ask

    Type /module and what you need, like “a /todos command that lists the project’s TODOs”.

  2. You give permission

    It needs the #2 Create permission. If it’s off, MADRE asks you for it and keeps your request. Typing the command never turns it on for you.

  3. The agent writes it

    Just one file, <id>.module.mjs, in its draft folder. It never installs it on its own.

  4. You install it

    MADRE puts a card in the conversation with INSTALL FOR EVERY PROJECT or INSTALL FOR THIS PROJECT. You look it over, pick with one click and turn it on in Modules.

MADRE 1.1, below OpenCode’s answer, which created todos.module.mjs in its drafts folder, the card “Module · @opencode · Wrote todos.module.mjs” with “Install for every project” and “Install for this project”, and the note “Read it first: a module runs inside MADRE with your permissions”.
The card to install it. The agent wrote the module. You decide where it goes, or whether it goes in at all.

What it can do

What your module can do.

You declare each one in the module’s file, and MADRE wires it into your projects.

  • Commands in the project. Make your own / commands. They answer with a card that you and your agents read.

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

  • Settings without designing anything. Declare selects, switches and fields. MADRE draws them on the card and keeps what you pick.

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

  • Listen to the project. It gets every message and every turn in the project, and it can react to them.

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

  • Diagnostics. Teach Diagnostics to spot new problems and how to fix them on each system.

  • Share it in the Market. Send it to the community Market. I read it, sign it and it shows up in everyone’s Market. Whoever installs it first sees what it declares: where it connects, which keys it asks for and what it adds.

Common mistakes

MADRE warns you before something breaks.

If you or an agent get something wrong in a module, MADRE tells you instead of installing it half-broken.

  • A misspelled field. Write sumary instead of summary and MADRE tells you which field it doesn’t know. It won’t install it with an empty card.

  • An import that won’t work. Modules don’t use imports. MADRE hands yours what it needs. If you copy the import from a built-in module, the error tells you what to do instead.

  • Removing it is one click. Every module of yours has UNINSTALL on its own card. It deletes the file and takes it out of the project, no restart needed.

If you’d rather write it yourself

Write your first module.

  1. Copy the file

    Put it in ~/.pulse/modules/ to have it in all your projects, or in .madre/modules/ inside a project so it only works there.

  2. Reload

    In Modules, open “Create your module” and hit Reload modules. If something fails, it shows you the exact file and line right there.

  3. Use it

    Flip its switch and type /your-command. Changed the file? Reload and you’re done. No need to restart the project.

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. It has a switch, a setting and the /hello command. No import, because MADRE hands it everything it needs. See hello-module.mjs

The card

MADRE builds your module’s card.

Every card in Modules has the same five parts, always in the same order. So your module’s card reads just like the ones that come with MADRE.

  1. Who it is

    Its name, whether it’s on or off, who made it, the version and the button to look for a newer one.

  2. What it does

    One sentence.

  3. What it touches

    What it writes and what it needs to work.

  4. Settings

    Your selects, switches and fields.

  5. The switch

    Install, turn on or off. It’s always at the bottom. Your own modules also have UNINSTALL.

MADRE 1.1, my-shop’s Modules: cards for Notes and Reminders switched on, Continuity not installed, Images, Git, Token saver, Preview, Test browser, GitHub and “Make your module”, each with its switch.
Modules, in your project. Each card has its switch; open it to see its five-part sheet. “Make your module” takes you to write your own.

Since 1.1

One file, the sdk: 2 contract and the Market.

A module says which SDK contract it is written for. With sdk: 2 it is a single file that imports nothing from MADRE, and you can share it with everyone in the Market.

  • What MADRE gives you. ctx.t gives you your words in the project’s language, ctx.services.ollama.generate the local AI, and your routes get their own settings.

  • It’s read before it’s installed. In the Market, people see what your module declares before installing it, and the same file they read is the one installed.

  • Signed for everyone. You send it to the community Market; once I’ve read it, I sign it and it reaches every copy of MADRE that asks for it.

MADRE 1.1, my-shop’s Market with the “Before you push” card: free, off in this project, “Without the terminal” shelf, version 1.0.1, its preview and “What it does”.
A module’s card in the Market. Price, shelf, version, its preview and what it does: what people read before getting it.

House rules

How a good module behaves.

  • It doesn’t connect without telling you. 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 computer. It keeps no keys.

  • It doesn’t write to the project. That’s what the agents’ permissions are for. If it installs something, it shows you the command before running it.

  • If it fails, it doesn’t break the turn. The error shows up on the module’s card and the project keeps going.

  • It talks like MADRE. Short, clear words, in the person’s language: with sdk: 2, ctx.t gives you your words in the project’s language.

  • It uninstalls from its card. Your own modules uninstall. The ones that come with MADRE only switch off.

Your say

What’s missing for your module?

If the SDK doesn’t let you do something you need, like a field, an event or a tool for the agents, tell me. It doesn’t ask for an account and it gives you a private link where you see the reply.

Suggest an SDK improvement

Heads up

A module runs with your permissions.

MADRE checks that it loads properly and stays inside its own space. What its code actually does, only you can check. Only install modules you’ve read, or ones from someone you trust.

Its addresses live under /api/x/<id>/.
If one tries to use another, it doesn’t load. None can pass itself off as MADRE.
It doesn’t take someone else’s name.
Not a built-in module’s, and not one that’s already installed.
It doesn’t make up messages.
It can’t invent turns or messages from the agents.
It gets no credentials.
Like MADRE, it uses the computer’s sessions.

Open MADRE in your project.

npx @jossuealcala/madre

Back to MADRE