Ement.el is a new Matrix client for Emacs. It aims to be simple, fast, featureful, and reliable.
Feel free to join us in the chat room:
The default formatting style resembles IRC clients, with each message being prefixed by the username (which enables powerful Emacs features, like using Occur to show all messages from or mentioning a user). Alternative, built-in styles include an Element-like one with usernames above groups of messages, as well as a classic, no-margins IRC style. Messages may be optionally displayed with unique colors for each user (with customizeable contrast), making it easier to follow conversations. Timestamp headers are optionally displayed where a certain amount of time passes between events, as well as where the date changes.
Two rooms shown in side-by-side buffers, showing inline images, reactions, date/time headings, room avatars, and messages colored by user (using the modus-vivendi Emacs theme).
#emacs:libera.chat showing colored text from IRC users, replies with quoted parts, messages colored by user, addressed usernames colored by their user color, highlighted mentions, and the fully-read marker line (using the modus-vivendi Emacs theme).
Four rooms shown at once, with messages colored by user, in the default Emacs theme.
A room at the top in the “Elemental” display style, with sender names displayed over groups of messages, and only self-messages in an alternate color. The lower window shows an earlier version of the rooms list.
Reactions displayed as color emojis (may need proper Emacs configuration).
The recommended way to install is with quelpa-use-package, like this:
;; Install and load `quelpa-use-package'.
(package-install 'quelpa-use-package)
(require 'quelpa-use-package)
;; Install `plz' HTTP library (not on MELPA yet).
(use-package plz
:quelpa (plz :fetcher github :repo "alphapapa/plz.el"))
;; Install Ement.
(use-package ement
:quelpa (ement :fetcher github :repo "alphapapa/ement.el"))
If you want to install it manually, it’s simple enough, but you should know what you’re doing, and you’re on your own.
- Call command
ement-connect
to connect. Multiple sessions are supported, so you may call the command again to connect to another account. - Wait for initial sync to complete (which can take a few moments–initial sync JSON requests can be large).
- Use these commands:
ement-list-rooms
to view the list of joined rooms.ement-view-room
to view a room’s buffer, selected with completion.ement-create-room
to create a new room.ement-invite
to invite a user to a room.ement-join-room
to join a room.ement-leave-room
to leave a room.ement-forget-room
to forget a room.ement-send-direct-message
to send a direct message to a user (in an existing direct room, or creating a new one automatically).ement-room-edit-message
to edit a message at point.ement-room-send-image
to send an image message.ement-room-set-topic
to set a room’s topic.ement-room-set-message-format
to set a room’s message format buffer-locally.
- Use these special buffers to see events from multiple rooms (you can also reply to messages from these buffers!):
- See all new events that mention you in the
*Ement Mentions*
buffer. - See all new events in rooms that have open buffers in the
*Ement Notifications*
buffer.
- See all new events that mention you in the
These bindings are common to all of the following buffer types:
- Switch to the room list buffer:
M-g M-l
- Switch to the mentions buffer:
M-g M-m
- Switch to the notifications buffer:
M-g M-n
Sending messages
- Write new message:
RET
- Write reply to event at point (when region is active, only quote marked text) :
S-RET
- Complete members and rooms at point:
C-M-i
(standardcompletion-at-point
command). - Compose message in a separate buffer (while writing in minibuffer):
C-c '
(Use commandement-room-compose-org
to activate Org mode in the compose buffer.) - Send emote:
e
- Send reaction (a type of annotation) to event at point, or send same reaction at point:
a
- Delete message at point:
C-k
Viewing rooms
- Move between events:
TAB
/<backtab>
- Scroll down (at the end of a room buffer, mark it as read and bury it):
SPC
- Scroll up:
S-SPC
- Move to the fully-read marker:
M-SPC
- Load older messages: at top of buffer, scroll up (i.e.
S-SPC
,M-v
ormwheel-scroll
) - Show source of event at point:
v
- Show another room:
r
- Show room list buffer:
R
- Sync new messages (not necessary if auto sync is enabled; with prefix to force new sync):
g
Viewing images
- Toggle scale of image at point (between fit-to-window and thumbnail):
mouse-1
- Show image in new buffer at full size:
double-mouse-1
- Show buffer of room at point:
RET
- Show buffer of next unread room:
SPC
- Move between room names:
TAB
/<backtab>
- Move between events:
TAB
/<backtab>
- Go to event at point in its room buffer:
RET
- Write reply to event at point (shows the event in its room while writing) :
S-RET
- Desktop notifications are enabled by default for events that mention the local user. They can also be shown for all events in rooms with open buffers.
- Send messages in Org mode format by customizing the option
ement-room-send-message-filter
(which enables Org format by default), or by callingement-room-compose-org
in a compose buffer (which enables it for a single message). Then Org-formatted messages are automatically converted and sent as HTML-formatted messages (with the Org syntax as the plain-text fallback). You can send syntax such as:- Bold, italic, underline, strikethrough
- Links
- Tables
- Source blocks (including results with
:exports both
) - Footnotes (okay, that might be pushing it, but you can!)
- And, generally, anything that Org can export to HTML
- Starting in the room list buffer, by pressing
SPC
repeatedly, you can cycle through and read all rooms with unread buffers. (If a room doesn’t have a buffer, it will not be included.) - Room buffers and the room-list buffer can be bookmarked in Emacs, i.e. using
C-x r m
. This is especially useful with Burly: you can arrange an Emacs frame with several room buffers displayed at once, useburly-bookmark-windows
to bookmark the layout, and then you can restore that layout and all of the room buffers by opening the bookmark, rather than having to manually arrange them every time you start Emacs or change the window configuration. - You can customize settings in the
ement
group.- Note:
setq
should not be used for certain options, because it will not call the associated setter function. Users who have an aversion to the customization system may experience problems.
- Note:
Emacs may not display certain symbols and emojis well by default. Based on this question and answer, you may find that the simplest way to fix this is to install an appropriate font, like Noto Emoji, and then use this Elisp code:
(setf use-default-font-for-symbols nil)
(set-fontset-font t 'unicode "Noto Emoji" nil 'append)
Ement.el doesn’t support encrypted rooms natively, but it can be used transparently with the E2EE-aware reverse proxy daemon Pantalaimon. After configuring it according to its documentation, call ement-connect
with the appropriate hostname and port, like:
(ement-connect :uri-prefix "http://localhost:8009")
Why write a new Emacs Matrix client when there is already matrix-client.el, by the same author, no less? A few reasons:
matrix-client
uses an older version of the Matrix spec, r0.3.0, with a few elements of r0.4.0 grafted in. Bringing it up to date with the current version of the spec, r0.6.1, would be more work than to begin with the current version. Ement.el targets r0.6.1 from the beginning.matrix-client
does not use Matrix’s lazy-loading feature (which was added to the specification later), so initial sync requests can take a long time for the server to process and can be large (sometimes tens of megabytes of JSON for the client to process!). Ement.el uses lazy-loading, which significantly improves performance.matrix-client
automatically makes buffers for every room a user has joined, even if the user doesn’t currently want to watch a room. Ement.el opens room buffers on-demand, improving performance by not having to insert events into buffers for rooms the user isn’t watching.matrix-client
was developed without the intention of publishing it to, e.g. MELPA or ELPA. It has several dependencies, and its code does not always install or compile cleanly due to macro-expansion issues (apparently depending on the user’s Emacs config). Ement.el is designed to have minimal dependencies outside of Emacs (currently only one,plz
, which could be imported into the project), and every file is linted and compiles cleanly using makem.sh.matrix-client
uses EIEIO, probably unnecessarily, since few, if any, of the benefits of EIEIO are realized in it. Ement.el uses structs instead.matrix-client
uses bespoke code for inserting messages into buffers, which works pretty well, but has a few minor bugs which are difficult to track down. Ement.el uses Emacs’s built-in (and perhaps little-known)ewoc
library, which makes it much simpler and more reliable to insert and update messages in buffers, and enables the development of advanced UI features more easily.matrix-client
was, to a certain extent, designed to imitate other messaging apps. The result is, at least when used with thematrix-client-frame
command, fairly pleasing to use, but isn’t especially “Emacsy.” Ement.el is intended to better fit into Emacs’s paradigms.matrix-client
’s long name makes for long symbol names, which makes for tedious, verbose code.ement
is easy to type and makes for concise, readable code.- The author has learned much since writing
matrix-client
and hopes to write simpler, more readable, more maintainable code in Ement.el. It’s hoped that this will enable others to contribute more easily.
However, note that matrix-client
is a more mature client and is very reliable in the author’s experience. While Ement.el is intended to reach feature parity with it and eventually surpass it, that will take some time, so matrix-client
remains a good choice.
Yet to be released.
Bug reports, feature requests, suggestions — oh my!
- It’s recommended to set the variable
print-circle
tot
in your Emacs config. Ement.el uses circular data structures for some things, and these can cause Emacs to infinitely loop and/or allocate a large amount of memory when attemping to print a backtrace for an error (as well as when doing certain other things, like callingC-u C-x =
on text that has circular structures in its display properties). Setting this variable to non-nil prevents that behavior and allows Emacs to quickly print these structures.
While Ement.el is not yet available in GNU ELPA and is not part of Emacs, it would be good to keep that option available. In that case, cumulative contributions of more than 15 lines of code would require that the author assign copyright of such contributions to the FSF. Therefore, please note that this project may require such assignment before accepting contributions. Authors who are interested in doing so may contact [email protected] to request the appropriate form.
An Org-formatted version of the Matrix spec is available in the meta/spec branch.
GPLv3