vamp/README.md

vamp

A modal Rust editor with a replaceable frontend and subprocess-isolated Ruby plugins.

Run

Requires current stable Rust and an interactive terminal. Ruby 2.6+ with its standard-library JSON support is required only for configuration/plugins; no Ruby gems are needed to run vamp itself.

cargo run -- --no-config notes.txt
cargo run -- --config examples/config.rb notes.txt

Without a file, vamp opens an unnamed buffer. A nonexistent file opens an empty buffer. cargo run -- --help lists the command-line options.

Getting started

Vamp starts in Normal mode. Press i, type text, then Esc to return to Normal. Type :save (alias :w) and Enter to save, or :save path to name an unnamed buffer. Type :quit (alias :q) and Enter to quit; it refuses unsaved changes in any open buffer. :force_quit (alias :q!) explicitly discards changes and quits.

Task	Default keys
Move in Normal	h/j/k/l or arrows; w/b/e for words
First/last line in Normal or Visual	gt / gb, at first nonblank; Visual extends the selection
Enter/leave Insert	i / Esc
Manual LSP completion in Insert	Ctrl+n starts/cycles next; Ctrl+j/k cycles next/previous, replacing text live
Edit completion snippet arguments	Type to replace the highlighted argument; Tab / Shift+Tab moves next/previous
Save in Normal	Space then w, or :w then Enter
Undo/redo in Normal	u / U (Shift+u)
Split panes in Normal	_ above/below; | left/right; Option/Alt+h/j/k/l changes focus
Close a pane	:pane.close; :pane.force_close explicitly discards exclusively displayed unsaved edits
Open/switch tabs in Normal	:tab.new opens the current buffer; Ctrl+Option/Alt+h/l switches previous/next
Close a tab	:tab.close; :tab.force_close explicitly discards exclusively displayed unsaved edits
Delete/change whole lines in Normal	dd / cc; leading counts work (3dd, 2cc)
Search in Normal	/, type a literal query, Enter; n/N for next/previous
Select/copy/cut	v characterwise or V whole rows, move to extend, then y/d in Visual
Paste in Normal	p/P after/before the caret or row for linewise fragments; system clipboard by default
Paste over selected text	p / P in Visual replaces every selection, preserving the clipboard
Command palette	Ctrl+p; type to filter, arrows select, Enter accepts, Esc cancels
Buffer picker in Normal	Space then b l or :buffers; type to search, arrows select, Enter switches, Esc cancels
Floating/docked explorer in Normal or Visual	Space then o / Space then e
Repository diff in Normal	:diff; choose Before then After, Tab changes category, type to search; Esc closes the selector; Working or checkout-matched pinned After is editable; :diff.close exits the comparison
Diff layout in Normal	Space then v cycles split/unified; Space then s flips left/right vs above/below split

Space is the default leader: press its suffix keys in order, not simultaneously. The editing guide contains the complete key table and behavior reference.

Configuration

By default, vamp loads $XDG_CONFIG_HOME/vamp/config.rb, or ~/.config/vamp/config.rb when that environment variable is unset. --config path selects a file explicitly; --no-config bypasses Ruby entirely and uses defaults.

Start with examples/config.rb. The configuration reference covers preferences, bindings, and native LSP setup. Language servers are disabled by default; install a trusted server and explicitly enable it.

Ruby configuration and plugins run with your account's filesystem/process permissions. Subprocess isolation is not a security sandbox; load only trusted scripts.

Current limits

• Terminal frontend only; no graphical frontend.
• Modal editing, not full Vim compatibility: characterwise and linewise Visual selections and counted dd/cc, but no block selection, named registers, or general operator–motion grammar. Search is literal, case-sensitive, and single-line.
• Native opt-in LSP supports diagnostics, go-to-definition, plain-text hover, manual primary-caret completion with snippet arguments, and automatic semantic highlighting—not rename, formatting, or code actions. Completion has no automatic popup or acceptance step; other carets are preserved and translated through the chosen edits. Snippet regex transforms and unresolved variables without defaults are omitted.
• System clipboard access supports macOS and Linux. Separate clipboard mode keeps internal editing available on unsupported/headless environments.

Performance and subprocess limits are documented in development.

Documentation

Guide	Contents
Editing	Keys, motions/counts, selections, repeat, clipboard, search, buffers, explorer, palette, syntax highlighting
Configuration	Ruby startup, preferences, action/mode reference, key notation, leader/list/tree bindings, native LSP
Plugins	Ruby API, capabilities, effects, asynchronous callbacks, isolation, messaging protocol
Architecture	Module ownership, session/frontend contracts, terminal lifecycle, syntax caches, native workers
Development	Verification commands, test organization, performance and process limits
Project context	Terminology and configuration-interface conventions