matterhorn-chat/matterhorn

A feature-rich Unix terminal client for the Mattermost chat system

Matterhorn is a terminal client for the Mattermost chat system.

Quick Start

We provide pre-built binary releases for some platforms. Please see the release list to download a binary release for your platform that matches your server version:

https://github.com/matterhorn-chat/matterhorn/releases

To run Matterhorn, unpack the binary release archive and run the matterhorn binary within. Help is available via the --help or -h flag.

$ matterhorn --help
$ matterhorn

When you run Matterhorn you'll be prompted for your server URL and credentials. To connect, just paste your web client's Mattermost URL into the Server URL box and enter your credentials. See the Matterhorn User Guide on the details for providing each kind of supported credentials.

Note: Version ABBCC.X.Y matches Mattermost server version A.BB.CC. For example, if your Mattermost server version is 3.6.0 then you would download matterhorn version 30600.2.4. See Our Versioning Scheme for details.

Installation Requirements

For most of our binary releases, no additional packages need to be installed; they should just work out of the box. But here are some additional requirements that may apply for your platform:

• CentOS Steam 8
  • The ncurses-compat-libs package must be installed.

Other Ways to Install: Third-Party Snap Package

@3v1n0 maintains a Snap package here:

https://github.com/3v1n0/matterhorn-snap/ (Snapcraft page)

Get Help!

We provide a number of avenues for getting support:

• Frequently asked questions
• Matterhorn User Guide
• Built-in help (/help)
• Command list
• Keybinding list
• Chat with the developers on the Mattermost Community server
• File tickets on this repository

Features

• Channel creation, deletion, and membership management commands
• Support for multiple teams
• Optimized channel-switching modes: M-a, M-s, and C-g
• Message posting, editing, replying, and deletion
• Markdown rendering
• Support for participating in threads via the thread window
• Convenient URL-opening with local browser
• Secure password entry via external command (e.g. OSX keychain)
• Secure authentication token entry via external command (e.g. OSX keychain)
• Yank verbatim content from messages into the system clipboard
• Optional live preview during message editing
• Optional smart quoting for efficient Markdown entry
• Edit messages with $EDITOR
• Rebindable keys (see /help keybindings)
• Message editor with kill/yank buffer and readline-style keybindings
• Support for adding and removing emoji post reactions
• Support for channel muting
• Tab-completion of:
  • Usernames: type @, then Tab to cycle through matches
  • Channel names: type ~, then Tab to cycle through matches
  • Commands: type /, then Tab to cycle through matches
  • Emoji: type : and then some text, then Tab to display and cycle through matches
  • Fenced code block languages: type three backticks to begin typing a code block, then Tab to cycle through available languages
• Support for attachment upload and download
• Spell-checking via Aspell
• Syntax highlighting of fenced code blocks in messages (works best in 256-color terminals)
• Flagging and unflagging of posts, which are then viewable with M-8 or /flags
• Support for SOCKS 4 and 5 proxies via the ALL_PROXY and HTTPS_PROXY environment variables. (Plain HTTP proxies are not yet supported.) Also supports NO_PROXY.
• Multiple color themes with color theme customization support
• Custom notifications via notification scripts (see the activityNotifyCommand configuration setting and docs/notification-scripts.md for details).
• Optional mouse support

Our Versioning Scheme

Matterhorn version strings will be of the form ABBCC.X.Y where ABBCC corresponds to the lowest Mattermost server version expected to be supported by the release. For example, if a release supports Mattermost server version 1.2.3, the ABBCC portion of the matterhorn version will be 10203. There may be later versions of the Mattermost server that are supported (e.g. Matterhorn 50200.X.Y supports Mattermost server versions 5.2 through at least 5.8).

The X.Y portion of the version corresponds to our own version namespace for the package. If the server version changes, X.Y SHOULD be 0.0. Otherwise the first component should increment if the package undergoes major code changes or functionality changes. The second component alone should change only if the package undergoes security fixes or other bug fixes.

Our Design Philosophy

Overall, we strive to build a terminal client that provides the same basic feature set as the web client. This is reflected in the state of the client, our issue backlog, and the content of our wiki feature design discussions.

