Skip to content

User Guide

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

CKB User Guide

Introduction

CKB (Code Knowledge Backend) is a tool that helps AI assistants understand your codebase. It provides a unified interface to query code intelligence from multiple backends (SCIP, LSP, Git) and returns optimized responses designed for LLM context windows.

Getting Started

Prerequisites

  • Go 1.21 or later
  • Git repository
  • (Optional) SCIP index for your project
  • (Optional) Language server for your project's language

Installation

# Build from source
git clone https://github.com/SimplyLiz/CodeMCP.git
cd CodeMCP
go build -o ckb ./cmd/ckb

# Add to PATH or move to /usr/local/bin
mv ckb /usr/local/bin/

Initialize Your Project

Navigate to your project root and initialize CKB:

cd /path/to/your/project
ckb init

This creates a .ckb/ directory with:

  • config.json - Configuration file
  • ckb.db - SQLite database for caching and symbol mappings

Verify Setup

# Check system status
ckb status

# Run diagnostics
ckb doctor

Core Concepts

Stable Symbol IDs

CKB assigns stable IDs to symbols that survive refactoring:

ckb:myrepo:sym:a1b2c3d4e5f6...

When a symbol is renamed, CKB creates an alias from the old ID to the new one, so references using the old ID continue to work.

Repository State

CKB tracks repository state using:

  • HEAD commit hash
  • Staged changes hash
  • Working tree changes hash
  • Untracked files hash

This composite state ID is used for cache invalidation.

Backend Ladder

CKB queries backends in priority order:

  1. SCIP - Pre-computed index (fastest, most accurate)
  2. LSP - Language server (real-time, may be slower)
  3. Git - Fallback for basic operations

Architectural Memory

CKB maintains persistent knowledge that survives across sessions:

  • Module Registry - Boundaries, responsibilities, and tags for each module
  • Ownership Registry - Who owns what code (from CODEOWNERS + git blame)
  • Hotspot Tracker - Historical risk tracking with trend analysis
  • Decision Log - Architectural Decision Records (ADRs)

This data is stored in ~/.ckb/repos/<repo-hash>/ and persists until explicitly refreshed.

CLI Commands

ckb init

Initialize CKB in the current directory.

ckb init

Creates .ckb/config.json with default settings.

ckb status

Show system status including:

  • Repository state
  • Backend availability
  • Cache statistics
  • Index freshness
ckb status

ckb doctor

Run diagnostic checks:

ckb doctor

Checks:

  • Configuration validity
  • Backend availability
  • SCIP index presence and freshness
  • Database integrity

ckb search

Search for symbols:

# Basic search
ckb search "myFunction"

# Filter by kind
ckb search "User" --kinds=class,interface

# Limit results
ckb search "handle" --limit=10

# Search within module
ckb search "process" --scope=internal/api

ckb refs

Find references to a symbol:

# Find all references
ckb refs "symbol-id"

# Limit scope
ckb refs "symbol-id" --scope=internal/

# Include test files
ckb refs "symbol-id" --include-tests

ckb impact

Analyze impact of changing a symbol:

# Basic impact analysis
ckb impact "symbol-id"

# Set analysis depth
ckb impact "symbol-id" --depth=3

ckb serve

Start the HTTP API server:

# Default (localhost:8080)
ckb serve

# Custom port
ckb serve --port 8081

# Bind to all interfaces
ckb serve --host 0.0.0.0

ckb symbol

Get detailed information about a specific symbol:

# Get symbol by stable ID
ckb symbol "ckb:myrepo:sym:abc123"

# Output as human-readable format
ckb symbol "ckb:myrepo:sym:abc123" --format=human

# Use full repo state (includes dirty working tree)
ckb symbol "ckb:myrepo:sym:abc123" --repo-state-mode=full

ckb arch

Get a high-level architecture view of the codebase:

# Basic architecture overview
ckb arch

# Increase dependency depth
ckb arch --depth=3

# Include external dependencies
ckb arch --include-external-deps

# Force refresh (bypass cache)
ckb arch --refresh

ckb mcp

Start the MCP (Model Context Protocol) server for AI assistant integration:

# Start MCP server (stdio mode)
ckb mcp

# Start with verbose logging
ckb mcp --verbose

See MCP Integration for setup with Claude Desktop.

ckb diag

