Usage

Installation

To use MisTTY, first install its package,

from MELPA or MELPA Stable, using M-x package-install mistty

from source using M-x package-vc-install https://github.com/szermatt/mistty

And then launch it with M-x mistty, as described in Launching.

You’ll likely want to eventually bind that to some shortcut:

(use-package mistty
  :bind (("C-c s" . mistty)))

and, unless you’re using Bash, configure directory tracking for your shell (Directory Tracking), but read on for more details.

Launching

To create a new interactive shell buffer in MisTTY mode, call M-x mistty, which either creates a new shell or goes to an existing MisTTY buffer, or M-x mistty-create, which creates a new MisTTY buffer.

Here’s a quick list of the commands defined by the MisTTY package, their behavior and arguments:

mistty-createcommand

This command launches a new interactive shell in a MisTTY buffer in the current buffer’s default-directory.

The shell that is launched is the one that’s configured with M-x configure-option mistty-shell-command. If mistty-shell-command is not set, MisTTY falls back to explicit-shell-file-name, shell-file-name, then the environment variables ESHELL and SHELL.

With a prefix argument, this command asks for a directory for the new shell, instead of using the current buffer’s current directory. This is particularly useful if you want to run shell on a remote host. (Remote Shells with TRAMP)

By default, new buffers are called “*mistty*”, or, if you use TRAMP “*mistty@hostname*”. You can configure this with M-x customize-option mistty-buffer-name.

misttycommand

This command creates a new MisTTY buffer the first time it is called. Afterwards, it’ll try to guess what’s most appropriate, displaying an existing MisTTY buffer or creating a new one.

With a prefix argument, this command always creates a new buffer.

mistty-other-windowcommand

This command does the same as mistty but opens the buffer in another window.

mistty-create-other-window: command

This command does the same as mistty-create, but opens the buffer in another window.

If you need more control on how MisTTY windows are handled than what’s provided by the -other-window variants, you can configure it using M-x customize-option display-comint-buffer-action or M-x customize-option display-buffer-alist. In the latter case, note that MisTTY buffers belong to the comint category, just like shell buffers.

See the section “Window Choice” of the Emacs manual for details.

mistty-in-project: command

This command creates a new MisTTY buffer in the root directory of the current project the first time it is called. Afterwards, it’ll try to guess what’s most appropriate, displaying an existing MisTTY buffer or creating a new one.

With a prefix argument, this command always creates a new buffer.

Note that if you want M-x project-kill-buffers to kill such buffers, you’ll want to execute mistty-project-init-kill-buffer somewhere in your configuration or tell M-x configure-option project-kill-buffer-conditions about MisTTY.

mistty-sshcommand

This command creates a new MisTTY buffer connected to another host using SSH. This is just a shortcut that uses TRAMP to connect to a remote host. (Remote Shells with TRAMP)

mistty-docker: command

This command creates a new MisTTY buffer connected to a docker instance. This requires the docker command-line tool to be installed. This is just a shortcut that uses TRAMP to connect to a remote host. (Remote Shells with TRAMP)

Terminal vs. Scrollback

MisTTY buffers are divided into two distinct zones, exhibiting different behaviors:

The scrollback zone, is where you can see commands that have been executed and their output.

The terminal zone, marked by a purple line on the left of the window, is where you can type command and interact with the terminal. In this zone, TAB triggers the shell completion, if available. With some shells, you’ll see autosuggestions as you type.

The scrollback zone operates like a standard Emacs buffer, allowing you to modify it freely.

The terminal zone, on the other hand, imposes certain limitations. While a shell is attached, you can edit the command you are about to execute, but you can’t modify the prompt itself. Any changes made to the prompt will be reverted by the shell.

The terminal zone is where the magic happens: this is where you can use a mix of Emacs and shell key bindings to edit the command line. The trickiest part is choosing which key bindings you want Emacs to handle and which key bindings you want the shell to handle.

By default, Emacs intercepts most key bindings, but a few are sent directly to the terminal:

RET: Executes the command in the shell.
TAB: Initiates command completion in the shell.
C-a: Moves the cursor to the beginning of the line.
C-e: Moves the cursor to the end of the line.
C-d: Deletes the next character or exits the program.
M-p: Navigates upwards in the command history (equivalent to C-p in the terminal).
M-n: Navigates downwards in the command history (equivalent to C-n in the terminal).
M-r: Invokes reverse command history search (equivalent to C-r in the terminal). See Backward Search.
M-.: Inserts the last argument from command history.

Additionally, C-c C-c sends the TERM signal to the terminal.

The program connected to the terminal determines the actual effects of these shortcuts. While most shells and command-line editing tools support these shortcuts by default, behavior may vary.

Warning

