Configuration

Table of contents


chat.nvim provides flexible configuration options through the require('chat').setup() function. All configurations have sensible defaults.

Basic Options

Option Type Default Description
width number 0.8 Chat window width (percentage of screen width, 0.0-1.0)
height number 0.8 Chat window height (percentage of screen height, 0.0-1.0)
auto_scroll boolean true Controls automatic scrolling behavior of the result window
border string 'rounded' Window border style, supports all Neovim border options
provider string 'deepseek' Default AI provider
model string 'deepseek-v4-flash' Default AI model
strftime string '%m-%d %H:%M:%S' Time display format
names table {bot = 'Bot', user = 'You'} Display names for the AI and user, shown before the colon in the chat window and on role badges in the HTML preview
render_markdown boolean true Enable RenderMarkdown plugin for result buffer (requires render-markdown.nvim)
system_prompt string or function '' Default system prompt, can be a string or a function that returns a string
storage_dir string stdpath('data') .. '/chat.nvim/' Base storage directory for all persistent data (sessions, plans, scheduler, etc.)
highlights table {title = 'ChatNvimTitle', title_badge = 'ChatNvimTitleBadge', placeholder = 'ChatNvimPlaceholder'} Highlight groups for title text, decorative badges and the prompt placeholder (see Prompt Placeholder)
winhighlight string 'NormalFloat:Normal,FloatBorder:WinSeparator' Window highlight configuration for floating windows
token_cooldown number 30 Seconds an api key is skipped after a rate-limit (429) or server (5xx) error
quota_cooldown number 3600 Seconds an api key is skipped after a quota-exhaustion error (e.g. coding-plan limits)
usage_stats table { enable = true, hourly_days = 7, daily_days = 365 } Per provider/model request & token accounting (see Usage Statistics)

Example

require('chat').setup({
  width = 0.8,
  height = 0.8,
  auto_scroll = true,
  border = 'rounded',
  provider = 'deepseek',
  model = 'deepseek-v4-flash',
  strftime = '%Y-%m-%d %H:%M',
  names = { bot = 'Nova', user = 'You' },
})

Prompt Placeholder

When the input window is empty, chat.nvim renders a placeholder (输入消息...) as virtual text. It lives in its own extmark namespace, so it never leaks into get_content() and is invisible to the buffer lines.

Only two highlight groups are involved:

Editor state Highlight group
Insert mode Comment
Normal mode, cursorline enabled highlights.placeholder (default ChatNvimPlaceholder)
Normal mode, cursorline unset Comment

Insert mode always uses Comment because CursorLine is not drawn there. In Normal mode the placeholder switches to the configured group only when the prompt window has cursorline enabled — that group derives its foreground from Comment and its background from CursorLine, so the placeholder blends into the cursor line instead of punching a hole into it.

require('chat').setup({
  highlights = {
    -- Customize the cursorline-aware placeholder group
    placeholder = 'MyPlaceholder',
  },
})

-- Fully override the colors (chat.nvim only sets them when the group is empty)
vim.api.nvim_set_hl(0, 'MyPlaceholder', { fg = '#7a7a7a', bg = '#2b2b2b' })

The group is (re)applied on ColorScheme, and the placeholder is re-rendered on TextChanged, TextChangedI, TextChangedP, ModeChanged, InsertEnter, InsertLeave, BufEnter, WinEnter and OptionSet.


Storage Paths

All persistent data (sessions, plans, scheduler, memory, user profiles) is stored under storage_dir. Sub-module storage directories are automatically derived from storage_dir unless explicitly overridden:

Module Config Key Derived Path Description
Sessions — storage_dir Chat session JSON files
Plans — storage_dir .. 'plans/' Task plan JSON files
Scheduler — storage_dir .. 'scheduler/' Scheduled task JSON files
Memory memory.storage_dir storage_dir .. 'memory/' Three-tier memory database
User Profiles user.storage_dir storage_dir .. 'users/' User profile markdown files

To override a specific module’s storage path, set its storage_dir to a custom value:

require('chat').setup({
  -- Change the base directory for everything
  storage_dir = '/my/custom/path/',

  -- Or override individual modules
  memory = {
    storage_dir = '/separate/memory/path/',
  },
})