Create a diagnostic bundle for troubleshooting:

# Create diagnostic bundle
ckb diag --out ckb-diagnostic.zip

# Anonymize symbol names and paths
ckb diag --out ckb-diagnostic.zip --anonymize

The bundle includes sanitized configuration, doctor output, backend status, and system information. It excludes source code and sensitive credentials.

ckb refresh

Refresh the architectural model:

# Refresh everything
ckb refresh

# Refresh only ownership
ckb refresh --scope ownership

# Force refresh even if data is fresh
ckb refresh --force

# Dry run - see what would change
ckb refresh --dry-run

Scopes:

  • all - Refresh everything (default)
  • modules - Module detection only
  • ownership - CODEOWNERS + git blame
  • hotspots - Hotspot snapshots
  • responsibilities - Module responsibilities

ckb ownership

Query code ownership:

# Get ownership for a file
ckb ownership internal/api/handler.go

# Get ownership for a module
ckb ownership --module internal/api

# Include ownership history
ckb ownership internal/api/handler.go --history

ckb decisions

Work with Architectural Decision Records:

# List all decisions
ckb decisions

# Filter by status
ckb decisions --status accepted

# Search decisions
ckb decisions --search "caching"

# Create a new decision
ckb decisions new --title "Use Redis for caching"

ckb federation

Manage repository federations for cross-repo queries. See Federation for full documentation.

# Create a federation
ckb federation create platform --description "Our microservices"

# Add repositories
ckb federation add platform --repo-id=api --path=/code/api-service
ckb federation add platform --repo-id=auth --path=/code/auth-service

# List federations
ckb federation list

# Check federation status
ckb federation status platform

# List repos in federation
ckb federation repos platform

# Sync federation index
ckb federation sync platform

# Rename a repo in federation
ckb federation rename platform old-api api

# Remove a repo from federation
ckb federation remove platform old-api

# Delete a federation
ckb federation delete platform --force

Subcommands:

  • create - Create a new federation
  • delete - Delete a federation
  • list - List all federations
  • status - Show federation status
  • add - Add a repository
  • remove - Remove a repository
  • rename - Rename a repository
  • repos - List repositories
  • sync - Sync federation index

ckb daemon

Manage the CKB daemon for always-on code intelligence. See Daemon Mode for full documentation.

# Start the daemon
ckb daemon start [--port=9120] [--bind=localhost] [--foreground]

# Stop the daemon
ckb daemon stop

# Restart the daemon
ckb daemon restart

# Check daemon status
ckb daemon status

# View logs
ckb daemon logs [--follow] [--lines=100]

Subcommands:

  • start - Start the daemon process
  • stop - Stop the daemon gracefully
  • restart - Stop and start the daemon
  • status - Show daemon status and statistics
  • logs - View daemon log output

ckb daemon schedule

Manage scheduled tasks:

# List all schedules
ckb daemon schedule list

# Run a schedule immediately
ckb daemon schedule run <schedule-id>

# Enable/disable a schedule
ckb daemon schedule enable <schedule-id>
ckb daemon schedule disable <schedule-id>

ckb webhooks

Manage webhook notifications:

# List configured webhooks
ckb webhooks list

# Test a webhook
ckb webhooks test <webhook-id>

# View delivery history
ckb webhooks deliveries <webhook-id> [--status=failed]

# Retry failed deliveries
ckb webhooks retry <webhook-id>

# View dead letter queue
ckb webhooks dead-letter <webhook-id>

ckb contracts

Manage and analyze API contracts across federations. See Federation for full documentation.

# List all contracts in a federation
ckb contracts list platform

# Filter by repo, type, or visibility
ckb contracts list platform --repo=api --type=proto --visibility=public

# Analyze impact of changing a contract
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto

# Include transitive consumers and heuristic edges
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto --include-transitive --include-heuristic

# Get contract dependencies for a repo
ckb contracts deps platform --repo=api --direction=dependencies
ckb contracts deps platform --repo=api --direction=consumers
ckb contracts deps platform --repo=api --direction=both

# Show contract statistics
ckb contracts stats platform

# Suppress a false positive edge
ckb contracts suppress platform --edge=123 --reason="Not actually used"

# Verify an edge (increase confidence)
ckb contracts verify platform --edge=123

