Performance & Architecture

Boring is designed for maximum efficiency in large-scale projects. This document explains the performance-focused architecture and optimization strategies.

🚀 Incremental Verification

Smart Caching System

Boring maintains a verification cache at .boring/cache/verification.json that stores file hashes. This enables:

100+ unchanged files → Re-verification in < 2 seconds
Only changed files are re-analyzed
Cache invalidation is automatic on file modification

# Normal verification (uses cache)
boring verify

# Force full verification (bypass cache)
boring verify --force

Performance Metrics (v10.28.0)

Operation	v10.24 (Legacy)	v10.28 (Diet)	Speedup
Cold Helper Start	~2,500ms	~575ms	~4.3x
Tool Profile Load	~800ms	< 100ms	8x
Full Index Search	~4s	~2s	2x
Verify (Cached)	~5s	~3s	1.6x

The "Boring Diet" & V13.1 Optimizations

Boring V13.1 further optimizes the startup path and execution efficiency: - Universal Lazy Loading: New lazy_loader.py ensures heavy modules (Local LLM, Vector Stores) are only loaded when explicitly called. - Configurable Cache TTL: RAG query caches now support custom Time-To-Live (TTL), defaulting to 120s via BORING_CACHE_TTL_SECONDS. - Background Pre-warming: Modules can be pre-warmed in the background to eliminate the perceived delay during first use. - Startup Profiling: Enable BORING_STARTUP_PROFILE=1 to see detailed timing for component initialization.

Enable via .boring.toml or env BORING_MCP_PROFILE=lite.

🧠 Incremental RAG Indexing

State Tracking

RAG indexing uses content hashing to track changes:

# Incremental index (default - only changed files)
boring rag index

# Full re-index
boring rag index --force

Auto-Update with RAGWatcher (V10.18+)

Starting from V10.18.3, RAGWatcher automatically detects file changes and triggers incremental re-indexing:

# Automatic - no manual commands needed
# RAGWatcher runs in background during boring start

⚡ Parallel Verification (V10.13+)

Thread Pool Architecture

Boring uses ThreadPoolExecutor for concurrent checks:

┌─────────────────────────────────────────┐
│           Verification Engine           │
├─────────────────────────────────────────┤
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐    │
│  │ T1  │  │ T2  │  │ T3  │  │ T4  │    │
│  │Lint │  │Test │  │Type │  │Sec  │    │
│  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘    │
│     └────────┴────────┴────────┘       │
│              Aggregator                 │
└─────────────────────────────────────────┘

Performance Gains

Project Size	Sequential	Parallel (4 threads)	Speedup
Small (50 files)	15s	8s	1.9x
Medium (200 files)	45s	15s	3x
Large (500+ files)	120s	30s	4x

🔄 Provider Switching

Polyglot Architecture

Boring supports multiple AI providers with automatic detection:

Provider	API Key Required	Best For
Gemini CLI	❌	General development
Claude Code CLI	❌	Complex reasoning
Ollama (Local)	❌	Privacy-sensitive
SDK Mode	✅	Custom integration

# Auto-detection at startup
boring start

# Explicit provider
boring start --provider gemini-cli
boring start --provider claude-code
boring start --provider ollama

📊 Quality Trend Tracking

History Recording

Audit scores are stored in .boring/brain/quality_history.json:

{
  "2024-01-01": {"score": 4.2, "issues": 15},
  "2024-01-02": {"score": 4.5, "issues": 10},
  "2024-01-03": {"score": 4.8, "issues": 5}
}

Visualization

# ASCII trend chart
boring_quality_trend --days 30

Quality Score Trend (Last 30 Days)
5.0 |                    ████████
4.5 |          ████████████
4.0 |  ██████████
3.5 |██
    └───────────────────────────────
       Jan 1       Jan 15       Jan 30

🛠️ Configuration

Project-Level Settings (.boring.toml)

[boring.performance]
parallel_workers = 4          # Thread count
verification_cache = true     # Enable caching
incremental_rag = true        # Auto RAG updates

[boring.timeouts]
api_call = 60                 # Seconds
verification = 300            # Seconds