If memory.storage_dir or user.storage_dir is nil (the default), they are automatically derived from storage_dir. You only need to set them if you want to use a different location for that specific module.


Tool Loading Configuration

Control which tools are sent with each request:

Option Type Default Description
tools.lazy boolean true Send only essential + activated tools instead of all tools
tools.essential string[] { 'read_file', 'list_directory', 'search_text', 'find_files', 'get_time' } Tools always included in requests when lazy mode is on

Example

require('chat').setup({
  tools = {
    lazy = true, -- set false to send all tools with every request
    essential = { 'read_file', 'list_directory', 'search_text', 'find_files', 'get_time' },
  },
})

Notes

  • With lazy loading the find_tool tool is always included; it lets the AI model discover other tools by keyword and activate them for the current turn
  • Activation resets when the turn ends (text-only response, no tool calls), so each turn starts from the essential toolset
  • Tools already called in the still-open turn are automatically re-included (self-healing after an abort or restart mid tool-call loop)
  • The tools array has a deterministic, per-turn frozen order (tools.essential → lazily loaded tools → find_tool last). Lazily loaded tools are placed on first appearance — tools called in the turn first (call order), then tools activated via find_tool (activation order) — and keep that slot until the turn ends. It sits right after the system prompt in every request body, so a stable order keeps the provider’s prompt cache valid; calling an already-placed tool or re-activating it never reshuffles the array, and only a genuinely new tool appends one entry

HTTP Server Configuration

Configure the built-in HTTP server for receiving external messages:

Option Type Default Description
http.host string '127.0.0.1' Host address for the HTTP server
http.port number 7777 Port number for the HTTP server
http.api_key string '' API key for authenticating incoming requests (must be non-empty to enable server)

Example

http = {
  host = '127.0.0.1',
  port = 7777,
  api_key = 'your-secret-api-key-here', -- Set to empty string to disable HTTP server
}

Notes

  • The HTTP server is automatically started when http.api_key is not empty
  • Incoming requests must include the API key in the X-API-Key header
  • Messages are queued and processed when the chat window is not busy

API Key Configuration

Configure API keys for the AI providers you plan to use:

api_key = {
  deepseek = 'sk-xxxxxxxxxxxx',        -- DeepSeek AI
  github = 'github_pat_xxxxxxxx',      -- GitHub AI
  moonshot = 'sk-xxxxxxxxxxxx',        -- Moonshot AI
  openrouter = 'sk-or-xxxxxxxx',       -- OpenRouter
  qwen = 'qwen-xxxxxxxx',              -- Alibaba Qwen (DashScope)
  aliyuncs = 'sk-xxxxxxxxxxxx',        -- Alibaba Cloud (Bailian)
  aliyuncs_coding_plan = 'sk-xxxxxxxxxxxx',  -- Alibaba Cloud Coding Plan (also used by aliyuncs_coding_plan_anthropic)
  siliconflow = 'xxxxxxxx-xxxx-xxxx',  -- SiliconFlow
  tencent = 'xxxxxxxx-xxxx-xxxx',      -- Tencent Hunyuan
  baidu = 'xxxxxxxx-xxxx-xxxx',        -- Baidu Qianfan
  bigmodel = 'xxxxxxxx-xxxx-xxxx',     -- BigModel AI (Zhipu)
  volcengine = 'xxxxxxxx-xxxx-xxxx',   -- Volcengine AI (Doubao)
  volcengine_coding_plan = 'uuid-xxxxxxxx',  -- Volcengine Coding Plan (or a list of keys)
  xiaomi = 'xxxxxxxx-xxxx-xxxx',       -- Xiaomi MiMo
  xiaomi_token_plan = 'xxxxxxxx-xxxx-xxxx', -- Xiaomi Token Plan
  openai = 'sk-xxxxxxxxxxxx',          -- OpenAI
  anthropic = 'sk-ant-xxxxxxxxxxxx',   -- Anthropic Claude
  gemini = 'AIxxxxxxxxxxxxxxxxxxxx',   -- Google Gemini
  longcat = 'lc-xxxxxxxxxxxx',         -- LongCat AI
  cherryin = 'sk-xxxxxxxxxxxx',        -- CherryIN AI
  yuanjing = 'xxxxxxxx-xxxx-xxxx',     -- Yuanjing AI
}

