Skip to content

Home

Jump to bottom
Lisa edited this page Jan 2, 2026 · 46 revisions

CKB - Code Knowledge Backend

Know your code. Change it safely. Ship with confidence.

CKB transforms your codebase into a queryable knowledge base. Ask questions, understand impact, find owners, detect dead code, and make changes without fear—all through a unified interface that works with your AI tools, CI/CD pipelines, and custom scripts.

CKB analyzes and explains your code but never modifies it. Think of it as a senior engineer who knows every line of code, every decision, and every owner—available 24/7 to answer your questions.

What is CKB?

CKB (Code Knowledge Backend) gives you instant answers to the questions that slow down development:

Question Without CKB With CKB
"What breaks if I change this?" Grep and hope Precise blast radius with risk score
"Who should review this PR?" Guess from git blame Data-driven reviewer suggestions
"Is this code still used?" Delete and see what breaks Confidence-scored dead code detection
"What tests should I run?" Run everything (30 min) Run affected tests only (2 min)
"How does this system work?" Read code for hours Query architecture instantly
"Who owns this code?" Search CODEOWNERS manually Ownership with drift detection

More Than Code Search

CKB isn't just another code search tool. It's a complete code intelligence platform:

🔍 Understand — Semantic search, call graphs, usage tracing, architecture maps

⚡ Analyze — Impact analysis, risk scoring, hotspot detection, coupling analysis

🛡️ Protect — Affected test detection, breaking change warnings, PR risk assessment

👥 Collaborate — Ownership lookup, reviewer suggestions, architectural decisions (ADRs)

📊 Improve — Dead code detection, tech debt tracking, documentation coverage

🔗 Integrate — CLI, HTTP API, MCP for AI tools, CI/CD pipelines, custom scripts

Works With Your Tools

AI Assistants CI/CD IDEs & Editors
Claude Code GitHub Actions VS Code
Cursor GitLab CI Any editor via CLI
Windsurf Jenkins Custom extensions
Any MCP client Any CI system

Built for Scale

  • Incremental indexing — Update in seconds, not minutes
  • Multi-repo federation — Query across all your repositories
  • Token-optimized — 83% reduction in LLM context usage with presets
  • Language-agnostic — Go, TypeScript, Python, Rust, Java, and more

What's New in v8.0

v8.0 focuses on reliability, error clarity, and AI efficiency:

  • Compound tools — explore, understand, prepareChange, batchGet, batchSearch reduce AI tool calls by 60-70%
  • Enhanced getStatus — Health tiers (available/degraded/unavailable), backend remediation, actionable suggestions
  • New reindex tool — Trigger index refresh without restarting, with scope control (full/incremental)
  • Structured error codes — All errors include remediation steps and drilldown suggestions
  • Breaking change detection — Compare API versions with compareAPI tool
  • Affected tests — Find tests that cover a symbol with getAffectedTests

📖 Looking for specific features? See Features for a complete guide organized by what you want to accomplish—code navigation, impact analysis, architecture, ownership, and more.

The Problem CKB Solves

AI Assistants Are Blind to Code Structure

When you ask an AI assistant "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 - Precise symbol information, but requires setup
  • Language servers - Real-time analysis, but slow for large queries
  • Git - History and blame, but no semantic understanding
  • CODEOWNERS - Ownership rules, but no integration with code intelligence

Each tool speaks a different language. None of them are optimized for AI consumption.

Context Windows Are Limited

Even with 100K+ token context windows, you can't just dump your entire codebase into an LLM. You need:

  • Relevant information only
  • Properly compressed responses
  • Smart truncation with follow-up suggestions

How CKB Helps

For AI-Assisted Development

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

CKB provides:
├── Symbol details (signature, visibility, location)
├── Blast radius: 4 modules, 12 files, 18 callers → high risk
├── 12 direct callers + 6 transitive callers (depth 2-3)
├── Risk score: HIGH (public API, many dependents)
├── Affected modules: auth, api, admin, tests
├── Code owners: @security-team, @api-team
└── Suggested drilldowns for deeper analysis

For Code Understanding

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

For Refactoring Safety

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

For Code Review

You: "Who should review changes to internal/api?"

