Skip to main content

​
What is Zen Mode?

Zen Mode transforms Avante.nvim into a terminal-based coding agent CLI that looks and feels like tools like Claude Code or Gemini CLI, but runs entirely within Neovim. This gives you the best of both worlds:
  • CLI-like experience for quick AI interactions
  • Full Neovim power underneath for editing and navigation
  • Vim muscle memory works perfectly
  • Rich plugin ecosystem available
  • No context switching between tools

​
Why Zen Mode?

Modern coding agent CLIs have popularized the “Vibe Coding” workflow, but they have fundamental limitations:

Terminal UX Problem

CLI tools struggle with editing multi-line prompts and code. They can’t match 50+ years of terminal editor innovation.

Context Switching

Agent CLIs often need to jump to external editors to view or modify code, breaking your flow.

Limited Extensibility

No access to Neovim’s thousands of mature plugins for navigation, editing, and productivity.

Vim Abstractions

Can’t leverage Vim’s elegant action + text object model for efficient editing.
Zen Mode solves this: It’s a Vibe Coding Agent CLI interface, but it’s actually Neovim underneath. You get a modern agent CLI UX with all of Neovim’s power.

​
Quick Setup

Create an alias to launch Zen Mode: 
alias avante='nvim -c "lua vim.defer_fn(function()require(\"avante.api\").zen_mode()end, 100)"'
Add this to your shell configuration file (~/.bashrc, ~/.zshrc, etc.), then reload your shell: 
source ~/.zshrc  # or ~/.bashrc
Now you can start Zen Mode just like any coding agent CLI: 
avante

​
Using Zen Mode

Once in Zen Mode, you have a focused AI coding interface:

​
Starting a Conversation

1

Launch Zen Mode

avante
This opens Neovim with the Avante sidebar in focus, ready for your first prompt.
2

Type your request

Use the input area to describe what you want:
Create a new authentication module with JWT support
Press <CR> (Enter) in normal mode or <C-s> in insert mode to submit.
3

Review and interact

The AI responds with code suggestions. You can:
  • Apply changes with a (cursor) or A (all)
  • Edit your request with e
  • Retry with r
  • Navigate with standard Vim movements
4

Edit code with Vim

Switch to the code buffer (<Tab>) and use all your Vim skills:
" Jump to function definition
gd

" Visual select and edit
vip:AvanteEdit refactor this to use promises

" Easy motion to navigate
<leader><leader>w

​
Key Features in Zen Mode

Unlike traditional agent CLIs, you can:
  • Use Vim motions (hjkl, w, b, f, t, etc.)
  • Leverage text objects (ciw, dap, vi{, etc.)
  • Run Vim commands (:s/old/new/g, :%s/foo/bar/g)
  • Access all your Vim plugins (telescope, treesitter, etc.)
" Multi-line editing example
:g/function/normal! $aend

" Quick navigation
/error handling<CR>

" Visual block mode
<C-v>jjjI-- <Esc>
Zen Mode supports all ACP features:
  • File operations
  • Tool execution
  • Multi-step workflows
  • Context gathering
See ACP Support for configuration.
Use avante.md files to give the agent project-specific context:
# Project Instructions

## Tech Stack
- Neovim plugin (Lua)
- FFI integration with Rust
- Async I/O with vim.loop

## Coding Standards
- Follow Neovim Lua style guide
- Add type annotations with ---@type
- Write tests for new features
See Project Instructions.

​
Zen Mode vs Traditional Usage

Optimized for terminal workflows
  • Launch from command line: avante
  • Sidebar-first interface
  • Quick AI interactions without opening files
  • CLI-like UX with Vim power underneath
Best for:
  • Starting new projects
  • Quick prototyping
  • Exploratory coding
  • Terminal-centric workflows

​
Advanced Configuration

Customize Zen Mode behavior: 
require('avante').setup({
  -- Zen Mode opens with these settings by default
  windows = {
    position = "right",
    width = 40,
  },
  behaviour = {
    auto_suggestions = false,  -- Disable in Zen Mode for cleaner UX
  },
})

​
Custom Zen Mode Alias

You can create variations for different workflows: 
# Zen Mode with specific provider
alias avante-claude='nvim -c "lua vim.defer_fn(function() require(\"avante.api\").switch_provider(\"claude\"); require(\"avante.api\").zen_mode() end, 100)"'

# Zen Mode for specific project
alias avante-work='cd ~/work && nvim -c "lua vim.defer_fn(function()require(\"avante.api\").zen_mode()end, 100)"'

# Zen Mode with custom instructions
alias avante-docs='nvim -c "lua vim.g.avante_instructions = \"~/docs-rules.md\"; vim.defer_fn(function()require(\"avante.api\").zen_mode()end, 100)"'

​
Keyboard Shortcuts in Zen Mode

All standard Avante keybindings work, plus you have full Vim at your fingertips:
ActionKeybindingDescription
Submit request<CR> (normal) or <C-s> (insert)Send your prompt to AI
Switch windows<Tab>Toggle between chat and code
Apply cursoraApply suggestion at cursor
Apply allAApply all suggestions
Edit requesteModify your last request
RetryrRegenerate response
Add file@Add file to context
Remove filedRemove file from context
Closeq or <Esc>Exit Zen Mode

​
Tips for Effective Zen Mode Usage

Use project instructions: Create an avante.md file in your project root to give the agent context about your codebase, conventions, and requirements.
Leverage Vim plugins: Your favorite Neovim plugins (telescope, harpoon, vim-fugitive) work perfectly in Zen Mode.
Split windows: Use :vsplit and :split to view multiple files while chatting with the AI.
Terminal integration: Open a terminal inside Neovim (:terminal) to run commands without leaving Zen Mode.

​
Example Workflow

Here’s a complete Zen Mode workflow for building a new feature:
1

Launch Zen Mode

cd ~/my-project
avante
2

Describe the feature

Create a new user authentication system with:
- Email/password login
- JWT token generation
- Password hashing with bcrypt
- Input validation
3

Review generated code

The AI generates the authentication module. Use Vim navigation:
" Jump to function
/login_user<CR>

" Check implementation
zz  " Center on screen
4

Apply and test

" Apply the changes
A

" Switch to terminal
:terminal
lua test/auth_test.lua
5

Iterate on feedback

Add rate limiting to prevent brute force attacks
The agent updates the code with rate limiting logic.

​
Comparison with Other Agent CLIs

FeatureZen ModeClaude CodeGemini CLICursor CLI
Vim Editing✅ Full Vim❌ Limited❌ Limited❌ Limited
Plugin Support✅ All Neovim plugins❌ None❌ None❌ None
Multi-line Editing✅ Vim text objects⚠️ Basic⚠️ Basic⚠️ Basic
Context Switching✅ None❌ External editor❌ External editor❌ External editor
Terminal Integration✅ Native⚠️ Limited⚠️ Limited⚠️ Limited
Customization✅ Full Lua/Vim script❌ Limited❌ Limited❌ Limited

​
Next Steps

Quick Start

Get started with Avante in 5 minutes

Project Instructions

Customize AI behavior for your project

ACP Support

Use external AI agents in Zen Mode

Keybindings

Complete keybinding reference

Build docs developers (and LLMs) love

Get started for freeTalk to us