Only configure keys for providers you plan to use; others can be omitted.

Multiple API Keys per Provider (Rotation)

Each provider key accepts a single string (default) or a list of strings. With a list, requests are rotated round-robin across the keys. A key that fails with a rate limit (429), quota exhaustion or a server error (5xx) is put on cooldown and skipped automatically until it recovers:

api_key = {
  volcengine_coding_plan = {           -- multiple keys: rotated automatically
    'uuid-of-account-1',
    'uuid-of-account-2',
    'uuid-of-account-3',
  },
  deepseek = 'sk-xxxxxxxxxxxx',        -- single key keeps the old behavior
}
Option Type Default Description
token_cooldown number 30 Seconds a key is skipped after a rate-limit (429) or server (5xx) error
quota_cooldown number 3600 Seconds a key is skipped after a quota-exhaustion error (e.g. “已用完5小时总额度”)
  • Quota-exhaustion errors (e.g. volcengine “已用完5小时总额度”, Gemini RESOURCE_EXHAUSTED) cool a key for quota_cooldown because the quota window itself is long; plain rate limits only cool for token_cooldown
  • Rotation state is in-memory only; restarting Neovim resets it
  • When every key is cooling down, the key that recovers soonest is retried so the API error stays visible instead of failing silently

File Access Control

Control which file paths tools can access for security:

-- Option 1: Disable all file access (default)
allowed_path = ''

-- Option 2: Allow a single directory
allowed_path = '/home/user/projects'

-- Option 3: Allow multiple directories
allowed_path = {
  vim.fn.getcwd(),               -- Current working directory
  vim.fn.expand('~/.config/nvim'), -- Neovim config directory
  '/etc',                        -- System configuration files
}

Security Recommendations

  • Empty string disables all file access
  • Recommended to set to your current project directory for security
  • Only allow directories you trust tools to read/write

Context Window Configuration

Configure automatic context truncation to manage token usage:

context = {
  enable = true,           -- Enable/disable context truncation
  trigger_threshold = 50,  -- Number of messages to trigger truncation
  keep_recent = 10,        -- Keep recent N messages (not included in truncation search)
  slide_step = 0,          -- Advance the cutoff only once every N messages (cache-friendly)
}

Notes

  • When conversation exceeds trigger_threshold messages, older messages may be summarized or removed
  • The keep_recent parameter ensures recent context is preserved
  • Helps prevent token limit errors during long conversations
  • After truncation, the [Context Window Notice] is appended as the very last request message. Its counts change on every request, so at the tail it only invalidates the suffix of the prompt cache: every message the previous request sent stays byte-identical. Flows that inspect the last request message (auto-continue, tool-result resend, retry) strip the trailing notice first via context.strip_trailing_notice
  • slide_step > 1 batches the cutoff: it only advances once every slide_step messages, so the front of the kept window stays byte-identical while history grows and the provider’s prompt cache keeps matching across requests instead of breaking on every message (the probe logs that as reason=messages). The window then oscillates between keep_recent and keep_recent + slide_step messages, and the first truncation can happen a bit later than trigger_threshold. 0 (default) and 1 keep the legacy behavior of sliding the cutoff on every message

Prefix Cache Probe

Providers bill cached prompt tokens at a fraction of the normal price, but only while the request prefix stays byte-identical: system prompt + tools + the messages already sent. The probe fingerprints every request and reports the first position where it diverges from the previous request of the same session.

cache = {
  probe = true, -- log where consecutive requests stop sharing a prefix
}

Every request is compared against the previous one and logged as one of:

Reason Meaning
append the previous prefix is intact, only new messages were added
system the leading system block changed
tools the tools array changed (order or membership)
messages an already-sent message was rewritten, or the window moved
truncated the request got shorter than the previous one (windowing)

append is the healthy case for an ongoing turn; the others mean everything after the reported index has to be re-prefilled.

Frequent messages breaks at the very front of the history are the classic symptom of the sliding truncation window: the cutoff moves on every request, so each request starts at a new message. Setting context.slide_step > 1 batches the window movement and restores cache hits (see Context Window Configuration).

