Ement.el is a Matrix client for Emacs. It aims to be simple, fast, featureful, and reliable.
Feel free to join us in the chat room: https://img.shields.io/matrix/ement.el:matrix.org.svg?label=%23ement.el:matrix.org
Ement.el is published in GNU ELPA as ement, so it may be installed in Emacs with the command
M-x package-install RET ement RET. This is the recommended way to install Ement.el, as it will install the current stable release.
The latest development build may be installed from ELPA-devel or from Git (see below).
Ement.el is also available in some other distributions. See Repology for details.
master branch of the Git repository is intended to be usable at all times; only minor bugs are expected to be found in it before a new stable release is made.
;; Install and load `quelpa-use-package'. (package-install 'quelpa-use-package) (require 'quelpa-use-package) ;; Install Ement. (use-package ement :quelpa (ement :fetcher github :repo "alphapapa/ement.el"))
ement-connectto connect. Multiple sessions are supported, so you may call the command again to connect to another account.
ement-list-roomsto view the list of joined rooms.
ement-view-roomto view a room’s buffer, selected with completion.
ement-create-roomto create a new room.
ement-create-spaceto create a space.
ement-invite-userto invite a user to a room.
ement-join-roomto join a room.
ement-leave-roomto leave a room.
ement-forget-roomto forget a room.
ement-tag-roomto toggle a tag on a room (including favorite/low-priority status).
ement-list-membersto list members in a room.
ement-send-direct-messageto send a direct message to a user (in an existing direct room, or creating a new one automatically).
ement-room-edit-messageto edit a message at point.
ement-room-send-fileto send a file.
ement-room-send-imageto send an image.
ement-room-set-topicto set a room’s topic.
ement-room-occurto search in a room’s known events.
ement-room-override-nameto override a room’s display name.
ement-ignore-userto ignore a user (or with interactive prefix, un-ignore).
ement-room-set-message-formatto set a room’s message format buffer-locally.
ement-room-toggle-spaceto toggle a room’s membership in a space (a way to group rooms in Matrix).
ement-directoryto view a room directory.
ement-directory-searchto search a room directory.
These bindings are common to all of the following buffer types:
M-RET(while writing in minibuffer:
C-c ')(Use command
ement-room-compose-orgto activate Org mode in the compose buffer.)
completion-at-pointcommand). (Type an
@prefix for a member mention, a
#prefix for a room alias, or a
!prefix for a room ID.)
ement-room-send-message-filter(which enables Org format by default), or by calling
ement-room-compose-orgin 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:
SPCrepeatedly, you can cycle through and read all rooms with unread buffers. (If a room doesn’t have a buffer, it will not be included.)
@followed by their displayname or Matrix ID. (Members’ names and rooms’ aliases/IDs may be completed with
setqshould 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.
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")
ement-notificationsshows recent notifications, similar to the pane in the Element client. (This new command fetches recent notifications from the server and allows scrolling up to retrieve older ones. Newly received notifications, as configured in the
ement-notifyoptions, are displayed in the same buffer. This functionality will be consolidated in the future.)
ement-room-quote, applied to quoted parts of replies.
ement-room-goto-prevwork more usefully at the end of a room buffer. (Now pressing
non the last event moves point to the end of the buffer so it will scroll automatically for new messages, and then pressing
pskips over any read marker to the last event.)
ement-room-goto-prevare bound to
ement-room-goto-fully-read-markeris bound to
M-g M-p(the mnemonic being "go to previously read").
ement-connectuser ID prompts use separate history list variables.
savehist-mode’s serializing of the
command-historyvariable’s arguments. (For
ement-commands, that may include large data structures, like
ement-sessionstructs, which should never be serialized or reused, and
savehist’s doing so could cause noticeable delays for users who enabled it). (See #216. Thanks to Phil Sainty and other users who helped to discover this problem.)
M-RETwhen point is at an image) view and scale images. (Thanks to Steven Allen for these and other image-related improvements.)
ement-room-image-show-mouseis used to show an image with the mouse.
image-modewhen showing images in a new buffer. (Thanks to Steven Allen.)
ement-room-image-showis not used for mouse events.
ement-room-list-next-unreadcould enter an infinite loop. (Thanks to Visuwesh and
ement-read-receipt-idle-timercould be duplicated when using multiple sessions. (#196. Thanks to Phil Sainty.)
.gpg), if the recipient’s private key or the symmetric encryption key were cached by Emacs (or a configured agent, like
gpg-agent), Emacs would automatically decrypt the file while reading its contents and then upload the decrypted contents. (This happened because the function
insert-file-contentswas used, which does many things automatically, some of which are not even mentioned in its docstring; refer to its entry in the Elisp Info manual for details. The fix is to use
insert-file-contents-literallyinstead.) Thanks to
min room buffers to
ement-room-mark-read(which moves read markers to point).
ement-view-space(which shows a directory of rooms in the space) instead of
ement-view-room(which shows events in the space, which is generally not useful).
ement-view-room, when used for a space, shows a footer explaining that the buffer is showing a space rather than a normal room, with a button to call
ement-view-spacefor it (which lists rooms in the space).
ement-describe-roomshows whether a room is a space or a normal room.
ement-view-spaceshows the space’s name and alias.
ement-room-scroll-up-mark-readmoves the fully read marker to the top of the window (when the marker’s position is within the range of known events), rather than only moving it when at the end of the buffer. (This eases the process of gradually reading a long backlog of messages.)
ement-room-list-modewhen room list buffer is refreshed. (#146. Thanks to Ted Reed for reporting.)
ement-room-listcommand upon initial sync.
ement-room-timestamp-header-aligncontrols how timestamp headers are aligned in room buffers.
ement-room-view-hookruns functions when
ement-room-viewis called. (By default, it refreshes the room list buffer.)
ement-room-timestamp-header-align, timestamp headers default to right-aligned. (With default settings, this keeps them near message timestamps and makes for a cleaner appearance.)
ement-room-listwhen no rooms are joined. (Fixes #123. Thanks to @Kabouik and Omar Antolín Camarena for reporting.)
(map :KEYWORD)form. (This can cause a broken installation on older versions of Emacs that have an older version of the
maplibrary loaded, such as Emacs 27.2 included in Debian 11. Since there’s no way to force Emacs to actually load the version of
maprequired by this package before installing it (which would naturally happen upon restarting Emacs), we can only avoid using such forms while these versions of Emacs are widely used.)
Added missing changelog entry (of course).
ement-create-spacecreates a new space.
ement-room-toggle-spacetoggles a room’s membership in a space (a way to group rooms in Matrix).
ement-room-list-kill-bufferkills a room’s buffer from the room list.
initial_device_display_nameupon login (e.g. ‘Ement.el: username@hostname’). (#134. Thanks to Arto Jantunen for reporting.)
ement-room-listreuses an existing window showing the room list when possible. (#131. Thanks to Jeff Bowman for suggesting.)
ement-tag-roomtoggles tags (rather than adding by default and removing when called with a prefix).
ement-room-override-namesets a local override for a room’s display name. (Especially helpful for 1:1 rooms and bridged rooms. See MSC3015.)
ement-view-spacewhen called from a room buffer. (Thanks to Richard Brežák for reporting.)
display-bufferwhen reverting room list buffer. (Fixes #121. Thanks to mekeor for reporting.)
:roomargument to put on a room’s account data.
ement-view-spaceto view a space’s rooms in a directory buffer.
ement-describe-roomcommand (formatting, bindings).
ement-initial-sync-timeoutproperly (important for when the homeserver is slow to respond).
ement-room-list. (The old,
tabulated-list-mode-based room list is available as
ement-room-unread-only-counts-notifications, now enabled by default, causes rooms’ unread status to be determined only by their notification counts (which are set by the server and depend on rooms’ notification settings).
ement-room-set-notification-statesets a room’s notification state (imitating Element’s user-friendly presets).
ement-set-display-namesets the user’s global displayname.
ement-room-set-display-namesets the user’s displayname in a room (which is also now displayed in the room’s Transient menu).
ement-taxy-room-listbuffer shows rooms’ notification state.
ement-interrupted-sync-hookallows customization of how sync interruptions are handled. (Now, by default, a warning is displayed instead of merely a message.)
ement-forget-roomin room buffers.
ement-directoryshows a server’s room directory.
ement-directory-searchsearches a server’s room directory.
ement-directory-nextfetches the next batch of rooms in a directory.
FORCE-Pargument (interactively, with prefix) to leave a room without prompting.
FORCE-Pargument (interactively, with prefix) to also leave the room, and to forget it without prompting.
ement-notify-mark-frame-urgent-predicatesmarks the frame as urgent when (by default) a message mentions the local user or "@room" and the message’s room has an open buffer.
ement-describe-roomfor rooms without topics.
window-scroll-functions, which sometimes caused a strange race condition that could cause Emacs to become unresponsive or crash.)
ement-taxy-room-listview no longer automatically refreshes the list if the region is active in the buffer. (This allows the user to operate on multiple rooms without the contents of the buffer changing before completing the process.)
ement-room-synccorrectly updates room-list buffers. (Thanks to Visuwesh.)
ement-room-scroll-up-mark-readselects the correct room window.
ement-room-list-avatarsdefaults to what function
Bug reports, feature requests, suggestions — oh my!
Ement.el is published in GNU ELPA and is considered part of GNU Emacs. Therefore, cumulative contributions of more than 15 lines of code require that the author assign copyright of such contributions to the FSF. Authors who are interested in doing so may contact firstname.lastname@example.org to request the appropriate form.
An Org-formatted version of the Matrix spec is available in the meta/spec branch.
This section is preserved for posterity. As it says, Ement.el has long since surpassed
matrix-client, which should no longer be used.
Why write a new Emacs Matrix client when there is already matrix-client.el, by the same author, no less? A few reasons:
matrix-clientuses 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-clientdoes 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-clientautomatically 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-clientwas 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-clientuses EIEIO, probably unnecessarily, since few, if any, of the benefits of EIEIO are realized in it. Ement.el uses structs instead.
matrix-clientuses 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)
ewoclibrary, 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-clientwas, to a certain extent, designed to imitate other messaging apps. The result is, at least when used with the
matrix-client-framecommand, 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.
ementis easy to type and makes for concise, readable code.
matrix-clientand hopes to write simpler, more readable, more maintainable code in Ement.el. It’s hoped that this will enable others to contribute more easily.
Note that, while
matrix-client remains usable, and probably will for some time to come, Ement.el has now surpassed it in every way. The only reason to choose
matrix-client instead is if one is using an older version of Emacs that isn’t supported by Ement.el.