For Vim users who already know how to edit: one trained project loop for jump, files, run, grep, git, and active key help.
A long-term Vim efficiency kit: find, jump, run, grep, git, LSP, and self-documenting keys over SSH.
Install current main:
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bashCurrent main is preparing the 2.3.0 release. Use BETA.md for the
release-candidate checklist, rollback steps, and Space keymap test loop.
chopsticks is for experienced Vim users who want one stable, ergonomic working set they can train once and keep for years. It does not replace Vim's editing language; it standardizes the project loop around it.
Stock Vim is a great editor core, but it does not ship that complete project workflow. You still have to assemble fuzzy finding, project grep, git, LSP, diagnostics, formatters, runners, terminal behavior, and a keymap that will not collapse over SSH.
That assembly work is the pain chopsticks removes:
- Project motion is scattered. Files, buffers, grep, tags, marks, git, and diagnostics live behind unrelated commands unless you design a system.
- Plugin defaults fight muscle memory. chopsticks gives QWERTY users one
canonical Space layout and keeps native Vim/LSP habits where they matter:
gd,gr,K,Ctrl-h/j/k/l,<C-w>hjkl,cl,cc. - Remote editing is fragile. It is built to degrade on TTY, slow SSH, and headless machines instead of assuming a GUI desktop.
- Custom configs are hard to onboard.
:ChopsticksHelp,SPC ?,:ChopsticksTutor,:ChopsticksConfig, and:ChopsticksStatusmake the active keymap, full help, local preferences, and missing tools visible inside Vim.
You SSH into a server. You need to edit code. You want LSP, fuzzy find, git integration, format-on-save — not a 20-minute setup.
chopsticks gives you a production-ready Vim config in one command. Pure VimScript — no Node.js for the core. Degrades gracefully on TTY. Works the same on your MacBook and your headless Arch box.
23+ plugins depending on profile and opt-ins, LSP, linting, and a hand-built statusline. No bloat, no decorations, just tools.
| Feature | Description |
|---|---|
| LSP | completion, go-to-def, hover, rename, code actions — pure VimScript (vim-lsp) |
| Lint + format | ALE runs black, prettier, goimports, rustfmt on save |
| Fuzzy find | files, buffers, grep, tags, marks, commands — FZF |
| Git | status, diff, blame, commit, log, conflict markers — fugitive + gitgutter |
| Run file | SPC rr — auto-detects Python, Go, Rust, JS, C, Shell, and more |
| Markdown | quiet writing defaults, browser preview (,mp), table of contents (,mt) |
| Diagnostics | :ChopsticksStatus — see what's installed, what's missing, how to fix it |
| TTY-aware | degrades gracefully on SSH, console, slow links — never breaks |
These commands install current main. For the 2.3.0 release-candidate
checklist and rollback steps, use BETA.md.
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash -s -- --profile=minimal
curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash -s -- --dry-run --profile=fullOr manually:
git clone https://github.com/m1ngsama/chopsticks.git ~/.vim
cd ~/.vim && ./install.sh --profile=engineerSupports macOS (brew), Debian/Ubuntu (apt), Arch (pacman), Fedora (dnf).
Set CHOPSTICKS_DEST=/absolute/path before running get.sh to install
somewhere other than ~/.vim.
First launch installs plugins automatically (30-60s). Restart vim when done.
Use ./install.sh --dry-run --profile=full to inspect the resolved profile and
config path without changing files. Use ./install.sh --configure-only --profile=minimal to switch profiles without reinstalling plugins or tools.
Default profile: engineer. Interactive installs ask for this profile before
plugins are installed; --profile=minimal, --profile=engineer, or
--profile=full selects it without prompting. --yes keeps the existing local
profile or uses engineer.
" Put this in ${XDG_CONFIG_HOME:-~/.config}/chopsticks.vim.
let g:chopsticks_profile = 'engineer' " default: LSP, ALE, syntax extras
" let g:chopsticks_profile = 'minimal' " core navigation/editing/git/markdown
" let g:chopsticks_profile = 'full' " engineer + heavier Markdown feedback
let g:chopsticks_keymap_style = 'space' " default: Space leader grouped layout
" let g:chopsticks_keymap_style = 'classic' " optional legacy comma layout
let g:chopsticks_enable_jk_escape = 1 " optional: insert-mode jk exits insert
let g:chopsticks_enable_ctrl_s_save = 1 " optional: Ctrl-S saves
let g:chopsticks_enable_sudo_save_bang = 1 " optional: :w!! sudo save
let g:chopsticks_enable_completion_keymaps = 1 " optional: Tab/Enter completion
let g:chopsticks_enable_auto_pairs = 1 " optional: automatic pair insertion
let g:chopsticks_enable_terminal_keymaps = 1 " optional: terminal Esc/Ctrl navigation
let g:chopsticks_enable_tmux_navigator = 1 " optional: vim-tmux-navigator integration
let g:chopsticks_enable_exrc = 1 " optional: source project-local .vimrc/.exrc from CWD
let g:chopsticks_enable_reindent_file = 1 " optional: full-file reindent mapminimal avoids LSP, ALE, completion plugins, extra language syntax plugins,
Startify, UndoTree, and browser Markdown preview. full keeps those and opts
into Markdown lint, format, spell, conceal, Marksman, and LSP virtual text.
Project updates leave ~/.config/chopsticks.vim alone, so put local choices
there instead of editing the managed .vimrc. The SPC ? cheat sheet follows
the active profile and only shows keys for enabled features. Inside Vim, use
:ChopsticksConfig to edit that local file and :ChopsticksReload after
saving it.
Default layout: space, leader SPC, localleader ,.
This is the canonical layout for QWERTY keyboards with CapsLock mapped to
tap-Esc / hold-Ctrl. Escape and Ctrl stay at the system layer; Vim keeps the
native <C-w> window model as a fallback and standard LSP motions (gd,
gr, K).
Git push/pull are intentionally not bound to default hotkeys. Normal-mode s
is a screen-local EasyMotion jump; use cl for native s substitute and cc
for native S.
For learning the kit, use :ChopsticksTutor to train the core loop, SPC ?
for the active keymap, :ChopsticksHelp / :help chopsticks for full native
Vim help, :ChopsticksConfig for local preferences, and :ChopsticksStatus
for tool/LSP health.
QUICKSTART.md is the 5-minute path; this README is the full reference.
During release-candidate testing, :ChopsticksBeta opens the in-editor
checklist, :ChopsticksBetaLog opens editable local notes, and
:ChopsticksBetaSession appends a timestamped session block.
SPC SPC fuzzy find file gd go to definition
SPC / ripgrep project K hover docs
SPC e toggle file sidebar SPC rr run current file
Ctrl-h/l enter/leave sidebar Ctrl-hjkl windows
SPC gs git status SPC cf format
SPC w save SPC q quit
Esc exit insert mode SPC ? cheat sheet
:ChopsticksConfig local prefs :ChopsticksReload reload
Canonical Space keybindings
SPC SPC files | SPC , buffers | SPC / grep | SPC Tab alternate buffer | SPC e browser | SPC E browser (file dir)
SPC ff files | SPC fb buffers | SPC fg git files | SPC fr recent | SPC fl buffer lines | SPC fL all lines | SPC fc local config | SPC fv edit vimrc | SPC fV reload
SPC sg grep | SPC sw grep word | SPC s/ search history | SPC s: command history | SPC sm marks | SPC st tags | SPC sr replace word
gd def | gr refs | gI impl | gy type | K docs | [d ]d LSP diagnostics | [e ]e ALE errors | SPC ca action | SPC cr rename | SPC cf format | SPC co outline | SPC ci LSP status | SPC rr run
s+2ch jump | SPC S jump fallback | cl native s substitute | cc native S substitute | gc comment | cs"' surround | Alt+j/k move line | SPC U undo tree | SPC y clipboard | SPC = re-indent visual | SPC cW strip whitespace | [<Space> ]<Space> blank lines
SPC gs status | SPC gd diff | SPC gb blame | SPC gc commit | SPC gl log graph | SPC gC FZF commits | SPC gB buffer commits | ]x [x conflict
Ctrl-h/j/k/l windows | <C-w>h/j/k/l native fallback | SPC z maximize | SPC bp SPC bn buffers | SPC bd close buffer | SPC bo close other buffers | SPC tt SPC th terminal | ]q [q quickfix | SPC xq SPC xQ open/close quickfix | SPC xl SPC xL open/close loclist
,mp preview in browser | ,mt table of contents
F2 paste | F3 line numbers | F4 relative numbers | F6 invisible chars | SPC us spell check | SPC uf format on save
SPC w save | SPC W save all | SPC q quit | :x / ZZ save and quit | SPC fc local config | SPC fV reload | SPC ? cheat sheet | :ChopsticksHelp full help | :ChopsticksTutor practice | :ChopsticksStatus diagnostics
Legacy classic keybindings
,ff find | ,b buffers | ,rg grep | ,rG grep word | ,fh recent | ,fl lines | ,e browser | ,E browser (file dir) | ,, last file
,dd def | ,dt type | ,di impl | ,dr refs | ,dk docs | ,dp ,dn diagnostics | [e ]e ALE errors | ,rn rename | ,ca action | ,o outline | ,cr run
,S+2ch jump | gc comment | cs"' surround | Alt+j/k move line | ,u undo tree | ,y clipboard | ,* replace word | ,F re-indent (v) | ,W strip whitespace | [<Space> ]<Space> blank lines
,gs status | ,gd diff | ,gb blame | ,gc commit | ,gL log graph | ,gC FZF commits | ,gB buffer commits | ]x [x conflict
Ctrl-h/j/k/l windows | <C-w>h/j/k/l native fallback | ,z maximize | ,h ,l buffers | ,bd close buffer | ,= ,- resize | ,tv ,th terminal
,mp preview in browser | ,mt table of contents
F2 paste | F3 line numbers | F4 relative numbers | F6 invisible chars | ,ss spell check | ,af format on save
,cp copy full path | ,cf copy filename | ,ec local config | ,ev edit vimrc | ,sv reload | ,wa save all | :ChopsticksStatus diagnostics
:LspInstallServer " auto-detects filetype
:LspStatus " check what's running
:ChopsticksStatus " see all tools + LSP + linters at a glancepylsp, gopls, rust-analyzer, clangd, sqls — no Node.js. JS/TS servers need Node.
Markdown LSP (marksman) is opt-in so prose buffers stay quiet by default.
ALE and vim-lsp coexist cleanly (ale_disable_lsp=1). ALE handles linting + formatting. vim-lsp handles everything else.
Markdown opens in writing mode: wrapped text, no spell noise, no concealed syntax, no sign column, no real-time markdownlint, and no Marksman diagnostics. The explicit commands still work:
,mp " preview in browser
,mt " table of contentsOpt into heavier Markdown tooling from your own vimrc before loading chopsticks:
let g:chopsticks_markdown_lint = 1
let g:chopsticks_markdown_format_on_save = 1
let g:chopsticks_markdown_lsp = 1
let g:chopsticks_markdown_spell = 1
let g:chopsticks_markdown_conceal = 1
let g:previm_enable_realtime = 1For Markdown LSP, install or select marksman first.
~/.vim/
├── .vimrc thin loader
├── doc/
│ └── chopsticks.txt :help chopsticks
└── modules/
├── env.vim TTY detection, truecolor, skip built-in plugins
├── plugins.vim vim-plug + profile/option-driven plugins
├── core.vim settings, keymaps, performance
├── ui.vim solarized, statusline, startify
├── editing.vim easymotion, yank highlight, blank lines
├── navigation.vim fzf, netrw sidebar, windows, terminal
├── lsp.vim vim-lsp, asyncomplete
├── lint.vim ale, format-on-save
├── git.vim fugitive, gitgutter, conflict nav
├── languages.vim vim-go, markdown, filetype settings
├── buffers.vim buffer commands
├── utilities.vim config, reload, trim, clipboard helpers
├── files.vim auto mkdir, large-file protection
├── runner.vim run current file
├── quickfix.vim quickfix and location-list helpers
├── status.vim :ChopsticksStatus diagnostics
├── cheatsheet.vim SPC ? and :ChopsticksCheatSheet
├── tutor.vim :ChopsticksTutor guided practice
├── beta.vim :ChopsticksBeta release checklist
├── help.vim :ChopsticksHelp native Vim help
└── tools.vim compatibility placeholder
Each module is self-contained. Comment out one line in .vimrc to disable it. Add your own with call s:load('mine').
| Metric | Value |
|---|---|
| Lazy-loaded | 7 plugins (on command or filetype) |
| Built-in plugins skipped | 12 (gzip, tar, zip, vimball, logiPat, etc.) |
| Large file threshold | 10MB (auto-disables syntax + undo) |
| TTY large file | 500KB (syntax disabled) |
| Problem | Fix |
|---|---|
| Plugins not loading | :PlugInstall then :PlugUpdate |
| LSP not starting | :LspInstallServer for current filetype |
| Colors wrong | export COLORTERM=truecolor in shell rc |
Optional Ctrl+s freezes |
stty -ixon in shell rc |
| Everything slow | Large file? Auto-disabled >10MB |
| What's installed? | :ChopsticksStatus shows tools, LSP, linters |
For deeper checks, start with :ChopsticksStatus, SPC ?,
:ChopsticksTutor, :ChopsticksHelp, :ChopsticksConfig, and
QUICKSTART.md.
See CONTRIBUTING.md. The two rules that matter: no Node.js in the Vim runtime, and don't regress startup time.
Regenerate the README demo after changing public keybindings:
vhs .github/demo.tapeThe tape uses .github/demo-project and forces the current repository .vimrc,
so the GIF should show the same keymap the code actually ships.