While truncation is active, a messages break at the very end of the request (right where the previous request ended) is expected and healthy: that position holds the previous request’s context notice, and only the suffix after the break is re-prefilled.

Reading the counters

local stats = require('chat.sessions').cache_stats(session_id)
-- stats.requests / stats.appends / stats.breaks
-- stats.breaks_per_request   cache invalidations per request
-- stats.prompt_tokens / stats.cached_tokens / stats.hit_ratio
-- stats.last_reason / stats.last_break_index

hit_ratio uses the provider-reported cache numbers (prompt_tokens_details.cached_tokens, cache_read_input_tokens, prompt_cache_hit_tokens) and stays 0 for providers that report none. Set cache.probe = false to disable all probe bookkeeping.

Where the numbers show up

Every surface reads usage through chat.usage, so the same payload is interpreted identically no matter which provider sent it:

  • completed-message footer in the result window: ✅ Completed • Tokens: 12.3K (10.0K↑/2.3K↓) 💾 45%
  • HTML preview (GET /session?id=<session_id> on the HTTP server): a Cached: N tokens (P%) line under the token count
  • cache_stats(session_id) (see above)

The 💾 / Cached: part is omitted when the provider reports no cache numbers, and total_tokens falls back to prompt_tokens + completion_tokens when the payload omits it.

Plugin authors can reuse the same normalization:

local usage = require('chat.usage')

usage.normalize(msg.usage)
-- { total_tokens, prompt_tokens, completion_tokens, cached_tokens }
usage.cached_tokens(msg.usage) -- cache field of any supported provider
usage.hit_ratio(msg.usage)     -- cached / prompt, 0..1
usage.sum(messages)            -- totals for a whole history
usage.summary(msg.usage)       -- "12.3K tokens · 45% cached"

Usage Statistics

Every finished request is counted once per provider/model, with tokens normalized through chat.usage (so provider-specific cache fields accumulate identically). Statistics are persisted to {storage_dir}/usage_stats.json in three layers with the same record shape (requests, total_tokens, prompt_tokens, completion_tokens, cached_tokens):

Layer Bucket key Retention (default) Purpose
total — never dropped all-time per provider/model totals
hourly YYYY-MM-DDTHH hourly_days = 7 short windows (“last 5 hours”)
daily YYYY-MM-DD daily_days = 365 longer windows (“last week / month”)
usage_stats = {
  enable = true,      -- set false to stop recording
  hourly_days = 7,    -- hourly buckets older than this are dropped
  daily_days = 365,   -- daily buckets older than this are dropped
}

Querying

local stats = require('chat.usage_stats')

stats.total()                 -- all-time [provider][model] = record
stats.range(os.time() - 5 * 3600)   -- last 5 hours (merges hourly buckets)
stats.range(os.time() - 7 * 86400)  -- last week (merges daily buckets)
stats.range(os.time() - 30 * 86400) -- last month (merges daily buckets)
stats.reset()                 -- clear everything

range(since) picks the layer automatically: spans under 48 hours merge hourly buckets, longer spans merge daily buckets. The bucket containing the window start is included whole, so a window may overshoot by at most one bucket. Bucket keys are fixed-width ISO strings, so lexicographic order is chronological and retention/vacuum is a plain string comparison — expired buckets are dropped lazily on the next record().

Accounting happens in sessions.on_complete (the same funnel that writes the usage footer message), so tool-call rounds and auto-continuation chains each count as one request, and failed requests (no usage reported) are not counted.


Memory System Configuration

chat.nvim implements a sophisticated three-tier memory system inspired by cognitive psychology.

Memory Architecture

  1. Working Memory ⚡ - High-priority, session-scoped memory for current tasks and decisions
  2. Daily Memory 📅 - Temporary memory for daily tasks and short-term goals (auto-expires)
  3. Long-term Memory 💾 - Permanent knowledge storage for facts, preferences, and skills

Configuration Example

