Skip to content

User Guide

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

CKB User Guide

Table of Contents

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

  • Node.js 16+ (for npm install) or Go 1.21+ (for building from source)
  • Git repository
  • (Optional) SCIP index for your project — run ckb index to auto-generate
  • (Optional) Language server for your project's language

Installation

npm (Recommended):

# Install globally
npm install -g @tastehub/ckb

# Or run directly without installing
npx @tastehub/ckb --help

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

Configure AI Tool (Optional)

If you use an AI coding assistant, configure CKB as an MCP server:

# Interactive setup - choose your AI tool
ckb setup

# Or specify directly
ckb setup --tool=claude-code
ckb setup --tool=cursor
ckb setup --tool=vscode

See ckb setup for all options, or MCP Integration for manual configuration.

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.

Annotations (v6.5)

Annotations are metadata you add to modules and decisions. They're consumed by other CKB tools to provide richer context:

Annotation Type Created With Consumed By
ADRs ckb decisions create explain, justify, impact, modules
Module Metadata ckb modules annotate explain, modules, responsibilities

Key behavior:

  • ADRs with --module flags automatically surface when querying those modules
  • justify won't recommend removing code that has an accepted ADR
  • Module annotations override inferred descriptions with higher confidence

See ckb decisions and ckb modules annotate for usage.

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 setup

Configure CKB as an MCP server for AI coding tools.

# Interactive setup - select AI tool and scope
ckb setup

# Configure for a specific tool
ckb setup --tool=claude-code
ckb setup --tool=cursor
ckb setup --tool=windsurf
ckb setup --tool=vscode
ckb setup --tool=opencode
ckb setup --tool=claude-desktop

# Configure globally (applies to all projects)
ckb setup --tool=cursor --global

# Use npx for portable setup
ckb setup --tool=claude-code --npx

Supported Tools:

Tool Project Config Global Config
Claude Code .mcp.json claude mcp add
Cursor .cursor/mcp.json ~/.cursor/mcp.json
Windsurf N/A ~/.codeium/mcp_config.json
VS Code .vscode/mcp.json code --add-mcp
OpenCode opencode.json ~/.config/opencode/opencode.json
Claude Desktop N/A Platform-specific config

Flags:

Flag Description
--tool AI tool to configure (claude-code, cursor, windsurf, vscode, opencode, claude-desktop)
--global Configure globally for all projects
--npx Use npx @tastehub/ckb instead of local binary

For manual configuration or other MCP clients, see MCP Integration.

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 (ADRs). ADRs document important architectural choices and their rationale.

# List all decisions
ckb decisions

# Filter by status
ckb decisions --status accepted

# Search decisions
ckb decisions --search "caching"

# Create a new decision (interactive)
ckb decisions create --interactive

# Create with flags
ckb decisions create \
  --title "Use Redis for caching" \
  --context "User sessions need fast access..." \
  --decision "We will use Redis with 1-hour TTL" \
  --consequence "New infrastructure dependency" \
  --module internal/cache \
  --alternative "Memcached"

v6.5 Integration: Once you create an ADR with --module, it automatically appears in:

  • ckb explain <symbol> - Shows related ADRs for the symbol's module
  • ckb justify <symbol> - Prevents "remove" verdict for intentionally kept code
  • ckb impact <symbol> - Lists ADRs for affected modules
  • MCP tools: explainSymbol, justifySymbol, analyzeImpact, getModuleOverview

Example workflow:

# 1. Record why you're keeping "unused" extension points
ckb decisions create \
  --title "Plugin extension points" \
  --context "Need extensibility for third-party plugins" \
  --decision "Keep extension interfaces even without current callers" \
  --module internal/plugins \
  --status accepted

# 2. Now justifySymbol won't flag plugin interfaces as dead code
ckb justify internal/plugins/PluginInterface
# Returns: "investigate" with "related to ADR-001: Plugin extension points"

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
  • search-modules - Search modules across federation
  • search-ownership - Search ownership across federation
  • hotspots - Get hotspots across federation
  • search-decisions - Search decisions across federation

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.

ckb explain

Explain why code exists with full context—origin, evolution, warnings, and related references.

