Configuration
Table of contents
- Basic Options
- Prompt Placeholder
- Storage Paths
- Tool Loading Configuration
- HTTP Server Configuration
- API Key Configuration
- File Access Control
- Context Window Configuration
- Prefix Cache Probe
- Usage Statistics
- Memory System Configuration
- User Profile Configuration
- Skills Configuration
- Auto-Retry Configuration
- Auto-Continuation Configuration
- system_prompt Usage Examples
- Complete Configuration Example
- Configuration Notes
- Next Steps
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_diroruser.storage_dirisnil(the default), they are automatically derived fromstorage_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_tooltool 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_toollast). Lazily loaded tools are placed on first appearance — tools called in the turn first (call order), then tools activated viafind_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_keyis not empty- Incoming requests must include the API key in the
X-API-Keyheader- 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 forquota_cooldownbecause the quota window itself is long; plain rate limits only cool fortoken_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_thresholdmessages, older messages may be summarized or removed - The
keep_recentparameter 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 viacontext.strip_trailing_notice slide_step > 1batches the cutoff: it only advances once everyslide_stepmessages, 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 asreason=messages). The window then oscillates betweenkeep_recentandkeep_recent + slide_stepmessages, and the first truncation can happen a bit later thantrigger_threshold.0(default) and1keep 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): aCached: 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
- Working Memory ⚡ - High-priority, session-scoped memory for current tasks and decisions
- Daily Memory 📅 - Temporary memory for daily tasks and short-term goals (auto-expires)
- 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_dirdefaults tonil, which means it is automatically derived from the top-levelstorage_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_dirdefaults tonil, which means it is automatically derived from the top-levelstorage_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()returnstrue, 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
- Path Security:
allowed_pathrestricts which file paths tools can access. Empty string disables all file access. Recommended to set to your current project directory for security.- 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).
- Memory System: Enabled by default, automatically extracts facts and preferences from conversations. Can be disabled with
memory.enable = false.- HTTP Server: Configure
http.api_keyto enable the HTTP server. The server binds to localhost by default for security.- Dynamic Updates: Some configurations (like provider and model) can be changed dynamically at runtime via the picker.
- Automatic Scrolling: The
auto_scrolloption 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.- system_prompt Function Support: The
system_promptoption 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.- RenderMarkdown: The
render_markdownoption enables/disables the RenderMarkdown plugin for the result buffer. Defaults totrue. Set tofalseif you prefer plain markdown syntax highlighting without rich rendering.- Auto-Retry: The
retryoption 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 includesPress 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.- Storage Paths: All persistent data is stored under
storage_dir(defaults tostdpath('data')/chat.nvim/). Sub-module directories (memory.storage_dir,user.storage_dir, plans, scheduler) are automatically derived fromstorage_dirunless explicitly overridden. See Storage Paths for the full derivation table.- User Profiles: The
useroption configures the user profile system (人物画像). When enabled, the AI can use@user_profileto read and update user profiles for personalized assistance. Profiles are stored as markdown files underuser.storage_dir(auto-derived fromstorage_dirif not set).- Skills: The
skillsoption 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.- Auto-Continuation: The
continuationoption configures automatic continuation of responses truncated bymax_tokens(finish reasonlength). 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.- Context Truncation: The
contextoption configures automatic context truncation.trigger_thresholdstarts truncation,keep_recentprotects the newest messages, andslide_step > 1batches 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 asreason=messages).
Next Steps
- Usage Guide - Learn how to use chat.nvim
- Providers - Configure AI providers
- Tools - Explore available tools