memory = {
  enable = true,  -- Global memory system switch

  -- Long-term memory: Permanent knowledge (never expires)
  long_term = {
    enable = true,
    max_memories = 500,           -- Maximum memories to store
    retrieval_limit = 3,          -- Maximum memories to retrieve per query
    similarity_threshold = 0.3,   -- Text similarity threshold (0-1)
  },

  -- Daily memory: Temporary tasks and goals (auto-expires)
  daily = {
    enable = true,
    retention_days = 7,           -- Days before auto-deletion
    max_memories = 100,           -- Maximum daily memories
    similarity_threshold = 0.4,
  },

  -- Working memory: Current session focus (highest priority)
  working = {
    enable = true,
    max_memories = 20,            -- Maximum working memories per session
    priority_weight = 2.0,        -- Priority multiplier (higher = more important)
  },

  -- Storage location (optional, defaults to storage_dir .. 'memory/')
  -- storage_dir = '/custom/memory/path/',
}

memory.storage_dir defaults to nil, which means it is automatically derived from the top-level storage_dir (i.e., storage_dir .. 'memory/'). Only set this if you want to use a different location. See Storage Paths for details.

Memory Type Characteristics

Type Lifetime Priority Use Case
Working Session only Highest Current tasks, decisions, active context
Daily 7-30 days Medium Short-term goals, today’s tasks, reminders
Long-term Permanent Normal Facts, preferences, skills, knowledge

Auto-Detection

The @extract_memory tool automatically detects memory type based on keywords:

  • Working Memory: “当前/正在/current”, “任务/task”, “决策/decision”, “问题/issue”
  • Daily Memory: “今天/明天/today/tomorrow”, “待办/todo”, “临时/temporary”
  • Long-term Memory: Other persistent information

User Profile Configuration

chat.nvim supports user profiles (人物画像) for personalized AI assistance. Profiles store user preferences, skills, and background information as markdown files.

require('chat').setup({
  user = {
    enable = true,        -- Enable user profile system
    id = '',              -- User ID (auto-detected from system username if empty)
    -- storage_dir = '/custom/users/path/',  -- Optional, defaults to storage_dir .. 'users/'
  },
})
Option Type Default Description
user.enable boolean true Enable/disable user profile system
user.id string '' User ID (auto-detected from system username if empty)
user.storage_dir string nil (derived from storage_dir) Storage directory for user profile markdown files

user.storage_dir defaults to nil, which means it is automatically derived from the top-level storage_dir (i.e., storage_dir .. 'users/'). Only set this if you want to use a different location. See Storage Paths for details.

When enabled, the AI assistant can use the @user_profile tool to read, update, and manage user profiles, providing personalized and context-aware responses.


Skills Configuration

chat.nvim includes a skill (slash command) system that lets you type /name [args] in the prompt window to invoke commands without sending to the LLM. You can register custom skills via configuration:

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

Each skill spec contains:

Field Type Description
name string Unique identifier (used as /name)
description string Short description shown in /help
handler function function(args: string, ctx: table): string|ChatSkillResult|nil
complete function Optional completion function (args) -> string[]

You can also register skills at runtime via require('chat').register_skill(spec) and unregister with require('chat').unregister_skill(name).

See Usage > Skills for the list of built-in skills.


Auto-Retry Configuration

chat.nvim automatically retries LLM requests that fail due to connection errors or timeouts. This helps maintain stable conversations even with intermittent network issues.

retry = {
  max_retries = 3,       -- Maximum retry attempts per request (default: 3)
  retry_delay = 2000,    -- Delay between retries in milliseconds (default: 2000 = 2 seconds)
}

How It Works

  • When an LLM request fails with a retryable error (connection failure or timeout), an error message is appended to the session with a retry hint (e.g., Auto-retry 1/3 (2 remaining).)
  • The system then automatically schedules a retry after the configured delay
  • Retry count is per-session and reset on each new user message
  • During the retry delay period, is_in_progress() returns true, preventing new messages from being sent
  • The user can cancel a pending retry with Ctrl-C
  • On successful response, the retry count is immediately reset
  • When all auto-retries are exhausted, the error message includes Press r to retry manually.

Retryable Error Codes

The following curl exit codes are considered retryable:

Code Description
6 Couldn’t resolve host
7 Failed to connect to host
28 Operation timeout
35 SSL/TLS handshake failure
52 Empty reply from server
56 Failure with receiving data

HTTP errors (e.g., 400, 429, 500) are not retried, as they indicate API-level issues rather than network problems. (With multiple keys configured, 429/5xx/quota errors instead put the used key on cooldown and the next key is rotated in.)


