🐱 meowvim

The purr-fect Neovim configuration for a cozy coding session. May or may not increase your productivity by a feline factor.

Overview • See It in Action • Key Features • Installation • Quick Start • Documentation • Customization • Troubleshooting • Contributing

---

🎯 Overview

meowvim is a fast, well-configured Neovim setup for the project meow ecosystem. It bundles curated plugins, sensible defaults, and playful touches so you can start coding immediately.

Who Is This For?

• Polyglot developers who need LSP, formatting, debugging, and testing
• Terminal users who want speed without sacrificing polish
• Project meow users who need consistent setup across macOS and Linux
• Automation fans who value lazy-loading, sessions, and keymap discovery

✨ Key Features

🎨 Interface & UX

• 6 colorschemes with 30+ variants: Catppuccin, TokyoNight, Rose Pine, Gruvbox, Nord, Kanagawa
• Transparency from 0-100% opacity
• Theme picker with live preview (:ColorschemeSelect or <leader>ok)
• noice.nvim message center and command palette
• Smooth folds, indent guides, persistent layout with auto-reload

🧠 Language Support

• LSP servers with diagnostics, actions, and symbol navigation
• Treesitter syntax highlighting and structural selection
• Completion with hjkl navigation (<C-j/k/l>) and GitHub Copilot (<C-y/g/n/p>)

🚀 Navigation & Productivity

• Flash motion (<leader><leader>) and Snacks finders for files, buffers, commands
• LazyGit (<leader>gg)
• Bookmarks for quick navigation (<leader>mm, <leader>mi)
• Code screenshots with syntax highlighting (<leader>cs)
• Auto buffer cleanup (configurable threshold)
• Sessions with per-branch support and project switching
• TODO tracking, search & replace, git workflows via Diffview and Gitsigns

🐾 Project Meow Features

• Config system with Lua tables, auto-reload, project settings
• Developer tools: conflict detection, profiling, startup tracking
• Automation: update-meowvim.sh with backup/rollback, test suite
• CI/CD with lint and multi-platform tests
• Mason-managed tools with auto PATH setup
• Overseer tasks, Neotest runners, DAP for Go, TypeScript, Python, more

📦 Installation

⚙️ Prerequisites

Type	Requirements
Required	Neovim ≥ 0.11, Git, true-color terminal
Recommended	Node.js ≥ 18, Python ≥ 3.8, Go ≥ 1.19, ripgrep, fd, fzf, Nerd Font
Optional	GitHub Copilot

⚡ Quick Install

# Backup existing config
mv ~/.config/nvim ~/.config/nvim.backup

# Clone meowvim
git clone https://github.com/retran/meowvim.git ~/.config/nvim

# Start Neovim
nvim

Plugins install automatically on first launch via lazy.nvim.

🐾 Install with project meow

git clone https://github.com/retran/meow.git ~/.meow
cd ~/.meow
git submodule update --init
./bin/meowctl install personal

The meow automation links meowvim with your dotfiles.

🔧 Staying Updated

# Automated update with backup/rollback
./bin/update-meowvim.sh

# Or manually inside Neovim
:Lazy sync
:MasonToolsUpdate

# Check health after updates
:checkhealth meowvim

🚀 Quick Start

1. Launch — first run installs plugins and bootstraps LSP servers
2. Configure — edit ~/.config/meowvim/config.lua (theme, transparency, features)
3. Keymaps — press <leader>hk for interactive search or see Quick Reference
4. Language tools — open Mason (<leader>Tm) to install LSP, formatters, debuggers
5. Navigate — <leader><leader> Flash jumps, <leader>ff file search, <leader>gg LazyGit, F2 terminal
6. Copilot (optional) — authenticate via :Copilot auth

📖 Documentation

The full documentation lives in the docs/ den:

• 01 – Installation & Upgrade Guide
• 02 – Configuration & Personalization
• 03 – Daily Workflows & Recipes
• Keymaps Reference & Quick Reference Card
• Troubleshooting & Health Checks

Each guide follows the meowg1k documentation structure so you can prowl between tools without context switching.

🧩 Customization

Customize meowvim through simple Lua tables:

• User config: Edit ~/.config/meowvim/config.lua - plain Lua table
• Project settings: Create ~/.config/meowvim/projects.lua for project overrides
• Commands: :MeowvimConfig, :MeowvimConfigReload, :MeowvimConfigShow
• Theme picker: :ColorschemeSelect or <leader>ok for live preview
• Options: lua/config/options.lua - Neovim settings
• Keymaps: lua/config/keymaps.lua - discoverable with which-key
• Plugins: lua/plugins/*.lua - one file per plugin

See Configuration Guide for details.

🛠️ Troubleshooting & Support

• Run :checkhealth meowvim for comprehensive environment diagnostics
• Use developer tools: :KeymapConflicts, :MeowvimProfile, :StartupTrends
• Run test suite: ./bin/test-config.sh to verify configuration integrity
• Visit Troubleshooting for common fixes, performance tuning, and LSP tips
• Enable verbose logging with :messages and review ~/.local/state/nvim/log if the cats get grumpy

🤝 Contributing

We welcome issues, feature ideas, and pull requests. Please:

1. Search existing issues to avoid duplicates.
2. Provide repro steps or screenshots where helpful.
3. Keep the cat puns tasteful and the Lua tidy.

📄 License

This project is released under the MIT License.

---

Made with ❤️ by Andrew Vasilyev and feline assistants Sonya Blade, Mila, and Marcus Fenix

Happy coding with project meow! 🐱

⭐ Star us on GitHub • 🐛 Report Bug • 💡 Request Feature • 🔀 Contribute