Skip to content

Configuration

Jump to bottom
Lisa edited this page Dec 18, 2025 · 21 revisions

CKB Configuration Guide

Overview

CKB configuration is stored in .ckb/config.json in your repository root. This file is created when you run ckb init.

Note: The v6.0 Architectural Memory features (ownership, decisions, hotspots) are implemented but currently use sensible defaults. Configurable settings for these features are planned for a future release. See v6.0 Configuration Roadmap below.

Configuration File

Location

your-repo/
└── .ckb/
    ├── config.json    # Configuration
    └── ckb.db         # SQLite database

Full Schema (Current Implementation)

{
  "version": 5,
  "repoRoot": ".",
  "backends": {
    "scip": {
      "enabled": true,
      "indexPath": ".scip/index.scip"
    },
    "lsp": {
      "enabled": true,
      "workspaceStrategy": "repo-root",
      "servers": {}
    },
    "git": {
      "enabled": true
    }
  },
  "queryPolicy": {
    "backendPreferenceOrder": ["scip", "glean", "lsp"],
    "alwaysUse": ["git"],
    "maxInFlightPerBackend": { "scip": 10, "lsp": 3, "git": 5 },
    "coalesceWindowMs": 50,
    "mergeMode": "prefer-first",
    "supplementThreshold": 0.8,
    "timeoutMs": { "scip": 5000, "lsp": 15000, "git": 5000 }
  },
  "lspSupervisor": {
    "maxTotalProcesses": 4,
    "queueSizePerLanguage": 10,
    "maxQueueWaitMs": 200
  },
  "modules": {
    "detection": "auto",
    "roots": [],
    "ignore": ["node_modules", "build", ".dart_tool", "vendor"]
  },
  "importScan": {
    "enabled": true,
    "maxFileSizeBytes": 1000000,
    "scanTimeoutMs": 30000,
    "skipBinary": true,
    "customPatterns": {}
  },
  "cache": {
    "queryTtlSeconds": 300,
    "viewTtlSeconds": 3600,
    "negativeTtlSeconds": 60
  },
  "budget": {
    "maxModules": 10,
    "maxSymbolsPerModule": 5,
    "maxImpactItems": 20,
    "maxDrilldowns": 5,
    "estimatedMaxTokens": 4000
  },
  "backendLimits": {
    "maxRefsPerQuery": 10000,
    "maxFilesScanned": 5000,
    "maxUnionModeTimeMs": 60000
  },
  "privacy": {
    "mode": "normal"
  },
  "logging": {
    "level": "info",
    "format": "human"
  }
}

Configuration Sections

version

Schema version number. Current version is 5.

{
  "version": 5
}

repoRoot

Root directory for the repository. Usually ".".

{
  "repoRoot": "."
}

backends

Configure which backends are enabled and their settings.

backends.scip

SCIP (Source Code Intelligence Protocol) backend.

Field Type Default Description
enabled bool true Enable SCIP backend
indexPath string ".scip/index.scip" Path to SCIP index file 
{
  "backends": {
    "scip": {
      "enabled": true,
      "indexPath": ".scip/index.scip"
    }
  }
}

backends.lsp

Language Server Protocol backend.

Field Type Default Description
enabled bool true Enable LSP backend
workspaceStrategy string "repo-root" How to initialize workspace
servers object {...} Language-specific server configs

Default servers configured:

  • go: gopls
  • typescript: typescript-language-server
  • dart: dart language-server
  • python: pylsp
{
  "backends": {
    "lsp": {
      "enabled": true,
      "workspaceStrategy": "repo-root",
      "servers": {
        "go": {
          "command": "gopls",
          "args": []
        },
        "typescript": {
          "command": "typescript-language-server",
          "args": ["--stdio"]
        },
        "dart": {
          "command": "dart",
          "args": ["language-server"]
        },
        "python": {
          "command": "pylsp",
          "args": []
        }
      }
    }
  }
}

backends.git

Git backend for blame, history, and fallback operations.

Field Type Default Description
enabled bool true Enable Git backend

queryPolicy

Controls how queries are routed to backends and how results are merged.

Field Type Default Description
backendPreferenceOrder string[] ["scip", "glean", "lsp"] Backend priority order
alwaysUse string[] ["git"] Backends to always query
maxInFlightPerBackend object {...} Max concurrent queries per backend
coalesceWindowMs int 50 Window for coalescing similar queries
mergeMode string "prefer-first" How to merge results
supplementThreshold float 0.8 When to supplement with additional backends
timeoutMs object {...} Timeout per backend in milliseconds