Auto-Continuation Configuration

When a response is truncated because it hit the model’s max_tokens limit (finish reason length), chat.nvim can automatically continue it instead of losing the tail.

continuation = {
  enable = true,           -- Enable automatic continuation (default: true)
  max_continuations = 3,   -- Max continuation requests per response (default: 3)
}

How It Works

  • The truncated output is kept as an assistant message and the request is re-sent directly (no synthetic user message), so the model resumes from where it stopped.
  • Fragments from repeated continuations are merged into a single assistant message (required by Anthropic’s strict user/assistant role alternation).
  • The continuation budget is per-session and resets on a completed response or a new user message.
  • When the budget is exhausted, an Auto-continue limit reached (N). notice is appended and the truncated content stays in the history so you can continue manually.

system_prompt Usage Examples

Here are different ways to use the system_prompt option:

String (simple)

system_prompt = 'You are a helpful programming assistant.',

Function loading from file

system_prompt = function()
  local path = vim.fn.expand('~/.config/nvim/AGENTS.md')
  if vim.fn.filereadable(path) == 1 then
    return table.concat(vim.fn.readfile(path), '\n')
  end
  return 'Default system prompt'
end

Function with project-specific prompts

system_prompt = function()
  local cwd = vim.fn.getcwd()
  if string.find(cwd, 'chat%.nvim') then
    return 'You are a specialized assistant for chat.nvim plugin development.'
  elseif string.find(cwd, 'picker%.nvim') then
    return 'You are a specialized assistant for picker.nvim plugin development.'
  end
  return 'You are a general programming assistant.'
end

Function with time-based prompts

system_prompt = function()
  local hour = tonumber(os.date("%H"))
  local day = os.date("%A")
  return string.format('Good %s! Today is %s. I am your AI assistant.',
    hour < 12 and 'morning' or 'afternoon' or 'evening',
    day)
end

Complete Configuration Example

require('chat').setup({
  -- Window settings
  width = 0.8,
  height = 0.8,
  auto_scroll = true,
  border = 'rounded',

  -- AI provider settings
  provider = 'deepseek',
  model = 'deepseek-v4-flash',
  api_key = {
    deepseek = 'sk-xxxxxxxxxxxx',
    github = 'github_pat_xxxxxxxx',
  },

  -- Multi-key rotation cooldowns (seconds)
  token_cooldown = 30,
  quota_cooldown = 3600,

  -- HTTP server configuration
  http = {
    host = '127.0.0.1',
    port = 7777,
    api_key = 'your-secret-key-here',
  },

  -- File access control
  allowed_path = {
    vim.fn.getcwd(),
    vim.fn.expand('~/.config/nvim'),
  },

  -- Base storage directory for all persistent data
  -- Sub-modules (memory, user, plans, scheduler) auto-derive from this
  storage_dir = vim.fn.stdpath('data') .. '/chat.nvim/',

  -- Time format
  strftime = '%Y-%m-%d %H:%M',

  -- 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',
  },

  -- System prompt
  system_prompt = function()
    local path = vim.fn.expand('./AGENTS.md')
    if vim.fn.filereadable(path) == 1 then
      return table.concat(vim.fn.readfile(path), '\n')
    end
    return 'You are a helpful programming assistant.'
  end,

  -- Context truncation (cache-friendly window batching)
  context = {
    enable = true,
    trigger_threshold = 50,
    keep_recent = 10,
    slide_step = 40, -- window front only moves every 40 messages
  },

  -- Memory system
  memory = {
    enable = true,
    long_term = {
      max_memories = 500,
      retrieval_limit = 3,
    },
    daily = {
      retention_days = 7,
      max_memories = 100,
    },
    working = {
      max_memories = 20,
      priority_weight = 2.0,
    },
    -- storage_dir omitted: auto-derived from storage_dir .. 'memory/'
  },

  -- Auto-retry on connection errors and timeouts
  retry = {
    max_retries = 3,
    retry_delay = 2000,
  },

  -- Auto-continuation for responses truncated by max_tokens
  continuation = {
    enable = true,
    max_continuations = 3,
  },

  -- Prefix cache observability
  cache = {
    probe = true,
  },

  -- User profile system (人物画像)
  user = {
    enable = true,
    id = '',
    -- storage_dir omitted: auto-derived from storage_dir .. 'users/'
  },

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

  -- MCP servers (optional)
  mcp = {
    open_webSearch = {
      command = 'npx',
      args = { '-y', 'open-websearch@latest' },
    },
  },

  -- IM integrations (optional)
  integrations = {
    discord = {
      token = 'YOUR_DISCORD_BOT_TOKEN',
      channel_id = 'YOUR_CHANNEL_ID',
      -- Optional: more guild channels (each gets its own cursor + session)
      channel_ids = { 'ANOTHER_CHANNEL_ID' },
      -- Optional: register every text channel of this guild on connect
      guild_id = 'YOUR_GUILD_ID',
      -- Optional: private (DM) chats, one session + workspace per peer
      p2p = {
        enable = true,
        -- Omit `allow` to serve every DM channel the bot can see.
        allow = { 'USER_ID_ALLOWED_TO_DM' },
        -- Defaults to the first entry of `allowed_path`.
        cwd_root = '/path/to/projects',
      },
    },
  },
})