We intend to add web client features to Matterhorn to the extent that they can be added sensibly in a terminal setting. Our goal is to do so in a way that minimizes surprise to web client users migrating to Matterhorn while also providing the best terminal user experience that we can think of. That might entail adding the web client features but changing their designs to ones better suited for terminal use or it might mean omitting aspects of web client features that rely heavily on mouse- or DOM-related UI idioms. It might also entail adding web client features but deviating slightly on specific behaviors.

If you are used to a web client feature and don't see it in Matterhorn, that's probably because we just haven't gotten to it yet. We would be happy to hear from people wanting to contribute! If you can't contribute, search existing issues to see if we already have an issue for it, or create a new issue and let us know!

Contributing

If you decide to contribute, that's great! Here are some guidelines you should consider to make submitting patches easier for all concerned:

• If you are new to Haskell and are unsure how much Haskell you need to know in order to contribute, please see our list of Haskell skills needed.
• Please base all patches against the develop branch unless you are specifically fixing a bug in a released version, in which case master is a fine place to start. Please also do this for submodules that have a develop branch if you need to contribute changes to submodules.
• If you want to take on big things, let's have a design/vision discussion before you start coding. Create a GitHub issue and we can use that as the place to hash things out. We'll be interested to discuss any usability / UI, performance, or compatibility issues.
• Please make changes consistent with the conventions already used in the codebase.
• We follow a few development practices to support our project and it helps when contributors are aware of these. Please see our practices document for more information.

Building

If you just want to run Matterhorn, we strongly suggest running a binary release (see above). Building from source is only recommended if you intend to contribute.

If you want to contribute changes to Matterhorn, you'll need to build it from source. See our building instructions for details.

matterhorn's Issues

Permit querying channel membership

It'd be nice to be able to see who is a member of a given channel (even if only the current one). Via a /members command, say.

Display UI immediately ASAP, load data asychronously

The client interface takes a few seconds (sometimes 3-5s for me) to appear while various data are fetched. I'd like to refactor things so that we can go ahead and show the UI with no channels and some status information like "Loading..." rather than staring at the shell wondering what is happening.

Add support for more channel jumping keys

For example:

• jump to channel with oldest unread activity (this is M-a in glirc2)
• jump back to previous channel (this is M-s in glirc2)

more? ...

Add command history support

Up and Down arrow keys in the editor (when it is not in some kind of multi-line editing mode) should cycle through the command history.

Support for creating new channels

This applies to both standard channels and DM channels. (Right now the dm command silently does nothing when you give it a DM channel name that does not already exist.)

Support for inviting other users to channels

Replace Message boolean flags with type

We have a bunch of boolean flags in our Message type right now but most if not all of them are mutually exclusive. I think we can improve the Message structure and simplify its rendering routine (plus get some more functionality I want) by collapsing all of those booleans into a single message type field.

Display date transition lines in chat message lists

Right now we have adjacent messages from different days and it isn't clear which days they are from. It'd be nice to turn

[23:59] user1: huh?
[00:04] user2: no.

into something like

[23:59] user1: huh?
  -- Jan 1 2016 --
[00:04] user2: no.

with a configurable date format string just as with time formatting.

Pasting is slow and sometimes typing too

There is a lot of latency when pasting (and sometimes when typing).

