Documentation

Complete reference for CharVim, a custom Neovim 0.12+ configuration managed by lazy.nvim. The entry point is nvim/init.lua and all modules live in nvim/lua/.

Installation

Run the install script. It auto-detects your OS and installs missing system dependencies before symlinking the config into ~/.config/nvim.

Supported package managers:

Manual install

1. Back up your existing config: mv ~/.config/nvim ~/.config/nvim.bak
2. Clone the repository: git clone https://github.com/CrtlUserKnown/Charvim.git ~/.config/nvim
3. Launch Neovim: nvim

Plugins install automatically via lazy.nvim on first launch.

Requirements

• Neovim 0.12+
• Git
• A Nerd Font for icons
• ripgrep for Telescope live grep and Find and Replace
• fd for Telescope file finding
• python3 for DAP Python support
• make for building avante.nvim
• node for Mason-managed LSP servers
• ANTHROPIC_API_KEY (optional) for AI features via avante.nvim

How Vim Works

Vim (and Neovim) is a modal editor. Keys do different things depending on the active mode. Press Esc to return to Normal mode from anywhere.

Leader Keys

Leader key timeout: 500 ms.

General

Navigation

Line Manipulation

File Explorer

Telescope

Hidden files are shown by default. .git/ directories are always ignored.

Harpoon 2

Multi-Cursor

In multi-cursor mode, entering Insert types at all cursor positions simultaneously.

Find & Replace / Rename

Panel navigation:

When the find term matches an identifier with an active LSP client, Y uses LSP rename instead of regex substitution.

LSP

Configured LSP Servers

Debugging (DAP)

The DAP UI opens automatically when a session starts and closes when it ends.

AI (avante.nvim)

Requires ANTHROPIC_API_KEY set in a .env file at the repo root. The file is auto-loaded on startup.

Themes

Available theme names: Auto, Knew-pines, Noir-cat, Tokyo Night, Catppuccin, Gruvbox, Habamax. Selection persists to ~/.local/share/nvim/charvim_theme.

UI Plugins

• noice.nvim: Replaces the command line with a centered popup.
• alpha-nvim: Dashboard with ASCII art logo and a two-column quick-access grid.
• which-key.nvim: Displays available keybindings in a popup using the modern preset.

Navigation and File Management

• telescope.nvim and telescope-file-browser.nvim: Fuzzy finder and file browser that replaces netrw. Shows hidden files by default.
• project.nvim: Project detection and management via Telescope.
• harpoon (v2): Quick file bookmarking and navigation.
• vim-tmux-navigator: Seamless navigation between Neovim splits and tmux panes.

Editing Tools

• nvim-surround: Add, change, and delete surrounding pairs.
• multicursor (custom): Native multi-cursor implementation.
• autoclose (custom): Auto-closes brackets, quotes, and backticks.
• rename-config (custom): Find and Replace panel backed by rg.
• save-popup (custom): Context-aware save options via leaderW.

LSP and Diagnostics

• mason.nvim: Installs and manages LSP servers, linters, and DAP adapters.
• LSP servers registered directly with vim.lsp.config() and vim.lsp.enable().
• Inlay hints enabled by default where supported. Toggle with leaderih.
• Diagnostic noise from ltex (sentence and paragraph length) is filtered globally.

Completion

• nvim-cmp: Completion engine with LSP and buffer sources.
• LuaSnip: Snippet engine.

Linting

nvim-lint runs automatically on BufWritePost and BufEnter.

Debugging

• nvim-dap and nvim-dap-ui: Debug Adapter Protocol with an auto-managed UI.
• mason-nvim-dap: Ensures DAP adapters are installed via Mason.

Syntax and Parsing

• nvim-treesitter: Syntax highlighting, indentation, and incremental selection.
• nvim-ts-autotag: Auto-closes and auto-renames HTML and JSX tags.
• typst-preview.nvim: Live browser preview for Typst files via :TP, :TS, :TU.

Editor Options

Statusline

Custom-built statusline (no plugin). Displays:

• Left: Mode indicator letter + filename + modified flag [+]
• Right: Save flash (written, shown 2s after save) + mode name + percentage + column

Filetype-Specific Settings

COBOL

Tab width: 8 spaces. Colour columns at 7 and 73. Text width: 72.

Crystal

.cr files fall back to Ruby syntax highlighting.

Java

Build system auto-detected (Maven / Gradle / Ant). JDTLS workspaces stored in ~/.cache/nvim/jdtls/<project_name>.

Kotlin

Build system auto-detected (Gradle or Maven).

User Customization

Two git-ignored files allow personal settings that survive git pull updates. Auto-created with template comments on first startup.

nvim/lua/user.lua

Loaded last, after all CharVim config. Add keymaps, options, autocommands, or override any default:

-- nvim/lua/user.lua
vim.opt.wrap = true
vim.keymap.set('n', '<leader>x', ':!echo hello<CR>', { desc = 'My command' })

nvim/lua/user-plugins.lua

Return a lazy.nvim spec list to add personal plugins:

-- nvim/lua/user-plugins.lua
return {
    { 'folke/zen-mode.nvim', opts = {} },
}

Update Checker

CharVim checks for new GitHub releases on startup. A Telescope popup appears when an update is found.

Settings persist to ~/.local/share/nvim/charvim_settings.json.

Uninstall / Reinstall

Open from the dashboard (u) or with :CharvimUninstall.

Custom Commands

Dashboard

Open with :AlphaRedraw or leaderd.