Skip to content

Home

Jump to bottom
CtrlUserKnown edited this page Jul 30, 2026 · 2 revisions

Welcome to the ctrlvim Wiki

This wiki documents ctrlvim — a modal text editor built from scratch in Rust, reimplementing Neovim's editing model rather than embedding or forking its C codebase. cvi is its terminal UI, built on Ratatui.

Early-stage but functional. 16 crates, strict dependency direction (types → text → options → editor → vimscript → api → lua → core → tui), no global mutable state.

Why

Neovim is incredible, but its C codebase is a mountain of complexity. ctrlvim reimagines the core in memory-safe Rust, keeping what makes Vim great (modal editing, extensibility, terminal-native feel) while making the internals approachable and hackable — Rust plugins as first-class as Lua ones, eventually.

Core Features

  • Modal editing — Normal/Insert/Visual/Command-line, with motions, operators, text objects, and composable counts (2d3w).
  • TOML configuration — ~/.config/ctrlvim/config.toml for options, per-mode keymaps, autocommands, user commands, and plugins. See docs/config.example.toml.
  • A real mapping layer — every chord (<C-x>, <A-x>, <C-S-x>, arrows, F-keys, <S-Tab>) bindable in Normal, Insert and Visual mode, with 'timeoutlen'-correct chord resolution and a which-key popup.
  • A from-scratch Vim regex engine — backreferences, lookaround, atomic groups, \zs/\ze, non-greedy repeats, all four magic levels — not translated onto a general-purpose regex crate.
  • Lua plugins — vim.api.*, vim.fn.*, vim.keymap, vim.treesitter, via mlua.
  • msgpack-RPC server — an external client can attach over a Unix socket and drive the editor through the same API surface Lua uses.
  • Tree-sitter syntax highlighting, an undo tree (g-/g+), registers, window splits, quickfix (:vimgrep/:make/:grep), project-wide find & replace, folds, tags (ctags).
  • Inline AI suggestions — Copilot-style ghost text from CodeGemma-2B running locally (candle) — no API key, nothing leaving the machine. See docs/ai.md.
  • Session persistence — reopens your tabs, cursor position, and unsaved edits after a crash or an accidental close.
  • Pinned files, macros, marks & jumps, Nerd Font file icons, a TUI dashboard with file browser, plugin manager, and floating overlays.

Full feature list and keybinding philosophy: repo README.

Install

curl -fsSL https://ctrluserknown.github.io/ctrlvim/install.sh | sh

There are no prebuilt release binaries yet, so this always builds from source (Rust 1.80+ and a C compiler — Lua 5.4 and tree-sitter are vendored). It's a plain POSIX shell script: clones the repo into ~/.cache/ctrlvim/src (or updates an existing clone), runs make install PREFIX=~/.local, and adds ~/.local/bin to your shell's PATH if it isn't there already. No root, ever, on its own initiative — for a system-wide install to /usr/local, run it as root yourself.

Prefer to see it first, or want the macOS universal-binary / staged-install (DESTDIR=) paths?

git clone https://github.com/CtrlUserKnown/ctrlvim.git
cd ctrlvim
sudo make install          # or: make install PREFIX=~/.local
make user-config            # seed ~/.config/ctrlvim/config.toml

make help lists every target, including make macos (universal arm64 + x86_64, ad-hoc signed) and make install DESTDIR=... for packaging. A dedicated CI workflow (.github/workflows/install.yml) exercises every one of these paths — root install, PREFIX=, DESTDIR=, user-config — on Linux and macOS on every change to the Makefile or workspace manifest.

Or just run it from a checkout without installing anything:

cargo run -p ctrlvim           # launch the editor
cargo test --workspace         # run the test suite

Architecture

module role
ctrlvim-types / ctrlvim-text Rope-backed buffer text, the shared value types
ctrlvim-options The three-tier option store (global / buffer / window)
ctrlvim-editor The Session: modes, motions, operators, marks, folds, quickfix, ex-commands
ctrlvim-vimscript Tree-walking Vimscript interpreter
ctrlvim-api / ctrlvim-api-macro The vim.* surface Lua (and RPC) calls into
ctrlvim-lua mlua-based Lua 5.4 runtime and bridges
ctrlvim-regex The from-scratch Vim regex engine
ctrlvim-treesitter Syntax-aware parsing and highlighting
ctrlvim-async Tokio event loop: timers, job control, msgpack-RPC
ctrlvim-tools The Mason-equivalent tool registry/installer for LSP servers, formatters, linters
ctrlvim-markdown Live in-buffer markdown rendering
ctrlvim-ai The local inline-suggestion backend (CodeGemma-2B on candle)
ctrlvim-core The Ctrlvim engine facade tying the above together
ctrlvim-tui The Ratatui frontend (binary: cvi) — dashboard, file editor, overlays

The dashboard's real data (git status, recent files, LSP detection, project stats) is gathered live from the project the editor is launched in — see crates/ctrlvim-tui/src/data.rs.

Roadmap notes

In-repo design docs for larger, still-in-progress efforts live in wikis/ in the repo itself (not this GitHub wiki) — e.g. lsp-mason-plan.md for the real LSP client, plugin-components-plan.md for the Rust plugin-component idea.

Quick Links

Created by CtrlUserKnown

Clone this wiki locally