Skip to content
wsdjegPublic

About

A lightweight Lua chat plugin for Neovim with AI integration.

Topics

Resources

Stars

13 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

942 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

chat.nvim

chat.nvim is a lightweight, extensible chat plugin for Neovim with AI integration. Chat with AI assistants directly in your editor through a clean floating window: 23 AI providers, a three-tier memory system, 49 built-in tools, the Model Context Protocol, IM integrations, and an HTTP API for external access.

Full documentation: https://nvim.chat

Run Tests GitHub License GitHub Issues or Pull Requests GitHub commit activity GitHub Release luarocks

chat-nvim

✨ Features

  • πŸ€– 23 AI Providers - DeepSeek, OpenAI, Anthropic, GitHub Models, Gemini, Ollama, Baidu, Xiaomi, Alibaba Cloud, Moonshot, Tencent, OpenRouter, SiliconFlow, and more
  • 🧠 Three-Tier Memory - Working, daily, and long-term memory with automatic extraction and priority-based retrieval
  • πŸ› οΈ 49 Built-in Tools - File operations, Git integration, web search and fetch, email, scheduling, user profiles
  • 🧩 Slash Commands - Built-in skills (/model, /provider, /cwd, /pin, /title, /retry, /help, ...) plus your own via register_skill()
  • πŸ” Lazy Tool Discovery - Only essential tools are sent with each request; the rest are activated on demand through a built-in catalog
  • πŸ”„ Parallel Sessions - Multiple conversations with different models and working directories at the same time
  • πŸ”Œ MCP Protocol - Native Model Context Protocol support via stdio and HTTP transports
  • πŸ’¬ IM Integration - Discord, Telegram, Slack, Lark, DingTalk, WeCom, WeChat
  • 🌐 HTTP API - Built-in server for external integration with API key authentication
  • πŸ‘€ User Profiles - Per-user preferences and skills for personalized assistance
  • ⏰ Scheduled Tasks - One-time or recurring tasks that persist across Neovim restarts
  • ⚑ Streaming Responses - Real-time AI responses with cancellation, auto-continuation and token tracking

πŸš€ Quick Start

  1. Install the plugin together with its required dependency job.nvim (see below).
  2. Configure an API key for at least one provider.
  3. Run :Chat, type your prompt, and press <CR>.
require('chat').setup({
  provider = 'deepseek',
  model = 'deepseek-v4-flash',
  api_key = {
    deepseek = 'your-deepseek-api-key',
  },
})

Switch providers or models at any time from the prompt window:

/provider openai
/model gpt-4o

πŸ“¦ Installation

chat.nvim works with all major Neovim plugin managers. job.nvim is required; picker.nvim is optional but recommended.

  • Using lazy.nvim

    {
      'wsdjeg/chat.nvim',
      dependencies = {
        'wsdjeg/job.nvim', -- Required
        'wsdjeg/picker.nvim', -- Optional but recommended
      },
    }
  • Using nvim-plug

    require('plug').add({
      {
        'wsdjeg/chat.nvim',
        depends = {
          'wsdjeg/job.nvim',
          'wsdjeg/picker.nvim',
        },
      },
    })
  • Using luarocks

    luarocks install chat.nvim
    

See the Installation Guide for prerequisities and troubleshooting.

πŸ”§ Configuration

A minimal setup covering the most commonly used options:

require('chat').setup({
  -- window options
  width = 0.8,
  height = 0.8,
  auto_scroll = true,
  border = 'rounded',
  -- default AI provider and model
  provider = 'deepseek',
  model = 'deepseek-v4-flash',
  -- time display format
  strftime = '%m-%d %H:%M:%S',
  -- display names for the AI and user, used in the chat window
  -- and on role badges in the HTML preview
  names = {
    bot = 'Bot',
    user = 'You',
  },
  -- enable RenderMarkdown for result buffer
  render_markdown = true,
  -- default system prompt (string or function returning a string)
  system_prompt = '',
  -- restrict file tool access to specific paths (string or list of strings);
  -- empty means no file access at all
  allowed_path = '',
  -- base directory for sessions, memory, plans, scheduled tasks, ...
  storage_dir = vim.fn.stdpath('data') .. '/chat.nvim/',
  -- HTTP server for external integration
  http = {
    host = '127.0.0.1',
    port = 7777,
    api_key = '', -- set to non-empty to enable
  },
  -- tool discovery: send only essential tools + find_tool, activate the rest on demand
  tools = {
    lazy = true,
    essential = { 'read_file', 'list_directory', 'search_text', 'find_files', 'get_time' },
  },
  -- API keys for providers
  api_key = {
    deepseek = 'your-deepseek-api-key',
    openai = 'your-openai-api-key',
    -- Multiple keys per provider: rotated round-robin, a key that hits a
    -- rate limit / quota / server error is cooled down automatically
    -- (token_cooldown = 30s, quota_cooldown = 3600s) and skipped
    volcengine_coding_plan = {
      'uuid-of-account-1',
      'uuid-of-account-2',
    },
  },
})

