aiolabs/maubot-plugins
9
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
12 commits 1 branch 0 tags 176 KiB
  • Python 100%
Find a file
Exact
Padreug b1c37161dd docs(spec): sync identity-model section with shipped nsecbunkerd state 
aiolabs/lnbits #9 + #18 are no longer in-flight; aiolabs/nsecbunkerd
deploys live from dev with sign-time TTL+revoke (#27), windowed
usage caps (#34), hard-reject on lapsed binding (#38), and a full
NDK -> nostr-tools transport port (#43/#45/#47). §7.2 now mandates
sign-time lifecycle enforcement; §7.3 lists expiresAt + usage caps
as part of the binding artifact; §12 swaps the upstream link for
the aiolabs fork and adds the never-full-wipe nsecbunker.db
operational hazard.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-28 00:42:47 +02:00
docs docs(spec): sync identity-model section with shipped nsecbunkerd state 2026-06-28 00:42:47 +02:00
journal docs: add umbrella + journal READMEs 2026-05-24 09:55:24 +02:00
tracker feat(tracker): Phase 1 plugin — Matrix + SQLite, rules-only 2026-05-24 15:48:21 +02:00
wiki feat(wiki): docs-lookup plugin against Quartz contentIndex 2026-05-24 16:40:11 +02:00
.gitignore feat(journal): farm-journal maubot plugin 2026-05-20 23:47:10 +02:00
CLAUDE.md docs: add community-organizer protocol spec 2026-05-24 15:12:37 +02:00
README.md feat(wiki): docs-lookup plugin against Quartz contentIndex 2026-05-24 16:40:11 +02:00

README.md

maubot-plugins

Umbrella for maubot plugins used by the aiolabs / Château du Faune Matrix stack. The maubot daemon itself is provisioned via server-deploy/modules/services/maubot.nix on the castle hosts; the actual plugin code lives here.

Plugins

Plugin Purpose
journal/ Farm-journal bot. !journal <text> records what you did, scoped per-user/room/timestamp. !journal show [@user] and !journal today query back.
tracker/ Community-organizer bot. !add / !task / !sidequest / !remind / !done / !list / !setup. Implements the Community Organizer spec — per-room shortcuts, 5-level priority, rules-based inbox classifier.
wiki/ Docs-lookup bot. !ask <query> / !doc <slug-or-title> / !wiki [refresh|status]. Points at any Quartz-rendered docs site (default: docs.ariege.io), full-text searches the corpus, replies with snippets + links. Internal-network deployment posture — works during WAN outages.

Community Organizer protocol

docs/community-organizer-spec.md defines the protocol the plugins in this repo (and companion renderers like inky-impression) use to coordinate community life — tasks, journals, reminders, shopping lists — over Matrix capture + Nostr storage. Designed to be adopted by other communities; reuses NIP-52 + NIP-72 instead of inventing new event kinds. Read it before changing verb behavior or event shapes in any plugin.

Building a plugin

A .mbp is just a zip containing maubot.yaml + the plugin's Python modules at the root. No special tooling needed:

cd <plugin>/
zip -j ../<plugin>.mbp maubot.yaml *.py

(-j strips the directory prefix so files land at the zip root.)

Uploading / iterating

  1. Open the maubot UI (e.g. https://maubot.<domain>/_matrix/maubot/).
  2. Plugins → + (first time) or click the existing plugin → upload the new .mbp. Maubot keys plugins by id; uploading a new version of the same id replaces the old one.
  3. Hit Save on the affected instance after upload — toggling Enabled without Save will revert. Easy facepalm.

Bump version: in maubot.yaml for every meaningful change so the maubot UI surfaces it cleanly and old .mbp files in /var/lib/maubot/plugins/ aren't ambiguous.

Bot account convention

Each plugin attaches to a Matrix client (a regular Matrix user account controlled by maubot). For the journal bot: @journalbot:ariege.io. Bot accounts are created the same way as any user — issue a registration token from the Continuwuity admin room (!admin token issue --once) and register through Element, then add the client in the maubot UI.

Invite the bot to whichever rooms it should serve via /invite @<bot>:<domain> — maubot's autojoin handles new invites that arrive after the client's sync loop is up.

Patterns + gotchas

Maubot-specific patterns (command decorators, multi-line caveats, database_type in maubot.yaml, etc.) live in ~/dev/CLAUDE.md under "Maubot plugin development". Read that before writing a new plugin — there are several footguns that look fine but silently lose data.