Skip to content

Home

Jump to bottom
Lisa edited this page Dec 25, 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 with persistent architectural understanding.

CKB analyzes, indexes, and explains your code but never modifies it. It won't refactor, lint, format, auto-fix, or enforce coding standards. Think of it as a librarian who knows everything about the books but never rewrites them.

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
  • Architectural memory that maintains persistent knowledge about your codebase structure, ownership, and design decisions

📖 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, 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-76 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
MCP Integration Claude Desktop and AI assistant setup
Presets Tool presets for token optimization
CI/CD Integration GitHub Actions and automated analysis
Daemon Mode Always-on service with webhooks
Index Management Automatic refresh, branch switching, freshness

Advanced

Page Description
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 (76 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 76 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 76 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