CKB — Code Knowledge Backend

The missing link between your codebase and AI assistants.

CKB gives AI assistants deep understanding of your code. Instead of grepping through files, your AI can now navigate code like a senior engineer—with knowledge of who owns what, what's risky to change, and how everything connects.

CKB analyzes and explains your code but never modifies it. Think of it as a librarian who knows everything about the books but never rewrites them.

The Problem

AI Assistants Are Blind to Code Structure

When you ask an AI "what calls this function?", it typically:

1. Searches for text patterns (error-prone)
2. Reads random files hoping to find context (inefficient)
3. Gives up and asks you to provide more context (frustrating)

Existing Tools Don't Talk to Each Other

Your codebase has valuable intelligence scattered across SCIP indexes, language servers, git history, and CODEOWNERS files. Each speaks a different language. None are optimized for AI consumption.

Context Windows Are Limited

Even with 100K+ token context, you can't dump your entire codebase into an LLM. You need relevant information only, properly compressed, with smart truncation.

What CKB Gives You

You: "What's the impact of changing UserService.authenticate()?"

CKB provides:
├── Symbol details (signature, visibility, location)
├── 12 direct callers across 4 modules
├── Risk score: HIGH (public API, many dependents)
├── Affected modules: auth, api, admin, tests
├── Code owners: @security-team, @api-team
└── Suggested drilldowns for deeper analysis

You: "Show me the architecture of this codebase"

CKB provides:
├── Module dependency graph
├── Key symbols per module
├── Module responsibilities and ownership
├── Import/export relationships
└── Compressed to fit LLM context

You: "Is it safe to rename this function?"

CKB provides:
├── All references (not just text matches)
├── Cross-module dependencies
├── Test coverage of affected code
├── Hotspot risk assessment
└── Breaking change warnings

Quick Start

Option 1: npm (Recommended)

# Install globally
npm install -g @tastehub/ckb

# Or run directly with npx (no install needed)
npx @tastehub/ckb init

Option 2: Build from Source

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

Setup

# 1. Initialize in your project
cd /path/to/your/project
ckb init   # or: npx @tastehub/ckb init

# 2. Generate SCIP index (optional but recommended)
ckb index  # auto-detects language and runs appropriate indexer

# 3. Connect to Claude Code
ckb setup  # creates .mcp.json automatically

# Or manually:
claude mcp add --transport stdio ckb -- npx @tastehub/ckb mcp

Now Claude can answer questions like:

• "What calls the HandleRequest function?"
• "How is ProcessPayment reached from the API?"
• "What's the blast radius if I change UserService?"
• "Who owns the internal/api module?"
• "Is this legacy code still used?"

Why CKB?

Three Ways to Use It

Features

Core Intelligence

• Symbol Navigation — Find any function, class, or variable in milliseconds
• Call Flow & Tracing — Trace how code is reached from API endpoints, CLI commands, or jobs
• Impact Analysis — Know exactly what breaks before refactoring, with risk scores
• Architecture Maps — Module dependency graphs, responsibilities, domain concepts
• Dead Code Detection — Keep/investigate/remove verdicts based on usage analysis

Ownership & Risk

• Ownership Intelligence — CODEOWNERS + git blame with time-weighted analysis
• Hotspot Detection — Track churn trends, get 30-day risk projections
• Architectural Decisions — Record and query ADRs with full-text search

Advanced Capabilities

• Federation — Query across multiple repos organization-wide
• Multi-Repo Management — Named repo registry with quick MCP context switching
• Daemon Mode — Always-on service with HTTP API, scheduled tasks, webhooks
• Contract Analysis — Protobuf and OpenAPI discovery with cross-repo impact
• Runtime Observability — OpenTelemetry integration for dead code detection
• Developer Intelligence — Symbol origins, co-change coupling, risk audit

Fast Indexing

• Zero-Index Operation — Tree-sitter fallback works without SCIP index
• Incremental Updates — O(changed files) instead of full reindex (Go, TypeScript, Python, Dart, Rust)
• Smart Caching — Skip-if-fresh, watch mode, transitive invalidation
• Auto Index Updates — Watch mode, daemon file watcher, webhook API for CI/CD

Remote Index Server

• Index Serving — Serve symbol indexes over HTTP for federation
• Index Upload — Push SCIP indexes with compression (gzip/zstd)
• Delta Updates — Upload only changed files
• API Key Auth — Scoped keys with rate limiting
• Remote Federation — Connect to remote CKB servers and query alongside local repos

📋 Full Changelog — Detailed version history from v5.1 to current

Zero-Friction UX (v7.0+)

• npm Distribution — npm install -g @tastehub/ckb or npx @tastehub/ckb
• Auto-Setup — ckb setup configures Claude Code integration automatically
• Update Notifications — Automatic update check for npm installs (disable with CKB_NO_UPDATE_CHECK=1)

Zero-Index Operation (v7.1)

• Tree-sitter Fallback — Symbol search works without SCIP index (8 languages)
• Auto-Index — ckb index detects language and runs the right SCIP indexer
• Install Guidance — Shows indexer install commands when missing
• Universal MCP Docs — Setup for Claude Code, Cursor, Windsurf, VS Code, OpenCode, Claude Desktop

Smart Indexing & Explicit Tiers (v7.2)

• Skip-if-Fresh — ckb index automatically skips if index is current with HEAD
• Freshness Tracking — Tracks commits behind HEAD + uncommitted changes
• Index Status — ckb status shows index freshness with commit hash
• Watch Mode — ckb mcp --watch polls every 30s and auto-reindexes when stale
• Lock File — Prevents concurrent indexing with flock-based locking
• Explicit Tiers — Control analysis mode: --tier=fast|standard|full or CKB_TIER env var
• Tier Diagnostics — ckb doctor --tier enhanced shows exactly what's missing and how to fix it

Doc-Symbol Linking (v7.3)

• Backtick Detection — Automatically detect Symbol.Name references in markdown
• Directive Support — Explicit <!-- ckb:symbol --> and <!-- ckb:module --> directives
• Fence Scanning — Extract symbols from fenced code blocks via tree-sitter (8 languages)
• Staleness Detection — Find broken references when symbols are renamed or deleted
• Rename Awareness — Suggest new names when documented symbols are renamed
• CI Enforcement — --fail-under flag for documentation coverage thresholds

Standardized Response Envelope (v7.4)

• Unified Metadata — All 76 MCP tool responses now include structured metadata
• Confidence Tiers — High/Medium/Low/Speculative tiers based on data freshness and source
• Provenance Tracking — Know which backends (SCIP, Git, LSP) contributed to results
• Truncation Awareness — Metadata shows when results are truncated and total counts
• Suggested Next Calls — Structured drilldown suggestions for follow-up queries

Production Hardening (v7.3)

• Delta Artifacts — CI-generated diffs for O(delta) ingestion instead of O(N)
• FTS5 Search — SQLite FTS5 for instant search (replaces LIKE scans)
• Compaction Scheduler — Automatic snapshot cleanup and database maintenance
• Prometheus Metrics — /metrics endpoint for monitoring and alerting
• Load Shedding — Graceful degradation under load with priority endpoints
• Health Details — /health/detailed endpoint with per-repo and storage metrics

Language Quality (v7.3)

• Quality Tiers — 4-tier classification (Tier 1: Go, Tier 2: TS/Python, Tier 3: Rust/Java, Tier 4: Experimental)
• Quality Assessment — Per-language metrics (ref accuracy, callgraph quality)
• Python Venv Detection — Auto-detect virtual environments with activation recommendations
• TypeScript Monorepo — Detect pnpm, lerna, nx, yarn workspaces with per-package tsconfig status

Auto Index Updates (v7.5)