Merge Modes:

  • prefer-first: Use first successful backend response
  • union: Merge all backend responses, deduplicate
{
  "queryPolicy": {
    "backendPreferenceOrder": ["scip", "lsp"],
    "alwaysUse": ["git"],
    "maxInFlightPerBackend": {
      "scip": 10,
      "lsp": 3,
      "git": 5
    },
    "coalesceWindowMs": 50,
    "mergeMode": "prefer-first",
    "supplementThreshold": 0.8,
    "timeoutMs": {
      "scip": 5000,
      "lsp": 15000,
      "git": 5000
    }
  }
}

lspSupervisor

Controls LSP server lifecycle and resource management.

Field Type Default Description
maxTotalProcesses int 4 Max LSP processes across all languages
queueSizePerLanguage int 10 Max queued requests per language
maxQueueWaitMs int 200 Max time to wait in queue 
{
  "lspSupervisor": {
    "maxTotalProcesses": 4,
    "queueSizePerLanguage": 10,
    "maxQueueWaitMs": 200
  }
}

modules

Module detection settings.

Field Type Default Description
detection string "auto" Detection strategy
roots string[] [] Additional module roots to include
ignore string[] [...] Directories to ignore

Detection Strategies:

  • auto: Detect based on language markers (go.mod, package.json, etc.)
  • manual: Only use specified roots
  • directory: Treat each top-level directory as a module

Default ignore patterns:

  • node_modules
  • build
  • .dart_tool
  • vendor
{
  "modules": {
    "detection": "auto",
    "roots": ["internal/legacy"],
    "ignore": ["node_modules", "build", ".dart_tool", "vendor", "dist"]
  }
}

importScan

Import/dependency scanning settings.

Field Type Default Description
enabled bool true Enable import scanning
maxFileSizeBytes int 1000000 Skip files larger than this (1 MB)
scanTimeoutMs int 30000 Timeout for scanning (30s)
skipBinary bool true Skip binary files
customPatterns object {} Custom import patterns by language 
{
  "importScan": {
    "enabled": true,
    "maxFileSizeBytes": 1000000,
    "scanTimeoutMs": 30000,
    "skipBinary": true,
    "customPatterns": {}
  }
}

cache

Cache tier configuration.

Field Type Default Description
queryTtlSeconds int 300 Query cache TTL (5 min)
viewTtlSeconds int 3600 View cache TTL (1 hour)
negativeTtlSeconds int 60 Negative cache TTL (1 min) 
{
  "cache": {
    "queryTtlSeconds": 300,
    "viewTtlSeconds": 3600,
    "negativeTtlSeconds": 60
  }
}

budget

Response budget limits for LLM optimization.

Field Type Default Description
maxModules int 10 Max modules in response
maxSymbolsPerModule int 5 Max symbols per module
maxImpactItems int 20 Max impact items
maxDrilldowns int 5 Max drilldown suggestions
estimatedMaxTokens int 4000 Target token budget 
{
  "budget": {
    "maxModules": 10,
    "maxSymbolsPerModule": 5,
    "maxImpactItems": 20,
    "maxDrilldowns": 5,
    "estimatedMaxTokens": 4000
  }
}

backendLimits

Hard limits to protect against resource exhaustion.

Field Type Default Description
maxRefsPerQuery int 10000 Max references per query
maxFilesScanned int 5000 Max files to scan
maxUnionModeTimeMs int 60000 Max time for union merge (60s) 
{
  "backendLimits": {
    "maxRefsPerQuery": 10000,
    "maxFilesScanned": 5000,
    "maxUnionModeTimeMs": 60000
  }
}

privacy

Privacy settings.

Field Type Default Description
mode string "normal" Privacy mode

Privacy Modes:

  • normal: Full output with paths and symbols
  • redacted: Paths and symbol names are hashed
{
  "privacy": {
    "mode": "normal"
  }
}

logging

Logging configuration.

Field Type Default Description
level string "info" Log level (debug, info, warn, error)
format string "human" Output format (human, json) 
{
  "logging": {
    "level": "info",
    "format": "human"
  }
}

CLI Command Flags

Each CLI command has specific flags. Use --help to see all options:

ckb --help           # Global help
ckb search --help    # Search command help
ckb serve --help     # Server command help

Common Command Flags

ckb search

Flag Default Description
--scope "" Limit to module ID
--kinds "" Filter by kinds (comma-separated)
--limit 20 Max results
--format "json" Output format (json, human)

ckb refs

Flag Default Description
--format "json" Output format

ckb impact

Flag Default Description
--format "json" Output format

ckb arch

Flag Default Description
--format "json" Output format
--depth 1 Dependency depth

ckb serve

