Skip to content

Home

Jump to bottom
Lisa edited this page Dec 16, 2025 · 59 revisions

CKB - Code Knowledge Backend

A language-agnostic codebase comprehension layer that orchestrates multiple code intelligence backends (SCIP, LSP, Git) and provides semantically compressed, LLM-optimized views.

What is CKB?

CKB (Code Knowledge Backend) is the missing link between your codebase and AI assistants. While AI coding tools like Claude, Cursor, and GitHub Copilot are powerful, they struggle with large codebases because they lack deep structural understanding of your code.

CKB solves this by providing:

  • A unified query layer that abstracts away the complexity of different code intelligence tools
  • Semantic compression that delivers exactly what an LLM needs without overwhelming its context window
  • Stable symbol tracking that survives refactoring, renames, and code moves

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

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)
├── 12 direct callers across 4 modules
├── Risk score: HIGH (public API, many dependents)
├── Affected modules: auth, api, admin, tests
└── 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
├── 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
└── Breaking change warnings

Key Features

Multi-Backend Orchestration

Query SCIP, LSP, and Git through a single interface. CKB automatically:

  • Routes queries to the best available backend
  • Falls back gracefully when backends are unavailable
  • Merges results from multiple sources

Stable Symbol Identity

Symbols get permanent IDs that survive:

  • Renames (oldName → newName)
  • Moves (pkg/old/ → pkg/new/)
  • Refactoring (extract method, inline, etc.)

Old references automatically redirect to current locations.

Smart Compression

Responses are optimized for LLM consumption:

  • Configurable token budgets
  • Intelligent truncation (most relevant first)
  • Drilldown suggestions for deeper exploration
  • Deterministic output for reliable caching

Impact Analysis

Understand the blast radius before making changes:

  • Visibility detection (public/private/internal)
  • Risk scoring based on usage patterns
  • Module-level impact summaries
  • Breaking change detection

Three-Tier Caching

Fast responses through intelligent caching:

  • Query cache - Recent query results
  • View cache - Expensive computations
  • Negative cache - Avoid repeated failures

All caches invalidate automatically when code changes.

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
Onboarding Read docs + explore Query architecture instantly

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

Quick Links

Installation

New to CKB? See the Quick Start guide for detailed, copy-paste instructions for your operating system.

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

Quick Start

# Initialize in your project
cd /path/to/your/project
ckb init

# Generate SCIP index (for Go projects)
scip-go --repository-root=.

# Check status
ckb status

# Search for symbols
ckb search "myFunction"

# Find references
ckb refs "symbol-id"

# Analyze impact
ckb impact "symbol-id"

# Start HTTP API
ckb serve --port 8080

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