Configuration Notes

  1. Path Security: allowed_path restricts which file paths tools can access. Empty string disables all file access. Recommended to set to your current project directory for security.
  2. API Keys: Only configure keys for providers you plan to use. Providers can be switched at runtime via the picker. Each key can be a single string or a list of strings; lists are rotated round-robin and failing keys are put on cooldown automatically (see Multiple API Keys per Provider).
  3. Memory System: Enabled by default, automatically extracts facts and preferences from conversations. Can be disabled with memory.enable = false.
  4. HTTP Server: Configure http.api_key to enable the HTTP server. The server binds to localhost by default for security.
  5. Dynamic Updates: Some configurations (like provider and model) can be changed dynamically at runtime via the picker.
  6. Automatic Scrolling: The auto_scroll option controls whether the result window automatically scrolls to show new content. When enabled (default), it only scrolls if the cursor was already at the bottom, preventing interruptions when reviewing history.
  7. system_prompt Function Support: The system_prompt option can be either a string or a function that returns a string. When a function is provided, it is called each time a new session is created, allowing for dynamic prompts based on time, project context, or external files. The function should handle errors gracefully and return a string value.
  8. RenderMarkdown: The render_markdown option enables/disables the RenderMarkdown plugin for the result buffer. Defaults to true. Set to false if you prefer plain markdown syntax highlighting without rich rendering.
  9. Auto-Retry: The retry option configures automatic retry of LLM requests on connection errors and timeouts. When a retryable error occurs, an error message with retry status is appended to the session (e.g., Auto-retry 1/3 (2 remaining).). When all retries are exhausted, the message includes Press r to retry manually. Retries are per-session and reset on each new user message. Only network-level errors are retried; HTTP errors (400, 429, 500, etc.) are not.
  10. Storage Paths: All persistent data is stored under storage_dir (defaults to stdpath('data')/chat.nvim/). Sub-module directories (memory.storage_dir, user.storage_dir, plans, scheduler) are automatically derived from storage_dir unless explicitly overridden. See Storage Paths for the full derivation table.
  11. User Profiles: The user option configures the user profile system (人物画像). When enabled, the AI can use @user_profile to read and update user profiles for personalized assistance. Profiles are stored as markdown files under user.storage_dir (auto-derived from storage_dir if not set).
  12. Skills: The skills option allows registering custom slash commands. Type /name [args] in the prompt window to invoke a skill without sending to the LLM. Built-in skills include /clear, /new, /delete, /model, /provider, /cwd, /pin, /title, /retry, and /help. See Usage > Skills for details.
  13. Auto-Continuation: The continuation option configures automatic continuation of responses truncated by max_tokens (finish reason length). The truncated content is kept as an assistant message and the request is re-sent directly (no synthetic user message) until the response completes or the budget is exhausted.
  14. Context Truncation: The context option configures automatic context truncation. trigger_threshold starts truncation, keep_recent protects the newest messages, and slide_step > 1 batches the cutoff so the window front stays byte-identical between steps, keeping the provider’s prompt cache valid (the cache probe logs sliding-window breaks as reason=messages).


Next Steps