CKB provides:
├── Primary owners from CODEOWNERS
├── Recent contributors from git blame
├── Related architectural decisions
└── Historical hotspot trends

Key Capabilities

CKB provides deep code intelligence across six areas. See Features for detailed documentation and example prompts.

Capability What It Does Key Tools
Features#code-navigation--discovery Find symbols, trace usage, explore call graphs search, refs, callgraph, trace
Features#impact-analysis--safety Assess blast radius, detect breaking changes impact, impact diff, audit, hotspots, pr-summary
Features#architectural-understanding Module overview, ADRs, explain code origins arch, modules, decisions, explain
Features#ownership--review CODEOWNERS + git blame, reviewer suggestions ownership, ownership-drift, recent
Features#code-quality--risk Dead code, coupling, complexity, quick wins dead-code, coupling, justify, audit
Features#documentation-intelligence Doc-symbol linking, staleness detection docs index, docs stale, docs coverage

Additional Capabilities

Technical Foundation

Feature Description
Multi-backend orchestration Routes queries to SCIP, LSP, or Git automatically
Stable symbol identity IDs survive renames, moves, and refactoring
Smart compression Token budgets, truncation, drilldown suggestions
Three-tier caching Query, view, and negative caches with auto-invalidation
Presets Load 14-81 tools based on task (83% token savings)

Use Cases

Use Case Without CKB With CKB
Find all callers Grep + manual filtering Precise semantic results
Understand function Read surrounding files Structured summary with context
Safe refactoring Hope for the best Impact analysis + risk score
Code review Check changed files only See downstream effects + owners
Onboarding Read docs + explore Query architecture instantly
Find code owner Search CODEOWNERS manually Query ownership for any path
Track tech debt Gut feeling Hotspot trends with data

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

Getting Started

Page Description
Features Complete feature guide organized by use case
Quick Start Installation for Windows, macOS, and Linux
Prompt Cookbook Real prompts for real problems
User Guide CLI commands and best practices
Language Support Supported languages and quality tiers
Practical Limits Accuracy notes and how to validate results

Integration

Page Description
Integration Guide How to use CKB in your own tools (CLI, API, MCP)
MCP Integration Claude Desktop and AI assistant setup
Presets Tool presets for token optimization
CI/CD Integration GitHub Actions and automated analysis
Workflow Examples Production-ready CI/CD workflow templates
Quality Gates Complexity, risk, coupling, and coverage gates
Daemon Mode Always-on service with webhooks
Index Management Automatic refresh, branch switching, freshness

Advanced

Page Description
Impact-Analysis Blast radius, risk scoring, and change analysis
Federation Cross-repository queries and contracts
Telemetry Runtime observability with OpenTelemetry
Doc-Symbol Linking Documentation-code linking
Incremental Indexing Fast index updates (Go)
Hybrid Retrieval Graph-based search ranking

Reference

Page Description
MCP Tools Complete MCP tool reference (81 tools)
API Reference HTTP API documentation
Configuration All configuration options
Authentication API tokens and rate limiting
Architecture System design
Performance Latency targets and benchmarks
Contributing Development guidelines

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

New to CKB? See the Quick Start guide for detailed instructions.

Quick Start

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

# Generate SCIP index (auto-detects language)
ckb index

# Check status
ckb status

# Configure Claude Code
ckb setup

# Search for symbols
ckb search "myFunction"

# Find references
ckb refs "symbol-id"

# Analyze impact
ckb impact "symbol-id"

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

# View architectural decisions
ckb decisions

# Start MCP server for AI assistants
ckb mcp

MCP Tools

CKB exposes 81 tools through the Model Context Protocol. Use Presets to load only what you need:

Preset Tools Best For
core 14 General development (default)
review 19 PR reviews, ownership
refactor 19 Refactoring, dead code
docs 20 Documentation maintenance
federation 28 Multi-repo work
full 81 Everything 
ckb mcp --preset=review

See MCP Tools for the complete tool reference and MCP Integration for setup instructions.

Interfaces

CKB provides three ways to interact:

Interface Best For
CLI Quick queries, scripting, CI/CD
HTTP API Web integrations, custom tools
MCP Server Claude Desktop, AI assistants

License

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

Clone this wiki locally