See the Configuration Guide for every available option.

Multi-key rotation

A provider key can be a single string (old behavior) or a list of keys. When a request fails on an api-key error before any content streamed (rate limit, quota exhausted, server error), the request is transparently re-sent with the next key: nothing is appended to the session, the model never sees the rotation. Per-key cooldowns:

Error class Config Default
Rate limit (429, QPS throttle) token_cooldown 30s
Quota exhausted (e.g. coding-plan 5h limit, balance, arrears) quota_cooldown 3600s

βš™οΈ Basic Usage

Open the chat window:

:Chat

Subcommands:

Command Description
:Chat Open the chat window (current session)
:Chat new Create a new session
:Chat prev / :Chat next Switch to the previous / next session
:Chat delete Delete the current session
:Chat clear Clear the current session's messages
:Chat cd <dir> Open a session in the given working directory
:Chat save <file> Save the session to a file
:Chat load <file|url> Load a session from a file or URL
:Chat share Share the session to a pastebin
:Chat preview Open the HTML preview in your browser
:Chat mcp <start|stop|restart> Control MCP servers
:Chat bridge <im> / :Chat unbridge [im...] Bind / unbind an IM integration to the current session

Built-in slash commands, typed in the prompt window:

/model /provider /cwd /pin /title /retry /new /delete /clear /toggle-force-push /help

Register your own with require('chat').register_skill({ name, description, handler }).

With picker.nvim the following keybindings work in the input window:

Key Binding Action
<Leader>fp Switch provider via picker
<Leader>fm Switch model via picker
<Leader>fr Browse session history via picker

See the Usage Guide for all commands and keybindings.

🧠 Memory System

chat.nvim implements a three-tier memory system:

Type Lifetime Purpose
Working Session Current context, decisions, active tasks
Daily 7-30 days Tasks, reminders, schedules
Long-term Permanent Preferences, facts, skills

Memories are automatically extracted during conversations and retrieved with priority-based ranking. See the Memory Guide for details.

πŸ› οΈ Tools

49 built-in tools let AI assistants interact with your environment:

  • File Operations - Read, write, copy, move, create and delete files and directories
  • Search - Find files, grep text, list directories, inspect metadata
  • Git Integration - Status, diff, log, show, add, commit, push, pull, fetch, branch, checkout, merge, rebase, reset, stash, tag, remote, config
  • Web Search - Search via Firecrawl, Google, or SerpAPI
  • Web Fetch - Fetch URLs and convert HTML to markdown
  • Email - Send emails via the system mail command
  • Mastodon - Read-only Mastodon: fetch toots, threads, and timelines
  • Memory Management - Extract and recall memories
  • Scheduled Tasks - One-time or recurring tasks, persisted across restarts
  • User Profiles - Manage per-user preferences and skills
  • Task Plans - Create and manage task plans
  • Office Documents - View Excel files with multiple modes
  • Development - Run make targets, check LSP diagnostics, get weather and time, convert images via ffmpeg
  • Session - Read your own conversation history, set the session system prompt

Tools are lazy-loaded by default: only the essential tools plus a find_tool discovery catalog are sent with each request to save prompt tokens, and other tools are activated on demand for the current turn. Set tools.lazy = false to send all tools with every request.

See the Tools Guide for the full list and usage.

πŸ”Œ MCP Support

Native Model Context Protocol support for extended tool capabilities:

require('chat').setup({
  mcp = {
    mcpServers = {
      -- stdio transport
      filesystem = {
        command = 'npx',
        args = { '-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir' },
      },
      -- HTTP transport
      remote = {
        url = 'http://localhost:3000/mcp',
      },
    },
  },
})

See the MCP Guide for details.

πŸ’¬ IM Integration

Connect messaging platforms for remote AI interaction:

  • Discord - Chat with AI via Discord bot
  • Telegram - Send messages and receive AI responses
  • Slack - Slash command integration
  • Lark - Feishu/Lark bot support
  • DingTalk - DingTalk robot integration
  • WeCom - WeChat Work integration
  • WeChat - WeChat official account support

See the Integrations Guide for setup instructions.

🌐 HTTP API

The built-in HTTP server allows external applications to send messages to chat.nvim:

curl -X POST http://127.0.0.1:7777/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-api-key" \
  -d '{"content":"Hello","session":"default"}'

See the API Guide for all endpoints.

πŸ“£ Self-Promotion

If you like this plugin, please star it on GitHub. Also check out my other Neovim plugins:

πŸ’¬ Feedback

If you encounter any bugs or have suggestions, please file an issue in the issue tracker

πŸ“„ License

Licensed under GPL-3.0.

About

A lightweight Lua chat plugin for Neovim with AI integration.

Topics

Resources

Stars

13 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages