amoorion

One heart for all your conversations.
Universal tool for administration of chatting and communication platforms

web page · documentation · PyPI · GitHub

Getting started

documentation: https://amoorion.readthedocs.io

pip install amoorion amoorion-bluesky        # the core and the platforms you use
amoorion                                     # asks step by step what to do
amoorion publish --text "hello" --to dryrun  # dryrun sends nothing: try it first

What it does

• Publish: write once, post to every platform you name.
• Read & reply: read what came in, in one inbox, and answer from there.
• Keep: every profile's posts as JSON files in dataset/; delete keeps a copy of what it removes.
• Connect: link the platforms with each other and with the services around them (webhooks, ntfy, NATS, e-mail: phase 5 of the plan).

Early stage: every platform is tested against fakes of its API; trying them against real accounts is under way.

How it is built

One core (model, view, controller) and namespaces on it: plugins (one per platform), methods (what amoorion can do), and the faces that expose the methods: CLI, HTTP API, MCP server for AI agents, and a daemon for long-running services. Secrets come only from a vault (Bitwarden / Vaultwarden, HashiCorp Vault / OpenBao, or a KeePassXC file); .env holds just the link to it. Each platform is its own package in packages/ (a uv workspace). Details: docs/structure.md, writing a plugin: docs/plugins.md.

Usage

uv sync
cp example.env .env                          # the link to the vault

uv run amoorion                              # asks step by step what to do (or: amoorion -i)
uv run amoorion plugins                      # platforms and what they can do
uv run amoorion accounts                     # which have their secrets in the vault
uv run amoorion publish --text "hello" --to dryrun bluesky
uv run amoorion --json read --platform bluesky
uv run amoorion reply --platform bluesky --to "at://…" --text "thanks"
uv run amoorion inbox                        # everything read or received so far
uv run amoorion snapshot --platform bluesky  # its posts into dataset/bluesky/<profile>/ (JSON, indexed)
uv run amoorion delete --platform bluesky --id "at://…"   # keeps a copy in the dataset first
uv run task help                             # help of every command

uv run amoorion api                          # HTTP API on 127.0.0.1:8000
uv run amoorion mcp                          # MCP server (stdio) for agents
uv run amoorion daemon                       # long-running services

The API needs the secret api/token in the vault (sent as Authorization: Bearer), and every hook its own secret; without them they refuse calls. Where each backend keeps a secret: docs/structure.md. Each platform's secrets are listed in its package's README, e.g. packages/amoorion-bluesky.

Run locally first; a Dockerfile and compose come next (phase 6 of the plan).

Development

uv run task init               # tools, git hooks, .env, then check
uv run task vault:new          # KeePassXC: the file of AMOORION_VAULT_PATH, an empty entry per platform
uv run task vault:status       # the vault's state, and which platforms have their secrets
uv run task vault:tools        # Bitwarden instead: bw by npm into tools/, then vault:login
uv run task check              # tests, YAML, commit messages, docs (= CI)
uv run task docs:build         # the docs site into docs/_build/html
uv run task plugin:new -- <platform> <Class> "<description>"   # a new platform
uv run task test:connect       # read-only: log in to every platform with its secrets, read a few posts
uv run task test:live          # a real test post on each (or: -- bluesky mastodon), read, replied, deleted

Examples of usage: Jupyter notebooks in examples/ (uv run task examples:build makes marimo notebooks and pages of them). The docs (this README, the guides, the plan and an API reference generated from the code) are built by Sphinx from docs/ for Read the Docs. Plan and open questions: docs/devlog/. Guide for agents and contributors: AGENTS.md.

Reference

• https://pl.wikipedia.org/wiki/(1221)_Amor
• https://github.com/sarverott/amoorion/
• https://amoorion.readthedocs.io
• https://pypi.org/project/amoorion/
• https://sarverott.github.io/amoorion
• https://sarverott.tumblr.com/post/831595954743459840/github-sarverottamoorion-universal-tool-for
• https://x.com/sarverott/status/2114859609823301649

License

Free, under the MIT License, © 2024–present Sett Sarverott: LICENSE, https://sett.mit-license.org

For agents

amoorion comes with an agent skill: amoorion --json skill gives it to any agent. In Claude Code:

/plugin install amoorion --marketplace Sarverott/amoorion