Usage

Table of contents

chat.nvim provides several commands to manage your AI conversations. The main command is :Chat, which opens the chat window. You can also navigate between sessions using the following commands.

Basic Commands

Command Description
:Chat Open the chat window with the current session
:Chat new Start a new chat session
:Chat prev Switch to the previous chat session
:Chat next Switch to the next chat session
:Chat delete Delete current session and create new empty session
:Chat clear Clear all messages in current session
:Chat cd <dir> Change current session cwd, open chat window
:Chat save <path> Save current session to specified file path
:Chat load <path> Load session from file path or URL
:Chat share Share current session via pastebin
:Chat preview Open HTML preview of current session in browser
:Chat bridge Bind current session to external platform (Discord)
:Chat unbridge [im] Unbind integration (all or specific platform)

MCP Commands

Manage MCP (Model Context Protocol) servers with the following commands:

Stop MCP servers 

:Chat mcp stop

Stops all running MCP servers and cleans up resources.

Start MCP servers 

:Chat mcp start

Starts all configured MCP servers. Note: Servers are automatically started when opening the chat window.

Restart MCP servers 

:Chat mcp restart

Restarts all MCP servers (stops and starts with a delay for cleanup).

  • MCP servers are automatically started when you open the chat window (:Chat)
  • MCP servers are automatically stopped when you exit Neovim
  • Use these commands for manual control if needed (e.g., after changing configuration)

Parallel Sessions

chat.nvim supports running multiple chat sessions simultaneously, with each session operating independently:

  • Independent Model Selection: Each session can use a different AI model (e.g., Session A with DeepSeek, Session B with GitHub AI)
  • Separate Contexts: Sessions maintain their own conversation history, working directory, and settings
  • Quick Switching: Use :Chat prev and :Chat next to navigate between active sessions
  • Isolated Workflows: Perfect for comparing model responses or working on multiple projects simultaneously

Workflow Example

  1. Start a session with DeepSeek: :Chat new (then select DeepSeek model)
  2. Switch to GitHub AI for a different task: :Chat new (select GitHub model)
  3. Toggle between sessions: :Chat prev / :Chat next
  4. Each session preserves its unique context and conversation flow

Examples

1. Start a new conversation 

:Chat new

This creates a fresh session and opens the chat window.

2. Resume a previous conversation 

:Chat prev

Cycles backward through your saved sessions.

3. Switch to the next conversation 

:Chat next

Cycles forward through your saved sessions.

4. Open or force to the chat window 

:Chat

This command will not change current sessions.

5. Delete current session 

:Chat delete

Cycles to next session or create a new session if current session is latest one.

6. Change the working directory of current session 

:Chat cd ../picker.nvim/

If the current session is in progress, the working directory will not be changed, and a warning message will be printed.

7. Clear messages in current session 

:Chat clear

If the current session is in progress, a warning message will be printed, and current session will not be cleared. This command also will forced to chat window.

8. Work with multiple parallel sessions 

" Start first session with DeepSeek
:Chat new
" Select DeepSeek as provider and choose a model

" Start second session with GitHub AI
:Chat new
" Select GitHub as provider and choose a model

" Switch between sessions
:Chat prev  " Go to first session
:Chat next  " Go to second session

This enables simultaneous conversations with different AI assistants for different tasks.

9. Save current session to a file 

:Chat save ~/sessions/my-session.json

Saves the current session to a JSON file for backup or sharing.

10. Load session from file 

:Chat load ~/sessions/my-session.json

Loads a previously saved session from a JSON file.

11. Load session from URL 

:Chat load https://paste.rs/xxxxx

Loads a session from a URL (e.g., from paste.rs).

12. Share current session 

:Chat share

Uploads the current session to paste.rs and copies the URL to clipboard. This allows easy sharing of conversations with others.

13. Preview current session in browser 

:Chat preview

Opens an HTML preview of the current session in your default browser. The preview includes session metadata, messages, tool calls, and token usage statistics. You can also use <C-o> in the picker’s chat source to open previews.

