Modules

Modules are the extension system for Gumm. Each module adds one or more tools that the LLM can call automatically in response to your messages.

What is a module?

A module is a small package that lives in modules/user/ on your server. It contains:

• A manifest.json — metadata (name, description, capabilities)
• An index.ts — the tool definitions and handler logic
• (Optional) A ui.vue — a configuration panel shown in the dashboard

When a module is active, its tool definitions are included in every LLM request. If the LLM decides a tool is relevant to your message, it calls it—and the module’s handler executes the action.

Module lifecycle

Installed → Validated → Loaded → Active → (Disabled | Error | Removed)

Installing a module

From the dashboard (recommended)

1. Go to Modules (/modules)
2. Click + Install
3. Enter a GitHub repository — either owner/repo or the full URL
4. Optionally specify a branch or tag (default: main)
5. Click Preview to verify the manifest
6. Click Install

The module is downloaded, validated, and loaded automatically. No server restart needed.

From the CLI

gumm modules install owner/repo

# Install a specific version
gumm modules install owner/repo --ref=v2.0

Manually (drop-in)

Copy your module folder into modules/user/ on the server:

modules/user/
  my-tool/
    manifest.json
    index.ts

The Module Registry watches this directory and loads the module automatically within seconds.

Managing modules

Enable / Disable

Toggle the switch next to any module in the Modules page. A disabled module:

• Remains installed on disk
• Is excluded from all LLM tool calls
• Can be re-enabled at any time without reinstalling

Update a module

1. Go to Modules
2. Click the … menu next to the module
3. Click Update — Gumm pulls the latest version from the same source

Or via CLI:

gumm modules update owner/repo

Uninstall a module

1. Click … → Uninstall

Or via CLI:

gumm modules uninstall module-id

This removes the module files and deregisters it from the database.

Official modules

Gumm ships with a set of officially maintained modules. They are installed but disabled by default — you need to enable them manually.

Connecting a module that requires authentication

Some modules (Spotify, Gmail) need you to authorize access to a third-party account. When you enable one of these:

1. Go to Modules and enable the module
2. A Connect button or setup panel appears (the module’s ui.vue)
3. Click Connect and follow the OAuth flow in the popup
4. Your credentials are stored securely in the database — no env vars needed

Module schedules

Modules can define CRON schedules — for example, a daily news briefing or weekly summary. Scheduled tasks run automatically in the background.

You can view and manage scheduled tasks at Tasks (/tasks).

Status indicators

Click on a module with a red status to see the error details.

Building your own module

→ See Technical — Module Development for the full developer guide.