MisTTY will not function if your shell is configured to use VI mode by default. Please disable VI mode before utilizing MisTTY. For instructions on disabling VI mode specifically for MisTTY buffers, while preserving it otherwise, consult see Shells. VI mode must be disabled even if you plan to use VI commands through Evil.

More generally, MisTTY relies on a set of common keybindings and behaviors to communicate with the terminal applications and will not behave properly if the application doesn’t understand these or interpret them in an unusual way. For a list of these keybindings, see Keybindings used by MisTTY.

To get the most out of MisTTY, it’s worth it to take the time to configure it to send to the terminal the shell key bindings that you actually use and keep everything else behaving as usual for your Emacs configuration.

To bind keys only in the terminal zone, bind them to mistty-prompt-map. To bind keys in both zones, bind them to mistty-mode-map. Examples are provided below.

The following commands are useful for sending key sequences to the current shell or terminal program:

mistty-send-keycommand

This command, when called interactively, forwards the key from which it was invoked. It is designed to be bound to the shell key bindings you wish to function in the terminal zone, mistty-prompt-map.

For example, to search in the shell command history, typically bound to C-r, MisTTY binds it to M-r, similar to comint. However, if you’d prefer to use the original binding, you can do the following:

(keymap-set mistty-prompt-map "C-r" #'mistty-send-key)

To have the key available in both the scrollback and terminal zones, bind it to mistty-mode-map instead.

You can also send arbitrary keys to mistty-send-key. For example:

(defun my-mistty-M-s (n)
  (interactive "p")
  (mistty-send-key n (kbd "M-s")))
(keymap-set mistty-prompt-map "C-c a" #'my-mistty-M-s)

mistty-send-last-keycommand: This command forwards the last key combination from the sequence it was invoked from to the terminal. For instance, C-c C-c is bound to mistty-send-last-key, such that the terminal ultimately receives just C-c.

For quick testing or for shell shortcuts you use infrequently, use the C-q prefix to bypass Emacs key bindings and send keys directly to the terminal. For example, pressing C-q <right> sends a right-arrow key press to the terminal instead of moving the cursor.

If further control is needed, try out:

mistty-send-key-sequencecommand

This command sends all keys you press to the terminal until you press C-g.

By default, it is bound to C-c C-q.

mistty-newlinecommand

This command sends a single newline as bracketed paste, meaning that the newline should be inserted as-is and not execute the current command.

By default, it is bound to S-<return>.

Navigating the scrollback zone

C-e C-e moves the point back inside the prompt. This is handled by the interactive function mistty-end-of-line-or-goto-cursor

M-x mistty-goto-cursor also moves the point back inside the prompt. You can bind it to a custom shortcut if you don’t like overloading C-e.

C-c C-p or M-x mistty-goto-previous-output goes to the beginning of the previous command output. This is useful to if the buffer has scrolled too far and you want to see it from the beginning.

C-c C-n or M-x mistty-goto-next-output does the reverse, that is, it goes to the next command output.

C-c C-o or M-x mistty-select-output selects the command output at or before point. With an argument, selects the Nth previous command output.

C-c C-r or M-x mistty-create-buffer-with-output creates a new buffer containing the command output at or before point. With an argument, creates a buffer containing the Nth previous command output.

M-x mistty-goto-previous-input goes to the beginning of the previous command input, that is, the previous prompt. While this is a way of going back the command you’ve previously input, it’s best to use the shell native command history, as discussed in Command History.

M-x mistty-goto-next-input goes to the next command input.

C-c C-l or M-x mistty-clear deletes the content of the buffer until the current prompt. With a numeric argument N, it deletes the content of the buffer until the Nth previous prompt.

Fullscreen Mode

MisTTY detects when a program, such as less or vi, requests full-screen mode. In response, it splits the MisTTY buffers in two:

The terminal buffer, which displays the program’s output and allows you to interact with it. It operates in term-mode.
The Scrollback Buffer, which contains the previous command lines along with their outputs.

To switch between these buffers, press C-c C-j or execute M-x mistty-toggle-buffers

When the full-screen program exits, the two buffers are merged back together. Please note that the output from the full-screen application is not available in the scrollback region.

Command History

MisTTY doesn’t track command history. It relies instead on being able to access the history of the different interactive command-line tools.

The command history available in most shells and command-line editing tools is available in MisTTY using the following shortcuts:

M-p moves up command history
M-n moves down command history
M-r triggers a backward search in command history (Backward Search)
M-. insert the last argument from command history

To get the same key bindings you’d get in a normal terminal, you can bind C-p, C-n, or C-r to mistty-send-key in the terminal zone of the MisTTY buffer. For example:

(keymap-set mistty-prompt-map "C-p" #'mistty-send-key)
(keymap-set mistty-prompt-map "C-n" #'mistty-send-key)
(keymap-set mistty-prompt-map "C-r" #'mistty-send-key)

Backward Search

Within various shells, pressing C-r or M-r activates a special backward search mode, where editing options are limited. MisTTY identifies this mode using the regular expressions set in M-x customize-option mistty-forbid-edit-regexps.

When this mode is active:

You can append or delete text but cannot modify it. Though yanking text and word deletion are still possible, most Emacs editing won’t work.
The modeline displays “FE:run” to indicate Forbid Edit mode.
Arrow keys are sent directly to the terminal, which is beneficial for shells like Fish that allow selection from multiple choices. To customize this functionality, adjust key bindings in mistty-forbid-edit-map, which extends mistty-prompt-map in this mode.
Pressing C-g sends a signal to the terminal and typically exits backward search mode without making a selection.

Completion-at-point

When in a MisTTY buffer, it’s best to rely on the completion or autosuggestions provided by the shell or other command-line tool currently running, as they’re more up-to-date and context-sensitive than what Emacs can provide.

However, some form of Emacs-based completion can still be useful from inside of a MisTTY buffer, to complete abbreviations, expand templates or add emojis.

The following completion packages are known to work with MisTTY out of the box, including auto-completion, if enabled:

Emacs builtin complete-in-region
corfu
company-mode

Emacs hippie-expand also works. That’s not completion, but it’s close.

Other packages might work or might be made to work with some efforts. Auto-completion is usually the main challenge, described in Auto-complete. Please file a bug (Reporting issues) if you encounter issues with other completion packages.

Autosuggestions

completion-at-point completes the text around the point. This is generally convenient, but gets confused by shell autosuggestions, available in Fish or ZSH.

What if you typed “com” and the shell helpfully suggests “completion”? The buffer would look like: “com<>pletion”, with <> representing the point. completion-at-point would then think you typed “completion” and not suggest anything else.

To avoid that problem MisTTY modifies the functions it finds in completion-at-point-functions so that they just won’t see anything after the point when in the terminal region. In the example above, they’d only complete “com”, not “completion”.

That is, completion-at-point in the MisTTY terminal region completes the text before the point.

If you don’t like that or don’t use a shell that supports autosuggestions, you can turn this off with M-x customize-option mistty-wrap-capf-functions

Template Expansion

Template expansion and other form of long-running editing command might be confused by the way MisTTY work in the terminal region. See Long-running commands for details.

The following template expansion packages are known to work with MisTTY out of the box, if enabled:

Emacs built-in tempo package
tempel
yasnippet

Other packages might work or might be made to work with some efforts. Please file a bug (Reporting issues) if you encounter issues with other packages.

Directory Tracking

If you’re using Bash or Fish version 4 or later, as a shell, you’ll discover that Emacs keeps track of the shell’s current directory, so commands like M-x find-file know where to start from.

If you’re using any other shell, you’ll need to configure it to tell Emacs about its current directory, as described in Directory Tracking for Fish and in Directory Tracking for Zsh.

Bash out-of-the-box directory tracking also doesn’t work in shells you start using ssh or docker. For that to work, the simplest solution is to start remote shells with TRAMP. (Remote Shells with TRAMP)

Remote Shells with TRAMP

If the default-directory that is current when a new MisTTY buffer is created contains a TRAMP path whose method supports it, MisTTY runs the shell with the method, user and host of that path.

Tip

C-u M-x mistty-create asks for a directory instead of using the default one. This makes it possible to open a remote shell on a host that no buffer is visiting. See Launching.

For this to work, MisTTY needs to know the shell executable to use on that host. The value of mistty-shell-command or explicit-shell-file-name is interpreted as a local file within that host, which might not always work.

To run different shells on different hosts, define different connection local profiles that set mistty-shell-command and bind them to the TRAMP host, machine or user you want, as shown in the example below. This is described in details in the Emacs Lisp manual, in the section Connection Local Variables.

Example:

(connection-local-set-profile-variables
 'profile-usr-local-fish
 '((mistty-shell-command . ("/usr/local/bin/fish" "-i"))))

(connection-local-set-profiles '(:machine "myhost.example")
 'profile-usr-local-fish)

By default, the name of TRAMP shells include the user and hostname, if different from the current one. If you don’t want that, configure it on M-x customize-option mistty-buffer-name.

Directory tracking and TRAMP

Directory tracking (Directory Tracking) normally just works in TRAMP shells started described in the previous section.

This isn’t necessarily true of shells started from a MisTTY buffers, by calling ssh, docker or sudo, but it is possible to make that work, as described below.

Tip

The simplest way to connect a host or docker instance you don’t want to configure is to just start it as described in Remote Shells with TRAMP and use Bash as your shell. Everything then just work out of the box, at least for Bash 4.4 and later. (Directory tracking in Bash)

If you haven’t already, configure your shell to tell Emacs about directory changes, even Bash. This is described in Directory Tracking for Bash, in Directory Tracking for Fish, and in Directory Tracking for Zsh.

Once this is done, the shell sends out file: URLs that include the host name. By default, MisTTY will then use that to set the default directory to remote file paths that include that hostname using the default TRAMP method. For example, given the file: URL file:/example.com/var/log reported by the shell, MisTTY will set the directory of its buffer to /-:example.com:/var/log.

If you always connect to hosts using SSH, this is likely all you need, if not, you can still make it work as follows:

If you’re using some other way of connecting to your host, configure it in M-x configure-option tramp-default-method. You can also configure that on a per-host basis using M-x configure-option tramp-default-method-alist
If you’re connecting to hosts in more diverse ways, you can configure the TRAMP path MisTTY should generate using M-x configure-option mistty-host-to-tramp-path-alist
If you want to configure the TRAMP path on the hosts, you can send it from the prompt as Emacs-specific \\032/...\\n code containing a TRAMP path instead of the standard file: URL recommended in Directory Tracking for Bash, in Directory Tracking for Fish, and in Directory Tracking for Zsh. Here’s an example of such a code for Bash that tells TRAMP to connect to the current docker instance:
```
if [ "$TERM" = "eterm-color" ]; then
    PS1='\032//docker:$HOSTNAME:/$PWD\n'$PS1
fi
```

That said, if you need more than just SSH to connect to other hosts, it might be overall just easier to start remote shells with TRAMP (Remote Shells with TRAMP) instead of the command line, because directory tracking just works in that case.

If everything fails, if TRAMP is causing you too much trouble and you just don’t want MisTTY to generate remote paths at all, unset the option M-x configure-option mistty-allow-tramp-paths.

Keybindings used by MisTTY

MisTTY relies on applications connected to the terminal to handle keybindings in a common way, that is:

Any printable character: Inserts the character at the cursor position.
DEL (ASCII 127): Deletes the preceding character.
C-k (ASCII 11): Deletes from the cursor to the end of the line.
C-e (ASCII 5): Moves the cursor to the end of the line.
C-a (ASCII 1): Moves the cursor to the beginning of the line.
ESC [ 200 ~ ... ESC [ 201 ~ (bracketed paste): Inserts characters verbatim, including tabs and newlines, allowing for multiline support.

These keybindings are supported by recent versions of bash, zsh, fish, Python, and IPython.

When interacting with applications that do not support some or all of these keybindings, operations may be limited. You will still be able to insert characters and, when supported, delete them using backspace or C-d. However, you may not have access to Emacs-style operations for moving the cursor or editing text.

It is important to note that in backward i-search mode within shells, only character insertion and deletion are supported. Thus, while most Emacs commands may not function, you can still use simple Emacs commands that insert text after the cursor, such as yank (with no special characters), or delete text before the cursor, such as backward-kill-word. For more details, see Backward Search

Supported OSC Control Sequences

OSC are optional “operating system command” control sequences that programs can use to communicate with the terminal and Emacs. MisTTY supports the following OSC control sequences:

OSC 0; <title> ST and OSC 2; <title> ST changes the window title. This sets the variable ansi-osc-window-title in the MisTTY buffer, which can then be referred to in frame-title-format to set the frame title dynamically.
OSC 7;file://<hostname>/<path> ST reports the shell’s current directory to Emacs. See Directory Tracking

OSC 8;;<url> ST <text> OSC 8;; ST makes text clickable.

Example:

printf '\e]8;;http://example.com\e\\This is a link\e]8;;\e\\\n'

OSC 10;? ST and OSC 11;? ST query the foreground or background color. The response is an hexadecimal 16 bit RGB value.

Example: Querying the background color in Bash:

$ read -t 0.1 -rs -d \\ -p $'\e]11;?\e\\' bg
$ echo "$bg" | strings
]11;rgb:1313/1c1c/2b2b

Example: A Zsh function that can figure out whether you have a light or dark background:

function bg_brightness {
    local bg
    if read -t 0.1 -rs -d \\ "?$(printf '\e]11;?\e\\')"  bg; then
        if [[ "$bg" =~ '11;rgb:([0-9a-f]{4})/([0-9a-f]{4})/([0-9a-f]{4})' ]]; then
            local r g b brightness
            typeset -i 10 r=16#${match[1]}
            typeset -i 10 g=16#${match[2]}
            typeset -i 10 b=16#${match[3]}
            (( brightness = ( 0.2126 * r + 0.7152 * g + 0.0722 * b ) * ( 256.0 / 0xffff ) ))
            if [[ $brightness -le 128 ]]; then
                echo dark
            else
                echo light
            fi
            return 0
        fi
    fi
    return 1
}

To extend the set of OSC codes supported by MisTTY, see OSC Sequences.