All sessions are automatically saved and can be resumed later. For more advanced session management, see the Picker Integration section below.

Key Bindings

Input Window Key Bindings

The following key bindings are available in the Input window:

Mode Key Binding Description
Normal <Enter> Send message
Normal q Close chat window
Normal <Tab> Switch between input and result windows
Normal Ctrl-C Cancel current request
Normal Ctrl-N Open new session
Normal Ctrl-D Delete current session
Normal r Retry last cancelled request
Normal alt-h Previous chat session
Normal alt-l Next chat session
Normal <Leader>fr Run :Picker chat
Normal <Leader>fp Run :Picker chat_provider
Normal <Leader>fm Run :Picker chat_model
Normal <M-t> Rename current session title

Result Window Key Bindings

The following key bindings are available in the Result window:

Mode Key Binding Description
Normal q Close chat window
Normal dd Delete message at cursor position
Normal <Tab> Switch between input and result windows
Normal <Leader>fr Run :Picker chat

Markdown Rendering

The result window uses markdown filetype, enabling syntax highlighting and RenderMarkdown integration for rich rendering of AI responses including headings, code blocks, tables, and lists.

Session Title

Each session has a title displayed in the title bar of both the input and result windows. Press <M-t> in the input window to rename the current session title.

Picker Integration

chat.nvim provides built-in picker sources for seamless integration with picker.nvim. These sources allow you to quickly access and manage your chat sessions, providers, and models.

The chat picker source displays all your active sessions, allowing quick switching between parallel conversations with different models.

Available Sources

1. chat - Session History

Search through your chat history sessions:

  • Displays the project name (cwd tail) and the first message of each session
  • Quickly resume previous conversations
  • Quickly locate sessions by project
  • Supports filtering and session management

Keyboard Shortcuts:

  • <CR> (Enter): Open selected session
  • <C-d>: Delete selected session
  • <C-o>: Open HTML preview in browser

2. chat_provider - Provider Switcher

Switch between different AI providers:

  • Dynamically change between supported providers (DeepSeek, OpenAI, etc.)
  • Real-time switching without restarting Neovim

3. chat_model - Model Selector

Select available models for the current provider:

  • Lists all compatible models for your selected provider
  • Intelligent filtering based on provider capabilities

Skills (Slash Commands)

chat.nvim includes a built-in skill system that lets you type /name [args] in the prompt window to invoke commands without sending a message to the LLM. This is useful for quick actions like switching models, clearing sessions, or changing the working directory.

Built-in Skills

Skill Description
/clear Clear all messages in current session
/new Create a new session
/delete Delete current session
/model [name] Switch model (shows selection UI if no name given)
/provider [name] Switch provider (shows selection UI if no name given)
/cwd <path> Change working directory
/pin Toggle pin status of current session
/title [text] Set session title (shows input UI if no text given)
/retry Retry last request
/help Show all available skills

Usage

Type the skill name directly in the prompt window:

/model gpt-4o
/provider openai
/cwd /tmp
/clear
/help

When no arguments are provided for /model and /provider, a selection UI (vim.ui.select) is shown. Similarly, /title without arguments uses vim.ui.input for interactive input.

Custom Skills

You can register your own skills via configuration or Lua API:

Via Configuration 

require('chat').setup({
  skills = {
    {
      name = 'greet',
      description = 'Say hello',
      handler = function(args, ctx)
        return 'Hello, ' .. (args or 'world') .. '!'
      end,
    },
  },
})

Via Lua API 

require('chat').register_skill({
  name = 'greet',
  description = 'Say hello',
  handler = function(args, ctx)
    return 'Hello, ' .. (args or 'world') .. '!'
  end,
})

-- Unregister a skill
require('chat').unregister_skill('greet')

Runtime Skills (File-based Auto-load)

The easiest way to add custom skills: create a .lua file in the lua/chat/skills/ directory. chat.nvim automatically discovers and loads these files on startup.