When pasting a long line (let's say an 80 character url) you can watch the characters appear one by one. My subjective assessment is that it is worse in channels with a lot of visible scrollback. Sometimes I can even get ahead of the cursor while typing.

Connection health and autoreconnect

I don't see this as a core feature, but instead as a nice to have feature.

We should make an effort to detect when the websocket connection is dead and reconnect as soon as possible. The way glirc handles this is to use a ping + timer. If there is no response from a ping after N seconds (by default N = 60) the client initiates a reconnect.

I don't know if the websockets library exposes server pings or not. If it does not, then we could simulate it by periodically initiating benign requests such as mmGetMe that just test our ability to fetch data that should always be available to us.

It's also worth noting that this connection health could correspond to both the one shot HTTP requests and the websocket connection. It's likely worth monitoring both. If we only test HTTP request we could hit an edge case where the internet connection dropped for just long enough to disrupt the websocket but came back fast enough to not interrupt HTTP requests.

Deal gracefully with Websocket exceptions

We're getting an occasional ParseException "Failed reading: unknown opcode ..." and it appears to be coming from the Websocket library.

To wit:

$ ag ParseException
websockets-0.9.7.0/src/Network/WebSockets/Stream.hs
156:    go (Atto.Fail _ _ err) _ = throwIO (ParseException err)

websockets-0.9.7.0/src/Network/WebSockets/Types.hs
121:    | ParseException String

websockets-0.9.7.0/tests/haskell/Network/WebSockets/Server/Tests.hs
133:    handleClose _ (ParseException _) =
146:        handler (ParseException _) = error "Unexpected parse exception"

Configuration file support for color themes

I'd like to add support for color theme configuration. To start with, this just means looking in the XDG directory (say) for a new theme.ini and use the brick attribute names as keys therein. Then we'd use that info to update the existing color theme attribute map.

Prompt for credentials interactively if missing from config

If the configuration doesn't specify a username and/or password method, prompt for one or both interactively on startup. We can take the same approach as for team selection: fire up a secondary Brick application to collect the values, then continue with the main application.

Find a better name for `dm`

Such as msg. I'd suggest adding command aliases but in this case I think (say) msg is a better name and is going to be less surprising.

Respect the user's bg terminal color

Right now we seem to be overriding the background color in the terminal. To reproduce use a light terminal color such as solarized light and then run matterhorn. When matterhorn runs the background color is dark.

We could handle this several different ways. My preference would be to simply not set the bg color, but if there are technical issues with that then we should allow the user to set a config option.

Add `/me` support

And let's make it render properly.

Add a command to set the channel topic

Such as /topic.

Implement support for multi-line messages

I'm not sure what the best UI is for managing newline insertion vs. sending (e.g. Enter confusion) and other considerations like modifier combinations in common terminal emulators, but we'll need this at some point.

Send requests asynchronously

From my chat messages: It occurs to me that the client could also greatly benefit from sending requests asynchronously, i.e. when we send a message it goes into a Chan and a worker thread sends it, rather than blocking the brick redraw on a mattermost-api library operation. That is most evident right now when you change channels, where we do a watermark update API call to the server and it causes a channel switch delay.

Configuration file support for date/time formatting

Right now we format time as [%HH:%MM] where %HH puts it in 24hour time. This might not appeal to all users. Allowing users to specify their favorite date formatting would be better and should be fairly easy to support given that we use the formatTime function.

Display notifications of unread messages

We need to annotate normal and DM channels with unread message counts (and thus track watermarks of some kind).

Support for joining and leaving channels

Permit scrolling in message lists

Right now we don't expose a binding for scrolling the chat message area. This is easy to do but the bigger task is to figure out the UI focus behavior (if any). And when we implement scrolling in the message area, it has to interact well with the visibility request used to keep the window scrolled to the last message.

Consider markdown formatting

Using e.g. https://hackage.haskell.org/package/cheapskate

Don't mark channel unread if it only has new messages from self

If I send a message to a channel and quickly switch to another channel, the channel I left appears to have unread messages. But I don't think it should, because I know I sent a message. I want to know when it has unread messages from anyone else. I think it makes sense to only update the unread status under that condition.

Support for logging protocol information

Add support for tab completion

We need editor tab-completion support for (at least):

• Channel names
• Command names (and possibly arguments)
• User names

Denote online/offline users

It'd be nice if I could tell who is actually online. An indicator next to the username in the user list is one way to do this. Alternatively we could split the user list into two groups:

----Users (online)-----
...
...
----Users (offline)----
...
...

Be more precise about list vs. set

We have lots of lists that should probably be sets. Particularly, I noticed this in ChatState and transitively in the types of its fields.

Add support for formatted text in message lists

This includes highlighting tokens of interest (usernames, URLs, etc.) and making this compose with line-wrapping.

Help screen

We need a screen that shows keybindings and commands.

Make command handlers check numbers of arguments

It'd be nice if command dispatching handled invalid argument counts gracefully. It'd be nice to update the Command type with an argument list description so we can both validate input and generate help for the expected arguments (rather than just crashing on a pattern match failure).

`dm` command does not accept "@"-prefixed usernames

E.g. if I run the command

/dm @ijones

then I get

[12:43] *matterhorn: No user named @@ijones

I propose that dm accept usernames with or without @.

Support responding to channel invites from other users

Share your work with Mattermost community?

Hi @aisamanra,

Saw your and everyone else's work for MatterHorn and we'd love to help share it with the Mattermost community. Would you be open to sharing more about your project? https://www.mattermost.org/share-your-mattermost-projects/

Also, we'd like to welcome everyone to join the integrations community on our nightly builds server, if anyone would like: https://pre-release.mattermost.com/core/channels/integrations

Wonderful work!

Show typing notifications

I think those are nice to have. There is probably a way we can display these unobtrusively.

Use the same message formatting for the text editor

So we can get color in usernames etc. while editing.

Filter out self from user list

The user channel list includes the user that is logged in. I think we should probably filter that one out. :)