• Watch Mode — ckb index --watch and ckb mcp --watch --watch-interval 15s
• Daemon File Watcher — Automatic incremental refresh on git changes
• Webhook API — POST /api/v1/refresh for CI/CD integration
• Index Staleness — ckb status and getStatus show commits behind, index age, staleness reasons
• Token Efficiency Visibility — Startup banner shows active tools, estimated tokens, preset savings (83% with core)

Multi-Language Incremental (v7.5)

• Expanded Support — Go, TypeScript, Python, Dart, Rust (automatic indexer detection)
• Graceful Degradation — Install hints when indexer is missing
• Unified API — IndexIncrementalWithLang(ctx, since, lang) for all languages

Performance Improvements (v7.5)

• SCIP Backend — Up to 2,500x faster: FindReferences (136x), SearchSymbols (7x), FindSymbolLocation (2,500x)
• Git Backend — 53x faster getHotspots (single git command vs 4 per file)
• Pre-computed Indexes — RefIndex, ConvertedSymbols cache, ContainerIndex for O(1) lookups

MCP Tools (76 Available)

CKB exposes code intelligence through the Model Context Protocol:

CLI Usage

# System status
ckb status

# Search for symbols
ckb search NewServer

# Find references
ckb refs NewServer

# Get architecture overview
ckb arch

# Analyze change impact
ckb impact <symbol-id>

# Query ownership
ckb ownership internal/api/handler.go

# List architectural decisions
ckb decisions

# Run diagnostics
ckb doctor

# Check tier-specific requirements
ckb doctor --tier enhanced

# Start MCP server for AI assistants
ckb mcp

# Federation (v6.2)
ckb federation create platform --description "Our microservices"
ckb federation add platform --repo-id=api --path=/code/api
ckb federation status platform
ckb federation sync platform

# Remote Federation (v7.3)
ckb federation add-remote platform prod --url=https://ckb.company.com --token=$CKB_TOKEN
ckb federation list-remote platform
ckb federation sync-remote platform
ckb federation status-remote platform prod

# Daemon (v6.2.1)
ckb daemon start [--port=9120]
ckb daemon status
ckb daemon logs --follow
ckb daemon stop

# Contracts (v6.3)
ckb contracts list platform
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto
ckb contracts deps platform --repo=api

# Telemetry (v6.4)
ckb telemetry status
ckb telemetry usage --symbol="internal/api/handler.go:HandleRequest"
ckb dead-code --min-confidence=0.7

# Developer Intelligence (v6.5)
ckb explain internal/api/handler.go:42
ckb coupling internal/query/engine.go --min-correlation=0.5
ckb export --min-complexity=10 --max-symbols=200
ckb audit --min-score=60 --quick-wins

HTTP API

# Start the HTTP server
ckb serve --port 8080

# Example calls
curl http://localhost:8080/health
curl http://localhost:8080/status
curl "http://localhost:8080/search?q=NewServer"
curl http://localhost:8080/architecture
curl "http://localhost:8080/ownership?path=internal/api"
curl http://localhost:8080/hotspots

# Index Server Mode (v7.3) - serve indexes to remote clients
ckb serve --port 8080 --index-server --index-config config.toml

# Index server endpoints
curl http://localhost:8080/index/repos
curl http://localhost:8080/index/repos/company%2Fcore-lib/meta
curl "http://localhost:8080/index/repos/company%2Fcore-lib/symbols?limit=100"
curl "http://localhost:8080/index/repos/company%2Fcore-lib/search/symbols?q=Handler"

# Upload endpoints (with compression + auth)
curl -X POST http://localhost:8080/index/repos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ckb_xxx" \
  -d '{"id":"my-org/my-repo","name":"My Repo"}'

gzip -c index.scip | curl -X POST http://localhost:8080/index/repos/my-org%2Fmy-repo/upload \
  -H "Content-Encoding: gzip" \
  -H "Authorization: Bearer ckb_xxx" \
  --data-binary @-

