vterm-editor.el/README.md

vterm-editor.el

Compose text in a full Emacs buffer and send it to vterm with a single keystroke.

Overview

When working inside a vterm terminal, editing multi-line text can be awkward: you lose access to Emacs keybindings, navigation, and editing commands. vterm-editor solves this by opening a temporary buffer where you can write comfortably using all of Emacs, then send the result back to vterm.

Without vterm-editor

You type directly in the terminal, limited to basic line editing.

With vterm-editor

┌─────────────────────────────────────────────────┐
│ Edit, then C-c C-c to send or C-c C-k to cancel│  ← header line
├─────────────────────────────────────────────────┤
│                                                 │
│  Write freely here with full Emacs power:       │
│  - Multiple cursors, search & replace, etc.     │
│  - Spell checking, auto-complete, snippets      │
│  - Any major/minor mode you want                │
│                                                 │
└─────────────────────────────────────────────────┘
        │ C-c C-c                │ C-c C-k
        ▼                        ▼
  Text sent to vterm        Buffer discarded

Features

• Full Emacs editing: Write in a regular buffer with all your keybindings and modes available
• Bracketed paste: Sends text using vterm's bracketed paste mode, safe for multi-line content
• Simple workflow: C-c C-c to send, C-c C-k to cancel
• Clean UI: Header line shows available actions, no clutter in the buffer
• Lightweight: Less than 80 lines of code

Installation

Using use-package (Emacs 29+)

(use-package vterm-editor
  :ensure t
  :vc (:url "https://git.andros.dev/andros/vterm-editor.el"))

Or from a local path:

(use-package vterm-editor
  :load-path "~/path/to/vterm-editor")

Manual installation

1. Download vterm-editor.el
2. Place it in your Emacs load path
3. Add to your init file:

(require 'vterm-editor)

With a keybinding in vterm

(use-package vterm-editor
  :after vterm
  :bind (:map vterm-mode-map
         ("C-c e" . vterm-editor-open)))

Usage

From any vterm buffer, run:

M-x vterm-editor-open

A new buffer *vterm-editor* opens in text-mode with vterm-editor-mode enabled. Write your text, then:

• C-c C-c: Send the text to the original vterm buffer and close the editor
• C-c C-k: Discard the text and close the editor without sending anything

The editor buffer is killed after either action, and focus returns to vterm.

How it works

1. vterm-editor-open saves a reference to the current vterm buffer
2. A temporary *vterm-editor* buffer opens via pop-to-buffer
3. On C-c C-c, the buffer content is sent using vterm-send-string with the paste-p flag enabled (bracketed paste mode), which wraps the text in terminal escape sequences (\e[200~...\e[201~) so the shell treats it as pasted content rather than executed commands
4. quit-window kills the editor buffer and restores the previous window layout

Requirements

• Emacs 25.1 or higher
• emacs-libvterm (vterm)

Contributing

Contributions are welcome! Please see the contribution guidelines for instructions on how to submit issues or pull requests.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.