Make *emphasized* text more noticeable

Either/or by using a color or text style attribute.

Give user a choice of team interactively

Right now the client requires the config to provide a team name. This is nice if you know which one you want, but when you don't, it would be good to have the client mirror the web client UX and allow the user to choose the team interactively based on the user's team list. The API has been updated to provide this and the client now fetches that restricted team list, but it still uses the config file team. This task is to make the team selection interactive when there is no team in the config. As a bonus we could even update the config with the selected team so the user never has to deal with this.

Make unread direct messages easier to spot

Right now the direct message channel (user) list is long enough that you have to scroll it just to check on whether there are any unread messages. To make it easier to tell if there are unread messages (but to preserve the ability to message anyone by scrolling to their name), I propose we sort the user list by most recent communication. This could be annoying but it's also optimized for the common case by showing you users with whom you communicated most recently. And if we have a good /focus command then it's no longer important to sort the list alphabetically.

Thoughts @dagit and @aisamanra?

Implement more text-editing keybindings

Such as:

• M-Backspace: delete word backward
• M-d: delete word forward
• M-{Left,Right}: move by word
• C-k, C-y: kill and yank

Evict old chat messages

Right now we render all the chat messages we have for each channel, but as the client runs for longer and longer periods of time, we render them even though they're unlikely to ever get seen again (even once we implement scrolling up). The cost to this is that they get drawn and cropped rather than not drawn at all, so I think we should be evicting them (i.e. keeping at most N for reasonable N messages in the channel message lists).

The /help command doesn't scroll when the backlog is full

If your current channel is full of text and you are at the very bottom, typing /help doesn't scroll the channel text. You have to hit page down to see the help text.

Improve channel join messages

Right now we have a redundant username in such messages:

[10:51] tristan: tristan has joined the channel.

Improve username color distribution

With only 16 colors we're going to have collisions. So this may not be fixable. This ticket is here to serve as a place to document ideas related to improving the coloring.

I'll go first, here is a vague rule I think would help:

• Use different colors for different length nicks, especially when the nicks have similarity (eg., batman and badman should preferably be different colors). We might compute similarity using hamming distance or levenshtein distance.

If you can think of other heuristics then let's try to collect them here.

Delimit unread messages in channel message lists

I'd like the client to show me which messages are new because it's often hard to remember what I last saw. So something like

[01:00] user1: foo
  -- New messages --
[01:01] user2: bar
[01:02] user3: blah

Preserve editor content when switching tabs

I found that I wanted to start typing a message in one channel, switch to another to get some information, and come back and finish. Right now that can't be done because we clear the editor on channel change. We'll need a map in the state to map from Channel ID to editor content and populate that on channel switch.

crash trying to /dm some users

If you try to /dm <user> where you have never messaged <user> before you will get a crash because of an irrefutable pattern match failure, like this:

matterhorn: src/State.hs:156:3-45: Irrefutable pattern failed for pattern Just n'

Display a useful error message when 'passcmd' fails

For example, currently I get:

$ .cabal-sandbox/bin/matterhorn
matterhorn: security: readCreateProcess: runInteractiveProcess: exec: does not exist (No such file or directory)

because I stupidly ran this under linux where security is not a valid command.