Flag Default Description
--port 8080 HTTP port
--host "localhost" Bind address

ckb diag

Flag Default Description
--out "" Output file path
--anonymize false Anonymize paths and symbols

Environment Variables

Configuration can be overridden with environment variables:

Variable Description
CKB_LOG_LEVEL Override log level
CKB_LOG_FORMAT Override log format
CKB_CONFIG_PATH Custom config file path

Examples

Minimal Configuration

{
  "version": 5,
  "backends": {
    "scip": { "enabled": true },
    "lsp": { "enabled": false },
    "git": { "enabled": true }
  }
}

SCIP-Only (Fastest)

{
  "version": 5,
  "backends": {
    "scip": { "enabled": true },
    "lsp": { "enabled": false },
    "git": { "enabled": true }
  },
  "queryPolicy": {
    "backendPreferenceOrder": ["scip"],
    "alwaysUse": ["git"],
    "mergeMode": "prefer-first"
  }
}

Large Codebase

{
  "version": 5,
  "budget": {
    "maxModules": 20,
    "maxSymbolsPerModule": 10,
    "maxImpactItems": 50,
    "estimatedMaxTokens": 8000
  },
  "backendLimits": {
    "maxRefsPerQuery": 50000,
    "maxFilesScanned": 20000
  },
  "cache": {
    "queryTtlSeconds": 600,
    "viewTtlSeconds": 7200
  }
}

Privacy-Focused

{
  "version": 5,
  "privacy": {
    "mode": "redacted"
  },
  "logging": {
    "level": "warn"
  }
}

MODULES.toml Format

The MODULES.toml file allows you to explicitly declare module boundaries and metadata. Place this file in your repository root.

Note: Module declarations in MODULES.toml take priority over auto-detection and provide higher confidence scores.

Basic Structure

# MODULES.toml - Explicit module declarations for CKB

[modules.internal/api]
responsibility = "HTTP API handlers and middleware"
owner = "@api-team"
tags = ["core", "api"]
public = ["Handler", "Router", "Middleware"]
internal = ["helper*", "private*"]

[modules.internal/storage]
responsibility = "Database operations and persistence"
owner = "@platform-team"
tags = ["core", "database"]
public = ["Repository", "Query", "Transaction"]

[modules.internal/auth]
responsibility = "Authentication and authorization"
owner = "@security-team"
tags = ["security", "core"]
public = ["Authenticator", "Authorizer", "Token*"]

Module Fields

Field Type Description
responsibility string One-sentence description of what the module does
owner string Primary owner (@team or @username)
tags string[] Classification tags for filtering
public string[] Glob patterns for public exports
internal string[] Glob patterns for internal-only symbols

Benefits of Explicit Declaration

  1. Higher confidence - Declared modules have confidence 1.0 vs 0.5-0.7 for inferred
  2. Preserved on refresh - Declared data is never overwritten by inference
  3. Better ownership - Explicit owners override git-blame heuristics
  4. Clearer boundaries - Public/internal patterns define module contracts

v6.0 Configuration Roadmap

The v6.0 Architectural Memory features are implemented and working, but currently use hardcoded defaults. Future releases will add configurable settings:

Planned: ownership

{
  "ownership": {
    "enabled": true,
    "codeownersPath": ".github/CODEOWNERS",
    "gitBlameEnabled": true,
    "timeDecayHalfLife": 90,
    "excludeBots": true,
    "botPatterns": ["\\[bot\\]$", "^dependabot", "^renovate"]
  }
}

Current defaults:

  • CODEOWNERS: .github/CODEOWNERS or CODEOWNERS
  • Git blame: enabled with 90-day half-life
  • Bot exclusion: enabled

Planned: decisions

{
  "decisions": {
    "enabled": true,
    "directories": ["docs/decisions", "docs/adr", "adr", "decisions"],
    "storePath": "~/.ckb/repos/{repo}/decisions"
  }
}

Current defaults:

  • Scans common ADR directories
  • Stores new ADRs in CKB data directory

Planned: staleness

{
  "staleness": {
    "freshDays": 7,
    "freshCommits": 50,
    "staleDays": 30,
    "staleCommits": 200,
    "obsoleteDays": 90,
    "obsoleteCommits": 500
  }
}

Current defaults:

  • Fresh: <7 days or <50 commits
  • Stale: 30-90 days or 200-500 commits
  • Obsolete: >90 days or >500 commits

Validation

Validate your configuration:

ckb doctor

This checks:

  • JSON syntax
  • Schema version compatibility
  • Required fields
  • Value ranges
  • Backend availability
  • MODULES.toml syntax

Clone this wiki locally