Tom Foster
6f6b23fd4d
Add Name field to stickers for user-friendly emoji shortcodes instead of SHA256 hashes, improving UX when using stickers as inline emoji. Features: - Add Name field to Sticker struct (defaults to SHA256) - New command: !sticker name <id> <shortcode> - Shortcode validation (alphanumeric, underscore, hyphen, 1-64 chars) - Publishing uses Name as emoji shortcode key (e.g. :happy_cat:) - SHA256 remains internal ID for deduplication Display updates: - !sticker show <id> displays shortcode name - !sticker list unsorted shows (:shortcode:) alongside alt-text - !sticker pack show <pack> shows (:shortcode:) for each sticker Example: - Before:  - After:  New stickers default to SHA256 hash until user sets friendly name. |
||
|---|---|---|
| .forgejo/workflows | ||
| cmd/stickerbook | ||
| internal | ||
| .gitignore | ||
| .markdownlint.yaml | ||
| .pre-commit-config.yaml | ||
| config.example.yaml | ||
| docker-compose.yml | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| README.md | ||
matrix-stickerbook
Bot and CLI for collecting images, organising, and publishing to Matrix rooms as MSC2545 sticker pack state events using simple text commands. Works with any image (not just stickers), the bot downloads and rehosts images to your homeserver, generates alt-text using Claude Haiku for accessibility, and deduplicates by content hash.
Built with mautrix-go, anthropic-sdk-go, Cobra, and Viper.
Command reference
All commands are plain text messages in any Matrix room the bot can see:
| Command | Description |
|---|---|
!sticker |
Show help |
!sticker list unsorted |
Stickers not in any pack |
!sticker show <id> |
Preview sticker with metadata |
!sticker name <id> <shortcode> |
Set emoji shortcode (e.g. happy_cat) |
!sticker usage <id> <type> |
Set usage (sticker/emoticon/both/reset) |
!sticker delete <id> |
Remove from collection |
!sticker pack list |
All packs with sticker counts |
!sticker pack create <name> |
Create a new pack |
!sticker pack show <pack> |
List stickers in a pack |
!sticker pack add <pack> <id> |
Add sticker to pack |
!sticker pack remove <pack> <id> |
Remove sticker from pack |
!sticker pack avatar <pack> <mxc> |
Set pack icon |
!sticker pack usage <pack> <type> |
Set default usage (sticker/emoticon/both/reset) |
!sticker pack publish <pack> [room] |
Publish to room (or republish to all) |
Getting started
You'll need a Matrix homeserver account and an Anthropic API key for alt-text generation.
Configuration and data is stored in ~/.config/stickerbook/ (or /data/ in Docker) - it creates
a blank config file on launch if needed, and see config.example.yaml for
configuration options. Your collection then lives in collection.json and pack definitions in
packs.json - easy to view, edit, or backup.
Local build
Install Go then build and run:
# Build the binary
go build ./cmd/stickerbook
# Generate Matrix login token
./stickerbook login
# Test connectivity
./stickerbook test
# Run the bot
./stickerbook bot
Docker
Install Docker then either see
docker-compose.yml for Docker Compose, or run directly:
# Generate Matrix login token
docker run --rm -it -v /path/to/data:/data \
git.tomfos.tr/tom/matrix-stickerbook:latest login
# Test connectivity
docker run --rm -v /path/to/data:/data \
-e ANTHROPIC_API_KEY=sk-ant-... \
git.tomfos.tr/tom/matrix-stickerbook:latest test
# Run the bot in daemon mode
docker run -d -v /path/to/data:/data \
-e ANTHROPIC_API_KEY=sk-ant-... --network host \
--name stickerbook \
git.tomfos.tr/tom/matrix-stickerbook:latest bot