Neovim Configuration

My personal Neovim configuration with LSP support, AI integration, and customized keybindings.

Features

• LSP Support: Full language server protocol integration for multiple languages
• Markdown Preview: Multiple preview options (browser and native webview)
• Completion: nvim-cmp with LSP sources (Tab completion disabled)
• Git Integration: Fugitive, Gitsigns, and Diffview
• File Navigation: Telescope fuzzy finder and Harpoon
• Debugging: DAP (Debug Adapter Protocol) support
• AI tools: OpenCode side split and Claude terminal launcher
• Agent workflow: Which-key discovery, reusable agent context, runbook actions, Overseer task runner, Edgy-managed tool panes
• Sessions: AutoSession workspace save/restore and session picker
• HTTP client: Kulala for running *.http and *.rest requests inside Neovim

Current status

• Neovim 0.12-compatible configuration
• Augment removed from the active setup
• nvim-treesitter/playground removed because it is incompatible with the current treesitter API
• Forgejo is the default git remote for this repo

Key Bindings

Leader Key: <Space>

Autocomplete

• <leader>tc - Toggle autocomplete on/off
• <C-n> / <C-p> - Navigate completion suggestions
• <C-y> - Accept completion
• <C-Space> - Trigger completion

Markdown Preview

• <leader>mp - Toggle Markdown Preview (browser-based)
• <leader>pk - Open Peek preview (native webview)
• <leader>pc - Close Peek preview

AI

• <leader>OC - Select an OpenCode session
• <leader>ot - Toggle OpenCode in a bottom split
• <leader>CC - Open Claude in a top terminal split
• <leader>oP - Add project context to OpenCode
• <leader>od - Add diagnostics context to OpenCode
• <leader>og - Add git context to OpenCode
• <leader>? - Show buffer-local keymaps

Agent workflow

• <leader>ac - Open the agent cockpit
• <leader>av - Pick and run a validation task
• <leader>ae - Collect agent context into a scratch buffer and clipboard
• <leader>aE - Collect agent context and append it to OpenCode
• <leader>Rb - Open the runbook picker
• <leader>Rf - Open runbook entries for the current file
• <leader>Rv - Pick and run a runbook validation command
• <leader>RC - Copy selected runbook context
• <leader>RS - Send selected runbook context to OpenCode

Agent context includes the current file and cursor, Git branch, Git status, Git diff stats, current PR metadata when available, selected text, buffer diagnostics, quickfix items, and recent Overseer tasks.

Direct commands:

• :AgentContext - Collect project and buffer context into a scratch buffer and clipboard
• :AgentContextCopy - Copy context without opening a scratch buffer
• :AgentContextSend - Copy context and append it to OpenCode
• :AgentContextBuffer - Collect current-buffer context only
• :AgentContextProject - Collect full project context
• :Runbook - Open repo-aware runbook entries
• :RunbookForFile - Open entries matching the current file
• :RunbookValidate - Run a selected command through Overseer when available
• :RunbookContext - Copy selected runbook context
• :RunbookSend - Send selected runbook context to OpenCode

Compatibility aliases remain available: :AgentEvidence and :AgentEvidenceToOpenCode.

Project context collects Git and GitHub metadata with short synchronous timeouts. Use :AgentContextBuffer when you only need the current buffer, diagnostics, and selection.

Runbook entries come from Home Manager-generated data when available, with built-in Lua defaults as a fallback. The Home Manager source uses a dendritic Nix tree in modules/home/neovim-runbook.nix and writes stdpath("state")/scribe/runbook/generated.lua during activation.

Tasks

• <leader>tt - Toggle Overseer task list
• <leader>tr - Run an Overseer task
• <leader>tl - Rerun the last task
• <leader>ta - Open task actions

Initial task templates include git-status, nix-flake-show, nix-flake-check, statix-check, gh-pr-checks, gh-pr-view, home-manager-build, and darwin-rebuild-build.

