Ada Matrix Bot

The official Matrix bot of Code Society, built with Code-Society-Lab/matrixpy.

Quick Start

1. Create a virtualenv and install dependencies:

 python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Create a .env file at the root of the project with your credentials:

# Username + password
ADA_USERNAME=@yourbot:matrix.org
ADA_PASSWORD=your_password
# Or username + token
ADA_USERNAME=@yourbot:matrix.org
ADA_TOKEN=your_token

3. Run the bot:

 ada start

By default it runs in development mode. To use a different environment:

 ada start --env production

Or point directly at a config file:

 ada start --config /path/to/config.yaml

If startup loops warnings like 'next_batch' is a required property, your token is likely invalid or expired. Regenerate ADA_TOKEN or switch to ADA_PASSWORD auth in your .env.

Configuration

Config files live in config/ and are selected by environment:

config/
production.yaml
development.yaml
staging.yaml

Static values like HOMESERVER and PREFIX go in the YAML file. Secrets are never committed — they live in a .env file and are referenced as environment variable placeholders:

HOMESERVER: "https://matrix.org"USERNAME: ${ADA_USERNAME}PASSWORD: ${ADA_PASSWORD}PREFIX: "!"LOG_LEVEL: "INFO"

Extensions

Extensions are self-contained modules that add commands and event handlers to the bot. Each extension must define an extension attribute at the module level:

frommatriximportExtension, Contextextension=Extension("ping")
@extension.command()asyncdefping(ctx: Context) ->None:
awaitctx.reply("Pong!")

Drop the file under bot/extensions/ and it will be auto-discovered and loaded on startup — no registration needed.

Rules

• The file must define an extension attribute, or the bot will raise a RuntimeError on startup.
• The extension name passed to Extension() should match the module's purpose.
• Each extension should stay focused on a single feature.