Subcommands:

  • list - List API contracts in a federation
  • impact - Analyze impact of changing a contract
  • deps - Get contract dependencies for a repository
  • stats - Show contract statistics
  • suppress - Suppress a false positive contract edge
  • verify - Verify a contract edge

Supported Contract Types:

  • proto - Protocol Buffers (.proto files)
  • openapi - OpenAPI/Swagger specifications (.yaml, .json)

ckb telemetry

Manage and query runtime telemetry data. See Configuration for telemetry setup.

# Check telemetry status and coverage
ckb telemetry status

# View observed usage for a symbol
ckb telemetry usage --repo=my-repo --symbol="internal/api/handler.go:HandleRequest"

# List services that couldn't be mapped to repos
ckb telemetry unmapped

# Test how a service name maps to a repo
ckb telemetry test-map "my-service-name"

Subcommands:

  • status - Show telemetry status and coverage metrics
  • usage - Show observed usage for a specific symbol
  • unmapped - List unmapped services
  • test-map - Test service → repo mapping

Coverage Levels:

Level Score Feature Access
High ≥ 0.80 Full: dead code, impact enrichment, usage display
Medium ≥ 0.60 Partial: usage display, impact enrichment (with warnings)
Low ≥ 0.40 Limited: usage display only (with caveats)
Insufficient < 0.40 None: telemetry features disabled

ckb dead-code

Find potential dead code using runtime telemetry. Requires telemetry to be enabled with medium+ coverage.

# Find dead code candidates in current repo
ckb dead-code

# Find dead code with higher confidence threshold
ckb dead-code --min-confidence=0.8

# Find dead code in a specific repo
ckb dead-code --repo=my-repo

# Limit results
ckb dead-code --limit=50

Flags:

Flag Default Description
--repo current Repository ID to analyze
--min-confidence 0.7 Minimum confidence threshold (0-1)
--limit 100 Maximum candidates to return

Output includes:

  • Symbol name and file path
  • Static reference count
  • Confidence score (capped at 0.90)
  • Coverage context

Important: Dead code detection is advisory. Always verify before deleting code. See Configuration for exclusion patterns.

Working with Responses

Response Structure

All CKB responses include:

{
  "data": { ... },
  "provenance": {
    "backends": ["scip", "lsp"],
    "repoStateId": "abc123...",
    "cachedAt": "2025-12-16T12:00:00Z"
  },
  "warnings": [],
  "drilldowns": []
}

Drilldowns

When results are truncated, CKB suggests follow-up queries:

{
  "drilldowns": [
    {
      "label": "Explore top module: internal/api",
      "query": "getModuleOverview internal/api",
      "relevanceScore": 0.9
    }
  ]
}

Warnings

CKB reports limitations in analysis:

{
  "warnings": [
    {
      "severity": "warning",
      "text": "SCIP index is 3 commits behind HEAD"
    }
  ]
}

CI/CD Integration

For GitHub Actions workflows, PR analysis, and automated architecture refresh, see the dedicated CI/CD Integration guide.

Best Practices

Keep SCIP Index Fresh

Regenerate your SCIP index after significant changes:

# For Go projects
scip-go

# For TypeScript projects
scip-typescript index

Use Scoped Queries

For large codebases, scope queries to specific modules:

ckb search "handler" --scope=internal/api

Monitor Cache

Check cache statistics to ensure efficient operation:

ckb status

Run Doctor Regularly

ckb doctor

Fix any issues before they impact queries.

Troubleshooting

"Backend unavailable" errors

  1. Check if the backend is installed
  2. Run ckb doctor to diagnose
  3. Check backend-specific configuration in .ckb/config.json

Stale results

  1. Check repository state with ckb status
  2. Regenerate SCIP index if stale
  3. Clear cache: ckb cache clear

Slow queries

  1. Ensure SCIP index exists (fastest backend)
  2. Reduce query scope
  3. Lower result limits
  4. Check if LSP server is responsive

Next Steps

  • Daemon Mode - Always-on service with scheduler, watcher, and webhooks
  • Federation - Cross-repository queries, contract analysis, and unified visibility
  • API Reference - Detailed API documentation
  • Configuration - All configuration options, telemetry setup, MODULES.toml format, and ADR workflow
  • Architecture - How CKB works internally
  • MCP Integration - AI assistant integration with 54 MCP tools

Clone this wiki locally