berani.nvim 🔮

berani.nvim is a harness-agnostic, decoupled AI coding agent integration plugin for Neovim (tailored for LazyVim). It bridges your buffer workflows directly with terminal multiplexers (herdr, tmux, zellij, or native Neovim splits/floats) and AI agent harnesses (agy, codex, opencode, hermes, gemini, etc.).

---

✨ Features

• 🖥️ Multi-Backend Transport Routing: Auto-detects terminal environment order (Herdr → Tmux → Zellij → Native) or toggle on the fly (<leader>ab).
• ⚡ Inline Virtual View (<leader>av): Non-destructive floating preview cards and inline virtual text with transient single-key actions (q dismiss, y yank, r replace, e expand).
• 🛰️ LSP Ambient HUD Widget (<leader>aH): Sleek, borderless, low-profile status ticker (fidget.nvim style) with fluid animated spinner, colored indicators (🟢, 🟡 ⠋, ⚪), and zero-float statusline() helper.
• 📌 Floating Popup & Single-Keypress Pin Mode: Ask general questions (<leader>aa), then press p to instantly promote floats to splits ([h], [l], [k], [j]) or tabs ([t]).
• 🤖 100% Dynamic Model Discovery: Queries models live from agent CLIs and ACP daemons with intelligent reasoning effort filtering (low, medium, high).
• 🔍 Interactive Edit Review & Hunk Acceptance: Review agent edits side-by-side (:BeraniReview), navigate hunks (]c / [c), and accept (<leader>ay) or reject (<leader>ax) changes.
• 📐 Visual Context & Diff Formatting: Format characterwise, linewise, or blockwise visual selections with syntax highlighting and file range metadata (@[abs_path#L10-L20]).

---

🚀 Quick Start

Using lazy.nvim:

return {
  "vikks/berani.nvim",
  opts = {}, -- Uses defaults: fidget HUD, virtual view, ask in float, code in active multiplexer
}

---

⌨️ Essential Keymaps (<leader>a)

Keymap	Mode	Command	Description
<leader>aa	Normal / Visual	:BeraniAsk	Ask general question in floating popup or pane
<leader>av	Visual / Normal	:BeraniVirtualSend / :BeraniVirtualToggle	Render agent response inline as virtual card / toggle
<leader>aH	Normal	:BeraniHUD	Toggle live connected harness HUD widget
<leader>ab	Normal	:BeraniToggleBackend	Toggle active backend transport between auto & native
<leader>as	Normal / Visual	:BeraniStatus / :BeraniSend	Show status / Send visual selection to agent
<leader>ac	Normal / Visual	:BeraniSelectTarget / :BeraniContext	Select target pane interactively / Send code context to agent
<leader>ad	Normal / Visual	:BeraniDiff	Send diff review comment to agent
<leader>ah	Normal	:BeraniSelectAgent	Select target agent harness & model interactively
<leader>ar	Normal	:BeraniReview	Toggle side-by-side edit review diff view
<leader>ay / <leader>ax	Normal	:BeraniAccept / :BeraniReject	Accept or reject agent edit hunk / file changes

---

📚 Documentation & Guides

For detailed configuration schemas, system architecture blueprints, and developer guides, explore the docs/ folder:

• ⚙️ Configuration Guide — Detailed opts schema (tasks, backends, harness, providers, window_opts).
• 💡 Examples & Recipes — Ready-to-use configuration recipes for Herdr, Tmux, Zellij, OpenCode ACP, and local Ollama.
• 🏛️ System Architecture — 4-layer decoupled architecture and backend adapter contracts.
• 📜 Keymaps & Commands Reference — Complete list of user commands and popup keybindings.
• 🛠️ Developer & Contributor Guide — Headless test suite runner and open-source PR workflows.

---

📄 License

MIT © 2026