Sessions and layout

• <leader>ss - Search saved sessions
• <leader>sr - Restore the current session
• <leader>sw - Save the current session
• <leader>sd - Delete a session
• <leader>ue - Toggle Edgy-managed tool panes
• <leader>uE - Select an Edgy-managed window

HTTP

• <leader>hs - Send current request
• <leader>ha - Send all requests in the file
• <leader>hi - Inspect response
• <leader>ht - Toggle response view
• <leader>hp - Jump to previous request
• <leader>hn - Jump to next request
• <leader>hb - Open Kulala scratchpad

File Navigation

• <leader>pf - Find files
• <C-p> - Git files
• <leader>/ - Live grep
• <leader>pb - Browse buffers

LSP

• gd - Go to definition
• gr - Go to references
• gi - Go to implementation
• K - Hover documentation
• <leader>rn - Rename symbol
• <leader>ca - Code actions

Git

• <leader>gs - Git status (Fugitive)
• <leader>gp - Preview git hunk
• <leader>gb - Git blame line

GitHub Review

• <leader>Pa - Open Octo actions
• <leader>Pp - List pull requests
• <leader>Pi - List issues
• <leader>Pn - List GitHub notifications
• <leader>Pk - Show PR checks
• <leader>Pw - Show PR workflow runs
• <leader>om - Open current branch PR conversation/timeline
• <leader>oM - Open a PR by number or URL
• <leader>oh - Open PR review help window
• <leader>or - Open current branch PR and start review mode
• <leader>oR - Open a PR by number or URL and start review mode

Customizations

• Tab key inserts literal tabs (autocomplete acceptance disabled)
• Dark chalkboard color theme
• Custom status line with git integration
• Automatic formatting on save for supported languages

Kulala quick start

Create a *.http or *.rest file and place the cursor inside a request.

Example:

GET https://httpbin.org/get
Accept: application/json

###

POST https://httpbin.org/post
Content-Type: application/json

{
  "hello": "world"
}

Usage:

• Use ### to separate requests in one file
• Press <leader>hs to run the request under the cursor
• Press <leader>ha to run every request in the file
• Press <leader>ht to show or hide the response view
• Press <leader>hb for a scratchpad when you do not want to save a file

A ready-to-run example lives at examples/kulala.http.

Octo PR review

Requirements:

• gh auth status must show a healthy GitHub login
• :checkhealth octo should pass after plugin sync/update

Fastest PR review flow:

1. Run <leader>or inside a checked out branch that already has a PR
2. Octo opens the PR and immediately enters review mode
3. You see the PR diff plus inline review threads in Neovim
4. A small floating help window appears with the most useful review keys

To view the PR conversation/timeline comments instead of the diff review:

• <leader>om opens the current branch PR buffer
• <leader>oM opens a PR by number or URL without starting review mode
• <leader>oh opens the review help window again manually

Alternate entrypoint:

• <leader>oR lets you enter a PR number or full GitHub PR URL

Useful review-mode navigation:

• ]q / [q move between changed files
• ]t / [t move between review threads
• <localleader>ca adds a review comment
• <localleader>sa adds a review suggestion
• <localleader>rt resolves a thread
• <localleader>rT reopens a resolved thread

Useful direct commands:

:Octo pr list
:Octo pr checks
:Octo pr runs

Source of truth

This repo is synced into ~/.config/nvim by Home Manager from the separate system configuration repo.

Local Development

# Clone and work locally
git clone ssh://forgejo@parrisisland.netmaker:2224/kenneth/nvim.git ~/.config/nvim
cd ~/.config/nvim

Git remotes

Forgejo is the default remote for this repo.

git remote -v

• origin points to the private Forgejo repository
• github points to GitHub

Push commands:

git push origin main
git push github main

Local pre-push validation

Install the local git hook once:

./scripts/install-git-hooks.sh

After that, every push validates that Neovim starts cleanly:

nvim --headless '+q'