# Explain a file
ckb explain internal/api/handler.go

# Explain a specific line
ckb explain internal/api/handler.go:42

# Include co-change information
ckb explain internal/api/handler.go --co-change

# Skip usage analysis for faster response
ckb explain internal/api/handler.go --no-usage

# Limit history entries
ckb explain internal/api/handler.go --history-limit=20

Flags:

Flag Default Description
--co-change true Include co-change coupling data
--usage true Include usage analysis
--history-limit 10 Maximum history entries to show

Output includes:

  • Origin (who created it, when, why)
  • Evolution timeline (changes over time)
  • Contributors and bus factor
  • Co-changes (files that change together)
  • Warnings (stale, temporary code, high coupling)
  • References (linked issues, PRs, JIRA tickets)

ckb coupling

Analyze co-change coupling—find files that historically change together.

# Analyze coupling for a file
ckb coupling internal/query/engine.go

# Set minimum correlation threshold
ckb coupling internal/query/engine.go --min-correlation=0.5

# Extend time window (days)
ckb coupling internal/query/engine.go --window=730

# Limit results
ckb coupling internal/query/engine.go --limit=10

Flags:

Flag Default Description
--min-correlation 0.3 Minimum correlation to include (0-1)
--window 365 Time window in days
--limit 20 Maximum results

Output includes:

  • Coupled files with correlation scores
  • Co-commit counts
  • Shared authors
  • Last co-change date
  • Coupling summary (strong/moderate/weak)
  • Insights and recommendations

ckb export

Export codebase structure in LLM-friendly format.

# Full export
ckb export

# Filter by complexity
ckb export --min-complexity=10

# Filter by usage
ckb export --min-calls=100

# Limit symbols
ckb export --max-symbols=200

# Exclude optional data
ckb export --no-usage --no-ownership

# Output to file
ckb export --out codebase-summary.txt

Flags:

Flag Default Description
--usage true Include call counts (requires telemetry)
--ownership true Include owners
--contracts true Include contract information
--complexity true Include complexity metrics
--min-complexity 0 Skip symbols below this complexity
--min-calls 0 Skip symbols below this call count
--max-symbols unlimited Maximum symbols to include
--out stdout Output file path

Output format:

# Codebase: my-project
# Symbols: 150 | Files: 45 | Modules: 8

## internal/api/ (owner: @api-team)
  ! handler.go
      $ Server                  c=5  calls=10k/day ★★★
      # HandleRequest()         c=12 calls=8k/day  ★★★

ckb audit

Audit codebase for risky code based on multiple weighted signals.

# Full risk audit
ckb audit

# Set minimum risk score
ckb audit --min-score=60

# Focus on specific factor
ckb audit --factor=complexity

# Get quick wins (high impact, low effort)
ckb audit --quick-wins

# Limit results
ckb audit --limit=20

Flags:

Flag Default Description
--min-score 40 Minimum risk score (0-100)
--limit 50 Maximum results
--factor all Focus on specific factor
--quick-wins false Return only high-impact, low-effort items

Risk Factors (weighted):

Factor Weight Description
Complexity 20% Cyclomatic/cognitive complexity
Test Coverage 20% Lack of test coverage
Bus Factor 15% Single-author code
Security 15% Handles auth, crypto, PII
Staleness 10% Not touched in 6+ months
Error Rate 10% Runtime error frequency
Coupling 5% High co-change coupling
Churn 5% Frequent modifications

Output includes:

  • Risk score per file/symbol
  • Factor breakdown with weights
  • Top contributing factors
  • Remediation suggestions
  • Quick wins (when --quick-wins enabled)

ckb modules

Get module overview and manage module annotations.

# Get overview of current directory
ckb modules

# Get overview of specific module
ckb modules internal/api

# Get with friendly name
ckb modules --name="API Layer" internal/api

# Human-readable output
ckb modules --format=human

Subcommands:

ckb modules annotate

Add or update module metadata. Annotations are persisted and used by other CKB tools.

# Add responsibility
ckb modules annotate internal/api --responsibility="HTTP API handlers"