How it works:

  1. Place a .lua file under lua/chat/skills/ (in your Neovim runtimepath)
  2. The file name (without .lua) becomes the module name, but the skill name is determined by the name field in the returned table
  3. The file must return a table matching the ChatSkill structure
  4. On init(), chat.nvim scans lua/chat/skills/*.lua and registers each one

File structure:

lua/chat/skills/
├── my-skill.lua           # /my-skill
├── setup-nvim-plugin-test.lua  # /setup-nvim-plugin-test
└── README.md              # Skipped (not a .lua file)

Minimal example — lua/chat/skills/greet.lua:

-- lua/chat/skills/greet.lua
-- /greet [name] - Say hello

return {
  name = 'greet',
  description = 'Say hello',
  handler = function(args, ctx)
    return 'Hello, ' .. (args or 'world') .. '!'
  end,
}

After creating the file, restart Neovim (or run :Chat which triggers init). Type /greet Nova in the prompt window to use it.

Advanced example — inject a user message and trigger LLM request:

-- lua/chat/skills/setup-nvim-plugin-test.lua
-- /setup-nvim-plugin-test - Scaffold a Neovim plugin test system

return {
  name = 'setup-nvim-plugin-test',
  description = 'Set up Neovim plugin test system',
  handler = function(_, _)
    local lines = {
      '请为当前项目搭建 Neovim 插件测试系统。',
      '',
      '参考 wsdjeg/chat.nvim 的测试基础设施：',
      '1. fetch AGENTS.md from GitHub raw URL',
      '2. Read current project structure',
      '3. Generate test files following the spec',
    }

    -- Return a ChatSkillResult table instead of a plain string
    return {
      content = table.concat(lines, '\n'),
      role = 'user',       -- Inject as a user message
      request = true,       -- Trigger LLM request after injecting
    }
  end,
}

Rules:

  • The file must return a table with name (string) and handler (function) fields
  • description is optional but recommended (shown in /help)
  • If a file fails to load, an error is logged and other skills continue loading
  • Files named README.* are skipped (documentation only)
  • Runtime skills are loaded after built-in skills, so built-in names take precedence

Skill Handler API

Each skill handler receives two arguments:

Parameter Type Description
args string Arguments passed after the skill name (trimmed)
ctx table Context containing ctx.session (session ID)

The handler can return:

Return type Description
string Output text displayed to the user
nil No output (silent execution)
ChatSkillResult A table to inject a message and optionally trigger LLM

ChatSkillResult fields:

Field Type Description
content string Message content to append to the session
role string? Message role: "user" or "assistant" (default: "assistant")
request boolean? If true, trigger LLM request after appending (default: false)

Skills are intercepted before being sent to the LLM. If the input doesn’t start with /, it’s treated as a normal message. Unknown /name commands will show a warning.

Session Management

Automatic Saving

All sessions are automatically saved to:

stdpath('data')/chat.nvim/sessions/

Session Files

Each session is stored as a JSON file with the following structure:

{
  "id": "2024-01-15-10-30-00",
  "provider": "deepseek",
  "model": "deepseek-v4-flash",
  "cwd": "/path/to/project",
  "prompt": "You are a helpful assistant...",
  "title": "",
  "pin": false,
  "messages": [
    {
      "role": "user",
      "content": "Hello!",
      "created": 1705300200
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help you?",
      "created": 1705300205,
      "usage": {
        "total_tokens": 30,
        "prompt_tokens": 10,
        "completion_tokens": 20
      }
    }
  ],
  "usage": {
    "total_tokens": 30,
    "prompt_tokens": 10,
    "completion_tokens": 20
  }
}

Field Reference:

Field Type Description
id string Session ID (timestamp format: YYYY-MM-DD-HH-MM-SS)
provider string AI provider name
model string Model name
cwd string Session working directory
prompt string System prompt for this session
title string Session title (shown in window title bar)
pin boolean Whether the session is pinned
messages array Array of message objects
messages[].role string Message role (user, assistant, tool)
messages[].content string Message content
messages[].created integer Unix timestamp (seconds)
messages[].usage object Token usage (assistant messages only, optional)
usage object Cumulative token usage for the session
last_user_message_time integer Unix timestamp of last user message (optional)

Session Commands

Command Description
:Chat save <path> Save session to custom location
:Chat load <path> Load session from file or URL
:Chat share Upload session to paste.rs
:Chat preview Open HTML preview in browser
:Chat delete Delete current session
:Chat clear Clear messages in current session

Window Management

Floating Window

chat.nvim uses a floating window interface with:

  • Dual-window layout: Separate input and result windows
  • Configurable dimensions: Adjust width and height via configuration
  • Border styles: Support for all Neovim border styles
  • Auto-scroll: Intelligent scrolling behavior

Window Dimensions

Configure window size in your setup:

require('chat').setup({
  width = 0.8,   -- 80% of screen width
  height = 0.8,  -- 80% of screen height
  border = 'rounded',
})

Border Options

Supports all Neovim border styles:

  • "none" - No border
  • "single" - Single line border
  • "double" - Double line border
  • "rounded" - Rounded corners (default)
  • "solid" - Solid border
  • "shadow" - Shadow effect

Streaming Responses

Real-time Streaming

chat.nvim supports streaming responses from AI providers:

  • Real-time display: See responses as they’re generated
  • Cancellation support: Press Ctrl-C to cancel ongoing requests
  • Retry mechanism: Press r to retry the last cancelled request
  • Auto-retry on network errors: When LLM requests fail due to connection errors or timeouts, the system automatically retries up to 3 times (configurable via retry option). Error messages with retry status (e.g., Auto-retry 1/3 (2 remaining).) are appended to the session. When all retries are exhausted, the message includes Press r to retry manually. During retry delay, Ctrl-C can cancel the pending retry.

Token Usage Tracking

Real-time token consumption is displayed for each response:

Input: 150 tokens | Output: 75 tokens | Total: 225 tokens

Token counts are displayed in the result window after each response, helping you monitor API usage.

Tips and Tricks

1. Quick Session Switching

Use keyboard shortcuts for fast navigation:

  • alt-h - Previous session
  • alt-l - Next session
  • <Leader>fr - Open session picker

2. Working with Multiple Projects

Use :Chat cd to change the working directory for each session:

:Chat cd ~/projects/project-a
" Work on project A...

:Chat new
:Chat cd ~/projects/project-b
" Work on project B...

3. Sharing Sessions

Share your conversations with others:

:Chat share
" URL copied to clipboard: https://paste.rs/xxxxx

4. Preview Sessions in Browser

Generate beautiful HTML previews:

:Chat preview
" Opens browser with formatted conversation

5. Session Backup

Save important sessions to files:

:Chat save ~/backups/important-session.json

Learn how to use chat.nvim’s advanced features for enhanced productivity.

Overview

chat.nvim provides powerful features beyond basic chatting:

  • Memory System: Three-tier memory for context retention
  • MCP Protocol: Extended tool capabilities via external servers
  • Tools: 41+ built-in tools for file operations, Git, web search, etc.
  • Skills: Slash commands for quick actions without LLM round-trips

Features

Memory System

chat.nvim implements a sophisticated three-tier memory system:

  • Working Memory ⚡ - Session-scoped, highest priority
  • Daily Memory 📅 - Temporary, auto-expires after 7-30 days
  • Long-term Memory 💾 - Permanent knowledge storage

Learn more: Memory System

MCP (Model Context Protocol)

Native MCP support for extended tool capabilities:

  • Connect to MCP servers via stdio or HTTP
  • Automatically discover MCP tools
  • Seamlessly integrate with built-in tools

Learn more: MCP

Built-in Tools

40+ built-in tools for various operations:

  • File: read_file, write_file, find_files, search_text
  • Git: git_add, git_commit, git_diff, git_log, etc.
  • Web: fetch_web, web_search
  • Memory: extract_memory, recall_memory
  • Planning: plan, schedule_task
  • User: user_profile

Next Steps