Agentic Neovim

Modular Neovim configuration system with dual plugin support: Lua-based plugins and native Zig-based CLI tools.

Quick Start

# Clone the repository
git clone https://github.com/yourusername/naravisuals-agentic-nvim ~/.config/nvim

# Or use the symlink script
./handle-symlink-integration.sh

Architecture

This project uses a dual-plugin architecture:

• Lua Plugins: Traditional Neovim plugins written in Lua
• Zig Plugins: Native CLI tools written in Zig (first-class citizens)

Zig plugins are the primary choice, with Lua plugins as fallback when native tools are unavailable.

Config Profiles

Profile	Description	Best For
minimal	Bare essentials	Fast startup, remote servers
balanced	Middle ground	Most users, daily driving
ide	Full-featured	Complete IDE experience
performance	Speed-optimized	Old hardware, large codebases
tpope-classic	Classic vim	Vim purists

Usage

Option 1: Config Picker (recommended)

# Symlink to init.lua
./handle-symlink-integration.sh  # select 'p' for picker

# Pick a config at runtime:
NVIM_CONFIG=balanced nvim
NVIM_CONFIG=ide nvim

Option 2: Direct Config

# Symlink directly to a config
./handle-symlink-integration.sh  # select config number

# Or manually:
ln -s /path/to/project/options/plugins/profiles.lua ~/.config/nvim/init.lua

Make it permanent:

echo 'export NVIM_CONFIG=balanced' >> ~/.bashrc  # or ~/.zshrc

Key Bindings

Leader Key: <Space>

Key	Action
<leader>e	Open oil.nvim file explorer
<leader>ff	Find files (Telescope)
<leader>fg	Live grep (Telescope)
<leader>fb	Buffers (Telescope)
<leader>fr	Recent files
gd	Go to definition
gr	Find references
K	Hover documentation
[d / ]d	Previous/Next diagnostic
gc	Toggle comment

Bookmark Keybindings (when enabled)

Key	Action
ma	Add bookmark at current line
md	Remove bookmark
ml	List bookmarks
ms	Search bookmarks
mj	Jump to bookmark

Installation

Option 1: Direct symlink (recommended)

./handle-symlink-integration.sh

Option 2: Manual

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

# Clone this repo
git clone https://github.com/yourusername/naravisuals-agentic-nvim ~/.config/nvim

# Start Neovim
nvim

Structure

.
├── init.lua                    # Entry point - loads selected config
├── options/
│   ├── plugins.lua            # Unified plugin interface
│   ├── plugins/              # Plugin profiles
│   │   ├── init.lua         # Unified entry point
│   │   └── profiles.lua     # All config profiles
│   ├── lua-plugins/         # Lua-based plugins
│   │   ├── init.lua
│   │   ├── profiles.lua
│   │   ├── bootstrap.lua
│   │   ├── config.lua
│   │   ├── keymaps.lua
│   │   ├── colorscheme.lua
│   │   ├── ui.lua
│   │   ├── editor.lua
│   │   ├── lsp.lua
│   │   ├── treesitter.lua
│   │   ├── telescope.lua
│   │   ├── git.lua
│   │   ├── bookmark.lua
│   │   └── tpope.lua
│   └── zig-plugins/         # Zig-based CLI tools (first citizen)
│       └── init.lua
├── cli/                       # Zig CLI tools
│   ├── src/                 # CLI source code
│   │   ├── fuzzy.zig
│   │   ├── grep.zig
│   │   ├── pick.zig
│   │   ├── fzf.zig
│   │   ├── task.zig
│   │   ├── buffer.zig
│   │   ├── lsp.zig
│   │   └── bookmark.zig
│   └── test/                # Test files
├── docs/                     # Documentation
└── handle-symlink-integration.sh

Zig CLI Tools

The project includes native CLI tools written in Zig:

Tool	Description
nvim-fuzzy	Fast fuzzy finder
nvim-grep	Fast grep/search
nvim-pick	File picker
nvim-fzf	Interactive fzf-like interface
nvim-task	Task runner
nvim-buffer	Buffer manager
nvim-lsp	LSP client
nvim-bookmark	Persistent line bookmarks

Building CLI Tools

# Build all tools
zig build

# Build specific tool
zig build fuzzy
zig build grep
zig build pick
zig build bookmark

# Install to PATH
cp zig-out/*/nvim-* ~/.local/bin/

Running Tests

# Run all unit tests
chmod +x cli/test_runner.sh
./cli/test_runner.sh

# Run integration tests
chmod +x cli/test_integration.sh
./cli/test_integration.sh

Requirements

• Neovim 0.9+
• Git
• Zig 0.12+ (for building CLI tools)
• A Nerd Font (optional, for icons)

License

MIT