Skip to content

verlato.json

Verlato reads verlato.json from the repository root (or the file named by VERLATO_CONFIG_PATH). Every key is optional; without the file, the defaults below apply. Environment variables override the file, and command-line options override both. A complete example is verlato.sample.json (also served to MCP clients as verlato://sample-config).

{
  "diff_engine": "intentumdiff",
  "model_privacy": "metadata-only",
  "provider": {"name": "ollama", "model": "gemma4:latest"},
  "suggestion_tone": "release-note",
  "suggestion_style": {"project_vocabulary": ["Release Control"], "banned_phrases": ["various improvements"]},
  "targets": {
    "changelog": {"path": "CHANGELOG.md", "format": "changelog"},
    "github-release": {"path": ".github/release.md", "format": "github-release"}
  }
}

Evidence and state

Key Default Meaning
state_path .verlato_state.json where items, review decisions, publication and feedback are kept
diff_engine intentumdiff intentumdiff (semantic review) or git (legacy text patches)
semantic_cache_path .verlato_semantic_cache.json per-commit semantic review cache
semantic_parallelism up to 4 threads for reviewing uncached commits
semantic_cross_file false detect symbols moved or renamed between files (commit-wide; roughly doubles review time)
semantic_max_nodes engine default (100,000) raise the engine's size limit, in tree nodes, so very large files (over about 10,000 lines) are reviewed instead of reported as too_large
commit_intent_inference off low-signal infers Conventional Commit intent for vague commits (details)
feedback_include_text false keep accepted and edited summary text in feedback events
summary_style prose how a summary is written without a model: prose, a release-note sentence ("Renamed open_tasks to pending (possible breaking change)."), or evidence, the diagnostic evidence summary Verlato 0.1 used (details)

Models

Key Default Meaning
model_privacy metadata-only metadata-only, local-summary-then-ai or trusted-provider-patch (Privacy modes)
provider {"name": "ollama"} the model provider; see below

provider

Key Applies to Meaning
name all stub, mock, ollama (default), litellm, plugin, github-copilot, codex-cli, claude-code
model all the model (Ollama default gemma4:latest; LiteLLM default ollama/gemma4:latest)
suggest_model Ollama, LiteLLM, plugin a different model for suggestions only
endpoint Ollama, LiteLLM, GitHub Models the chat endpoint
timeout_seconds all per request (Ollama 15, LiteLLM and plugins 30, CLI agents 120)
api_key_env LiteLLM name of the environment variable holding the API key
keep_alive Ollama how long Ollama keeps the model loaded (10m; null for Ollama's default)
num_ctx Ollama context window
num_predict Ollama, LiteLLM global output cap (LiteLLM: max_tokens, default 1024; 0 sends none)
summary_num_predict, classify_num_predict, suggest_num_predict Ollama per-task output caps (180, 24, adaptive)
suggest_think Ollama allow thinking on suggestion requests (false)
max_items_per_scan all above this many changesets, model calls are skipped for the scan (25; -1 disables)
plugin_manifest plugin id, display_name, command, config_schema, capabilities
plugin_command (or command) plugin the command, as a list or a shell-style string (overrides the manifest's)
plugin_config plugin passed to the plugin as config
plugin_env plugin names of environment variables passed through to the plugin
fallbacks all providers to try in order when this one fails; each object inherits these settings and overrides what it names (details)

Suggestions

Key Default Meaning
suggestion_strategy auto auto, single, paired, full-diff-json, tool-retrieval (strategies)
suggestion_count 1 suggestions per item (1-5)
suggestion_parallelism 1 items suggested at once (1-8)
suggestion_batch_size 5 items per structured request (1-5)
suggestion_prompt_profile conservative conservative, lean or minimal
suggestion_adaptive_recommendations false include tuning advice in suggestion previews and doctor ollama
suggestion_tone release-note release-note, concise, technical or customer-facing
suggestion_style guidance, project_vocabulary, banned_phrases, specificity_floor (Writing style)
suggestion_cache_backend json the only backend
suggestion_cache_path .verlato_suggestion_cache.json the suggestion cache
suggestion_cache_ttl_days 30 days before cached suggestions expire

targets

Release-note files that draft apply can write. Each target has a path (relative to the repository root) and a format:

Format Output
changelog Keep a Changelog-style entries
github-release GitHub release notes

The built-in targets are changelog (CHANGELOG.md) and github-release (.github/release.md). A targets object replaces that list, so name every target you use; each needs both path and format:

{
  "targets": {
    "changelog": {"path": "docs/CHANGELOG.md", "format": "changelog"},
    "github-release": {"path": ".github/release.md", "format": "github-release"},
    "website": {"path": "site/releases.md", "format": "github-release"}
  }
}

verlato draft apply --target and the MCP verlato_apply_draft tool accept changelog and github-release (use --file / file for any other path); the editor service's draft.apply accepts any configured target name.