# Add capabilities and tags
ckb modules annotate internal/api --capabilities="REST,WebSocket" --tags="core,infrastructure"

# Define API boundaries
ckb modules annotate internal/api --public-paths="handler.go,routes.go" --internal-paths="helpers.go"

# Full annotation
ckb modules annotate internal/auth \
  --responsibility="OAuth2 token validation and session management" \
  --capabilities="OAuth2,JWT,Sessions" \
  --tags="security,core"

v6.5 Integration: Annotated modules get richer context in:

  • ckb modules / getModuleOverview - Shows annotations in output
  • ckb explain <symbol> / explainSymbol - Includes module annotations
  • ckb modules responsibilities / getModuleResponsibilities - Declared annotations override inferred with higher confidence

Declared vs Inferred:

  • Without annotation: CKB infers responsibility from code (lower confidence)
  • With annotation: Your declared responsibility is used (higher confidence, source: "declared")

ckb modules responsibilities

Get responsibilities for modules:

# Get all module responsibilities
ckb modules responsibilities

# Get for specific module
ckb modules responsibilities internal/api

# Include file-level responsibilities
ckb modules responsibilities --include-files

# Limit results
ckb modules responsibilities --limit=50

ckb justify

Get keep/investigate/remove verdict for a symbol with evidence.

# Justify a symbol
ckb justify 'scip-go gomod myproject myproject/pkg/MyFunction'

# Human-readable output
ckb justify --format=human 'symbol-id'

Returns verdict (keep/investigate/remove) with evidence including:

  • Reference count
  • Export status
  • Entrypoint relationships
  • Telemetry usage data

ckb callgraph

Get caller/callee relationships for a symbol.

# Get full call graph (both directions)
ckb callgraph 'symbol-id'

# Callers only
ckb callgraph --direction=callers 'symbol-id'

# Callees only
ckb callgraph --direction=callees 'symbol-id'

# Set traversal depth (1-4)
ckb callgraph --depth=2 'symbol-id'

ckb entrypoints

List system entrypoints (API handlers, CLI mains, background jobs).

# List all entrypoints
ckb entrypoints

# Filter by module
ckb entrypoints --module=internal/api

# Limit results
ckb entrypoints --limit=50

ckb trace

Trace how a symbol is reached from system entrypoints.

# Trace usage paths
ckb trace 'symbol-id'

# Limit paths returned
ckb trace --max-paths=20 'symbol-id'

# Set maximum path depth
ckb trace --max-depth=3 'symbol-id'

ckb hotspots

Find high-churn, high-complexity code areas.

# Get hotspots
ckb hotspots

# Top N hotspots
ckb hotspots --limit=50

# Filter by minimum score
ckb hotspots --min-score=0.5

# Filter by module
ckb hotspots --module=internal/api

ckb diff-summary

Summarize what changed and what might break.

# Default: last 30 days
ckb diff-summary

# Single commit
ckb diff-summary --commit=abc1234

# Commit range
ckb diff-summary --base=main --head=feature/my-branch

# Time window
ckb diff-summary --start=2024-01-01 --end=2024-06-30

ckb pr-summary

Analyze a pull request with risk assessment.

# Analyze current branch's PR
ckb pr-summary

# Analyze specific PR by number
ckb pr-summary --pr=123

# Specify base branch
ckb pr-summary --base=main --head=feature/my-branch

ckb jobs

Manage background jobs.

# List all jobs
ckb jobs list

# Get job status
ckb jobs status <job-id>

# Cancel a job
ckb jobs cancel <job-id>

ckb concepts

Discover key codebase concepts.

# List key concepts
ckb concepts

# Limit results
ckb concepts --limit=30

# Filter by minimum importance
ckb concepts --min-importance=0.5

ckb recent

Find recently relevant files.

# Get recently relevant files
ckb recent

# Within specific time window (days)
ckb recent --days=7

# Limit results
ckb recent --limit=30

ckb complexity

Get complexity metrics for a file.

# Analyze file complexity
ckb complexity path/to/file.go

# Include function-level breakdown
ckb complexity --functions path/to/file.go

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 58 MCP tools

Clone this wiki locally