VectorLint Configuration Guide

July 24, 2026 · View on GitHub

A comprehensive reference for configuring VectorLint using.vectorlint.ini.

Configuration File

VectorLint is configured via a .vectorlint.ini file in the root of your project. This file defines global settings, file associations, and rule overrides.

Complete Example

# .vectorlint.ini

# [Global Settings]
# Optional: Path to custom rules directory
# If omitted, only preset rules (from RunRules) are used
# RulesPath=.github/rules
# Number of concurrent reviews (Default: 4)
Concurrency=4
# Default severity for violations (Default: warning)
DefaultSeverity=warning

# [File Patterns]
# Map file patterns to rule packs and apply overrides

# All markdown files - run "Acme" rule pack
[**/*.md]
RunRules=Acme
# Override strictness for the GrammarChecker rule
GrammarChecker.strictness=7

# Technical documentation - run "Acme" pack with higher standards
[content/docs/**/*.md]
RunRules=Acme
# Higher strictness for docs
GrammarChecker.strictness=9

# Marketing content - run "TechCorp" pack
[content/marketing/**/*.md]
RunRules=TechCorp
BrandVoice.strictness=8

# Drafts - skip all rules
[content/drafts/**/*.md]
RunRules=

Global Settings

These settings control the application's core behavior.

SettingTypeDefaultDescription
RulesPathstring(none)Root directory for custom rule packs. If omitted, only presets are used.
Concurrencyinteger4Number of concurrent reviews to run.
DefaultSeveritystringwarningDefault severity level (warning or error) for reported issues.

Global Style Guide (VECTORLINT.md)

You can place a VECTORLINT.md file in your project root to define global style instructions.

Zero-Config Mode

If no .vectorlint.ini exists, VectorLint will automatically:

  1. Detect VECTORLINT.md
  2. Create a synthetic "Style Guide Compliance" rule
  3. Review your contents against it

Combined Mode

If you have configured rules (via .vectorlint.ini), the content of VECTORLINT.md is prepended to the system prompt for every review. This ensures your global style preferences (tone, terminology) are respected across all specific rules.

Note: Keep VECTORLINT.md concise. VectorLint will emit a warning if the file exceeds ~4,000 tokens, as very large contexts can degrade performance and increase costs.

LLM Providers

VectorLint relies on an LLM provider. Configure it globally in ~/.vectorlint/config.toml, or at project scope using a .env file (which takes precedence).

You can generate these files using the vectorlint init command.

VectorLint supports multiple LLM providers. Set LLM_PROVIDER to your desired provider (e.g., openai, anthropic, gemini) and provide the corresponding API key.

Observability

VectorLint can optionally emit AI execution telemetry to Langfuse. The first implementation is scoped to the Vercel AI SDK calls made through VercelAIProvider.

Example configuration for Langfuse:

OBSERVABILITY_BACKEND=langfuse
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
# Optional for self-hosted Langfuse. Defaults to cloud.langfuse.com.
LANGFUSE_BASE_URL=https://cloud.langfuse.com
  • Observability is best-effort and non-blocking.
  • If initialization or shutdown fails, VectorLint logs a warning and continues.
  • Prompts and outputs are recorded when Langfuse observability is enabled.

False-Positive Filtering (PAT)

VectorLint uses PAT (Pay A Tax) style gate checks to reduce false positives. The model may return many raw candidates, but only candidates that pass deterministic gate checks are surfaced in CLI output.

You can tune the confidence gate with an environment variable:

CONFIDENCE_THRESHOLD=0.75
  • Default: 0.75
  • Applies to surfaced violations
  • Invalid values gracefully fall back to the default

File Pattern Sections

VectorLint uses [glob/pattern] sections to map specific files to rule packs.

Syntax

[glob/pattern]
RunRules=PackName, AnotherPack
  • Pattern: A standard glob pattern (e.g., **/*.md, content/docs/**/*.md).
  • RunRules: A comma-separated list of rule pack names to run on matching files.
    • Use company names (e.g., Acme, TechCorp) if your rules are organized that way.
    • Leave empty (RunRules=) to explicitly skip rules for these files.

Directory Structure

The RulesPath setting defines the root directory where VectorLint looks for rule packs. The subdirectories inside RulesPath become the available "PackNames".

Example Layout:

project/
├── .github/rules/           ← Configured as RulesPath
│   ├── Acme/                ← Rule Pack: "Acme"
│   │   ├── grammar.md
│   │   └── style.md
│   └── TechCorp/            ← Rule Pack: "TechCorp"
│       └── brand.md
└── .vectorlint.ini

In this example, VectorLint sees two available packs: Acme and TechCorp.

  • Files in .github/rules/Acme/ become rules in the Acme pack.
  • To use them, you set RunRules=Acme in your config.

Order of Appearance

Cascading Configuration

VectorLint uses a "Cascading" logic (similar to Vale.sh) to determine which configuration applies to a file.

  1. General to Specific: All configuration blocks that match a file are applied, starting with general patterns and ending with specific ones.
  2. What happens:
    • Rule Packs: A file runs rules from all matching patterns.
    • Settings: More specific patterns override general ones.
  3. Specificity:
    • General: Patterns with fewer path segments or more wildcards (e.g., *.md).
    • Specific: Patterns with more path segments or exact names (e.g., content/docs/api.md).

Example

# General (Applied FIRST)
[**/*.md]
RunRules=GeneralRules
Grammar.strictness=5

# Specific (Applied SECOND, overrides General)
# MATCHES: content/docs/api.md
# RESULT: Runs "GeneralRules" AND "TechDocs". strictness is 9 (overrides 5).
[content/docs/**/*.md]
RunRules=TechDocs
Grammar.strictness=9

You can configure the strictness of check rules (like Grammar or AI Detection) to control how they score content. Strictness determines the penalty weight for error density.

Syntax

[pattern]
RuleID.strictness=value

Values

You can use named levels or direct numeric multipliers:

  • 1-3 or lenient: ~5 points penalty per 1% error density. (Drafts)
  • 4-7 or standard: ~10 points penalty per 1% error density. (General Content)
  • 8-10 or strict: ~20 points penalty per 1% error density. (Technical Docs)

Example:

[content/docs/**/*.md]
RunRules=Acme
GrammarChecker.strictness=strict
Terminology.strictness=20

See Also