# Token management (index server admin)
ckb token create --name "ci-upload" --scope upload    # Create API key
ckb token list                                         # List all tokens
ckb token revoke ckb_xxx                              # Revoke a token
ckb token rotate ckb_xxx                              # Rotate (new secret, same ID)

MCP Integration

CKB works with any MCP-compatible AI coding tool.

# Auto-configure for current project
npx @tastehub/ckb setup

# Or add globally for all projects
npx @tastehub/ckb setup --global

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "ckb": {
        "type": "stdio",
        "command": "npx",
        "args": ["@tastehub/ckb", "mcp"]
      }
    }
  }
}

{
  "mcp": {
    "ckb": {
      "type": "local",
      "command": ["npx", "@tastehub/ckb", "mcp"],
      "enabled": true
    }
  }
}

cd /path/to/your/repo
ckb setup --tool=claude-desktop

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["-y", "@tastehub/ckb", "mcp"],
      "env": {
        "CKB_REPO": "/path/to/your/repo"
      }
    }
  }
}

{
  "mcpServers": {
    "ckb": {
      "command": "cmd",
      "args": ["/c", "npx", "@tastehub/ckb", "mcp"]
    }
  }
}

# Default: core preset (14 essential tools)
ckb mcp

# Workflow-specific presets
ckb mcp --preset=core        # 14 tools - search, explain, impact (default)
ckb mcp --preset=review      # 19 tools - core + diff, ownership
ckb mcp --preset=refactor    # 19 tools - core + coupling, dead code
ckb mcp --preset=federation  # 28 tools - core + cross-repo
ckb mcp --preset=docs        # 20 tools - core + doc-symbol linking
ckb mcp --preset=ops         # 25 tools - core + jobs, webhooks, metrics
ckb mcp --preset=full        # 76 tools - all tools (legacy)

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp", "--preset=review"]
    }
  }
}

Under the Hood

CKB orchestrates multiple code intelligence backends:

• SCIP — Precise, pre-indexed symbol data (fastest)
• LSP — Real-time language server queries
• Git — Blame, history, churn analysis, ownership

Results are merged intelligently and compressed for LLM context limits.

Persistent knowledge survives across sessions:

• Module Registry — Boundaries, responsibilities, tags
• Ownership Registry — CODEOWNERS + git-blame with time decay
• Hotspot Tracker — Historical snapshots with trend analysis
• Decision Log — ADRs with full-text search

Who Should Use CKB?

• Developers using AI assistants — Give your AI tools superpowers
• Teams with large codebases — Navigate complexity efficiently
• Anyone doing refactoring — Understand impact before changing
• Code reviewers — See the full picture of changes
• Tech leads — Track architectural health over time

Documentation

See the Full Documentation Wiki for:

• Quick Start — Step-by-step installation
• Prompt Cookbook — Real prompts for real problems
• Language Support — SCIP indexers and support tiers
• Practical Limits — Accuracy notes, blind spots
• User Guide — CLI commands and best practices
• Incremental Indexing — Fast index updates for Go projects
• Doc-Symbol Linking — Symbol detection in docs, staleness checking
• Authentication — API tokens, scopes, rate limiting
• MCP Integration — Claude Code setup, 76 tools
• API Reference — HTTP API documentation
• Daemon Mode — Always-on service with scheduler, webhooks
• Configuration — All options including MODULES.toml
• Architecture — System design and components
• Telemetry — Runtime observability, dead code detection
• Federation — Cross-repository queries
• CI/CD Integration — GitHub Actions, PR analysis

Requirements

Using npm (recommended):

• Node.js 16+
• Git

Building from source:

• Go 1.21+
• Git

Optional (for enhanced analysis):

• SCIP indexer for your language (scip-go, scip-typescript, etc.) — run ckb index to auto-install

License

Free for personal use. Commercial/enterprise use requires a license. See LICENSE for details.