A modern, AI-powered Neovim IDE configuration that transforms your terminal into a comprehensive development environment.
Transform your coding experience with NairoVIM - a sophisticated Neovim configuration that combines the legendary efficiency of Vim with modern IDE features, AI assistance, and a beautifully integrated terminal workflow. Whether you're a seasoned developer or new to terminal-based editing, NairoVIM provides everything you need for productive development.
- ✨ Key Features
- 📋 Prerequisites
- 🚀 Quick Installation
- 🎯 Quick Start Guide
- ⌨️ Essential Keybindings
- 🤖 AI Assistance Setup
- 🎨 Post-Installation Setup
- 📸 Screenshots
- 🎨 Customization
- 🆘 Troubleshooting
- 📚 Documentation
- 🤝 Contributing
- 📄 License
- 🙏 Acknowledgments
- 🤖 AI-Powered Development - Integrated OpenCode, Avante AI, and GitHub Copilot support
- 🎨 Beautiful UI - Multiple themes with enhanced status bars and visual elements
- 🔍 Advanced Search - Telescope fuzzy finder with FZF and Ripgrep integration
- 📁 Smart File Management - Tree-style file explorer with git integration
- 🌳 Language Intelligence - LSP support for 20+ programming languages
- 🐛 Integrated Debugging - Debug Adapter Protocol with visual debugging
- 📊 Git Workflow - Embedded Lazygit with diff viewing and conflict resolution
- ⚡ Performance Optimized - Lazy-loaded plugins for fast startup (~40-120ms)
- 🛠️ Extensible - 70+ carefully selected plugins with modular architecture
- macOS or Linux (Windows WSL supported)
- Homebrew - Package manager (install here)
- Git - Version control system
- Ghostty Terminal - Modern terminal emulator (recommended, install here)
- Alternative: iTerm2, Terminal.app, or any terminal with 256-color support
- Nerd Font - For proper icon display (download here)
- Node.js - For additional LSP servers and tools
- Python 3 - For certain Neovim plugins
-
Clone the repository:
git clone https://github.com/yourusername/nairovim.git cd nairovim -
Run the installation script:
./install.sh
-
Install Ghostty terminal (recommended):
brew install --cask ghostty
-
Start your development environment:
# Using Ghostty (recommended) ghostty nvim # Or with tmux (optional) tmux nvim
That's it! The installation script will:
- ✅ Install Neovim and essential development tools
- ✅ Configure Ghostty with tmux-like keybindings
- ✅ Set up tmux (optional, for legacy workflows)
- ✅ Configure zsh with Oh My Zsh
- ✅ Install and configure 70+ Neovim plugins
- ✅ Set up development utilities (FZF, Ripgrep, Lazygit, etc.)
- ✅ Create backups of existing configurations
Manual Installation (click to expand)
-
Install Homebrew (if not already installed):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -
Install core dependencies:
brew install neovim fzf ripgrep bat lazygit brew install --cask ghostty # Recommended terminal -
Set up configuration files:
# Link dotfiles ln -sf "$(pwd)/ghostty_config" "$HOME/.config/ghostty/config" ln -sf "$(pwd)/.zshrc" "$HOME/.zshrc" # Link Neovim config ln -sf "$(pwd)/nvim" "$HOME/.config/nvim" # Optional: tmux (legacy support) ln -sf "$(pwd)/.tmux.conf" "$HOME/.tmux.conf" git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
-
Install Oh My Zsh:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
If you're new to NairoVIM, we highly recommend starting with the built-in interactive tutorial. It provides hands-on, step-by-step guidance for the essential features:
# From the dashboard (when you first open nvim)
Press 't' for Interactive Tutorial
# Or use the keybinding anytime
,tt # (comma + t + t)
# Or use the command
:TutorialThe tutorial covers:
Beginner Lessons (17 min):
- Lesson 1: File navigation basics (5 min)
- Lesson 2: Text editing fundamentals (5 min)
- Lesson 3: Search & find operations (7 min)
Advanced Lessons (33 min):
- Lesson 4: LSP & code intelligence (10 min)
- Lesson 5: AI-assisted coding (7 min)
- Lesson 6: Git workflow integration (8 min)
- Lesson 7: Power user tips (8 min)
Total time: ~50 minutes for complete mastery!
# Open Ghostty terminal (recommended)
ghostty
# Open Neovim
nvim
# Start interactive tutorial (first time users)
,tt
# Or jump right in:
# Find and open a file
<Ctrl-s>f
# Search for text across project
<Ctrl-s>s
# Open file explorer
<Ctrl-n>NairoVIM is optimized for Ghostty with built-in split and tab management:
# Splits (tmux-like bindings)
<Ctrl-b> - # Create horizontal split
<Ctrl-b> \ # Create vertical split
<Ctrl-b> h/j/k/l # Navigate between splits
# Tabs
<Ctrl-b> c # Create new tab
<Ctrl-b> n/p # Next/previous tab
<Ctrl-b> x # Close tab
# Zoom
<Ctrl-b> z # Toggle split zoomNote: tmux is still supported but considered a legacy option. Ghostty provides native split/tab management with better performance.
# Open integrated Lazygit
,G
# Use vim-style navigation: j/k to move, space to stage
# Make commits and push directly from Neovim# Toggle OpenCode terminal (recommended)
,ot
# Ask about current code
,oa
# Add file context and ask questions
,o+
,oAThe leader key is , by default. Here are the most commonly used keybindings:
| Keybinding | Description |
|---|---|
<C-S>f |
Find git files (Telescope) |
<C-S>s |
Live grep search across project |
<C-S>b |
Switch buffers |
<C-S>r |
Recent files |
<C-n> |
Toggle file explorer |
<C-F>f |
FZF git files (alternative) |
| Keybinding | Description |
|---|---|
gd |
Go to definition |
gi |
Go to implementation |
gR |
Find references |
K |
Hover documentation |
<leader>ca |
Code actions |
<leader>rn |
Rename symbol |
]e / [e |
Next/previous diagnostic |
| Keybinding | Description |
|---|---|
<leader>ot |
Toggle OpenCode terminal |
<leader>oa |
Ask about cursor/selection |
<leader>o+ |
Add buffer/selection to context |
<leader>oe |
Explain code at cursor |
<leader>on |
New AI session |
| Keybinding | Description |
|---|---|
<leader>G |
Open Lazygit |
]c / [c |
Next/previous git hunk |
<leader>hs |
Stage hunk |
<leader>hp |
Preview hunk |
<leader>hb |
Blame line |
| Keybinding | Description |
|---|---|
<leader>F |
Maximize current window |
<leader>s |
Find and replace (Scooter) |
<leader><CR> |
Clear search highlights |
jk |
Exit insert mode |
| Keybinding | Description |
|---|---|
<leader>tt |
Start/resume interactive tutorial |
<leader>tl |
List all tutorial lessons |
<leader>tr |
Restart current lesson |
<leader>tn |
Start next lesson |
📖 See complete keybinding reference: Check ARCHITECTURE.md for all 70+ keybindings.
OpenCode provides seamless AI assistance directly in your terminal with full context awareness.
-
Set your Anthropic API key:
# Add to ~/.zshrc or ~/.bashrc export ANTHROPIC_API_KEY="your-api-key-here" # Reload shell source ~/.zshrc
-
Get your API key from Anthropic Console
-
Start using OpenCode:
# In Neovim ,ot # Toggle OpenCode terminal
# Ask about current code
,oa
# Add file to context
,o+
# Ask general question with context
,oA
# Explain code at cursor
,oe
# Start new session
,onKey Features:
- ✅ Context-aware with multi-file support
- ✅ Session persistence
- ✅ Beautiful markdown rendering in terminal
- ✅ Fast & efficient
- ✅ Direct API calls (privacy-focused)
Cost: ~$0.01-$0.05 per query, ~$0.50-$2.00 daily for typical usage
📖 For alternative AI tools (Avante, Copilot): See ARCHITECTURE.md - AI Tools
NairoVIM includes a pre-configured Ghostty setup with:
- TokyoNight theme (auto-switching dark/light modes)
- tmux-like keybindings for splits and tabs
- Optimized font rendering
The installation script automatically links the config, but you can verify:
# Check Ghostty config location
cat ~/.config/ghostty/config
# Key features:
# - Ctrl+b prefix (tmux-style) for splits/tabs
# - TokyoNight theme with dark/light auto-switching
# - Font size 12 for optimal readabilityGhostty vs tmux:
- ✅ Ghostty: Native splits/tabs, better performance, modern GPU rendering
⚠️ tmux: Legacy option, session persistence, remote development
Recommendation: Use Ghostty for local development, tmux only for remote SSH sessions.
# Recommended: Hack Nerd Font
brew tap homebrew/cask-fonts
brew install --cask font-hack-nerd-fontGhostty is pre-configured to use Nerd Font-compatible rendering.
# In Neovim, open Mason
:Mason
# Install language servers for your languages:
# - TypeScript: typescript-language-server
# - Python: pyright
# - Rust: rust-analyzer
# - Go: gopls
# Navigate with j/k, press 'i' to installAdd to ~/.gitconfig:
[core]
editor = nvim
[merge]
tool = nvim
[mergetool "nvim"]
cmd = nvim -c "DiffviewOpen"
# In Neovim
:colorscheme <Tab>
# Available themes:
# - tokyonight-night (default dark)
# - tokyonight-day (light)
# - catppuccin
# - gruvbox
# - nightfoxOr use keybindings:
<leader>DD- Dark theme (tokyonight-night)<leader>LL- Light theme (tokyonight-day)
# Open plugin manager
:Lazy
# Common operations:
# - Update plugins: U
# - Install new: I
# - Clean unused: X
# - View logs: L
# Open LSP/tool manager
:MasonEdit the plugin file (e.g., lua/nairovim/plugins/plugin-name.lua):
return {
"plugin/name",
enabled = false, -- Add this line
}Plugins not loading:
:Lazy restore
:Lazy syncLSP not working:
:LspInfo
:Mason # Install language serversIcons not showing:
# Install Nerd Font and configure terminal to use it
brew install --cask font-hack-nerd-fontSlow startup:
# Profile plugins
:Lazy profile
# Disable unused plugins (see Customization above)📖 Comprehensive troubleshooting guide: See TROUBLESHOOTING.md
- ARCHITECTURE.md - Technical details, plugin ecosystem, complete keybindings
- TROUBLESHOOTING.md - Detailed issue resolution guide
- FAQ.md - Frequently asked questions
- CONTRIBUTING.md - Contribution guidelines
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
NairoVIM is built on the shoulders of giants. Special thanks to:
- The Neovim team for the amazing editor
- All plugin authors who make this configuration possible
- The open source community for continuous inspiration
.oPYo. 8 o 88 88 88
8 8 8 8 88 88 88
8 .oPYo. .oPYo. .oPYo8 o8P .oPYo. .oPYo. .oPYo. 88 88 88
8 oo 8 8 8 8 8 8 8 8 8 8 8 8 8 88 88 88
8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 `' `' `'
`YooP8 `YooP' `YooP' `YooP' 8 `YooP' `YooP8 `YooP' 88 88 88
:....8 :.....::.....::.....:::::..::.....::::....8 :.....:.........
:::::8 :::::::::::::::::::::::::::::::::::::::ooP'.::::::::::::::::
:::::..:::::::::::::::::::::::::::::::::::::::...::::::::::::::::::Ready to transform your coding experience? Get started now!