Skip to content

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

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

🔐 Secure — Secret detection, credential scanning, security-sensitive code identification

👥 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, A2A for agent orchestration, CI/CD pipelines

Works With Your Tools

AI Assistants Agent Platforms CI/CD IDEs & Editors
Claude Code Vertex AI Agent Engine GitHub Actions VS Code
Cursor LangChain GitLab CI Any editor via CLI
Windsurf Any A2A agent Jenkins Custom extensions
Grok Any CI system
Any MCP client

Built for Scale

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

What's New in v9.3

v9.3 is a reliability and transparency release for the structural engine:

v9.3 — Fast tier, visible and hardened:

  • ckb doctor reports the Cartographer tier — a new cartographer check states plainly whether the fast, SCIP-free structural tier is linked into your binary. Previously a build could silently run without it with no way to confirm.
  • macOS/Linux release binaries ship the fast tier — npm and Homebrew builds for darwin and linux link a pinned, checksum-verified Cartographer v4.0.2. Windows ships the pure-Go stub tier. See Cartographer.
  • No longer crashes on very large repos — two unbounded recursions in the graph engine could overflow the stack and abort the whole CKB process via the FFI on a full Linux-kernel checkout (~64k files). Fixed with a 256 MB-stack pool, iterative cycle detection, and a hard depth ceiling.
  • Accurate Go dependency edges — import resolution is now go.mod-aware, eliminating fabricated dependency edges.

v9.2 — Outgoing impact + architecture rendering:

  • Cross-repo outgoing impact — analyzeOutgoingImpact traces a symbol's blast radius across federated repos via LIP query_outgoing_impact
  • Symbol existence probe — symbolExists returns a fast yes/no (with confidence) before expensive lookups
  • Architecture diagrams — renderArchitecture (Cartographer 3.0.0) emits Mermaid/Graphviz from the live module graph
  • LIP v2.3 semantic coupling — analyzeImpact blast radius enriched with semantic coupling scores

v9.1 — LIP utilisation + index UX:

  • stream_context, query_expansion, explain_match wired into the query path
  • Index status surfaces freshness tier, commits-behind, and human-readable age
  • Bug-pattern detection sharper (fewer false positives on test fixtures)
  • Removed heavy dist/ noise from review and audit scans

LIP v2.3+ semantic layer (requires LIP):

  • Semantic search re-ranking — searchSymbols uses LIP nearest-neighbour for natural-language queries
  • PR novelty detection — reviewPR adds semantic-novelty check (files with no semantic neighbours flagged)
  • Semantic test discovery — getAffectedTests finds test files by embedding proximity
  • File boundary analysis — explainFile appends per-region shift magnitude (semantic_boundaries)
  • Architecture coupling matrix — getArchitecture adds semantic_coupling across modules

Refactoring intelligence (v8.1):

  • Dependency cycle detection — findCycles uses Tarjan's SCC algorithm to find circular dependencies at module, directory, or file level
  • Proactive refactoring suggestions — suggestRefactorings identifies complexity, coupling, dead code, and extract candidates
  • Extract flow analysis — prepareChange with changeType: "extract" uses tree-sitter to detect parameters, returns, and generate function signatures
  • Move/relocate analysis — prepareChange with changeType: "move" tracks affected imports and detects target conflicts
  • Unified refactoring planner — planRefactor combines risk assessment, impact analysis, test gaps, and ordered steps in one call
  • Test gap analysis — analyzeTestGaps finds untested functions sorted by complexity risk

📖 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: "Review this PR"

ckb review --format=markdown

CKB provides:
├── Verdict: PASS/WARN/FAIL with score (0-100)
├── 21 quality checks: breaking, secrets, tests, complexity, health, bug-patterns, ...
├── Key risks and per-file findings
├── Code health grades (A-F) with before/after delta
├── Suggested reviewers from CODEOWNERS + git blame
├── PR split suggestion for large changesets
└── Compliance output for regulated industries

Key Capabilities

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

Capability What It Does Key Tools
[Code Navigation](/docs/Features#code-navigation--discovery) Find symbols, trace usage, explore call graphs search, refs, callgraph, trace
[Impact Analysis](/docs/Features#impact-analysis--safety) Assess blast radius, detect breaking changes impact, impact diff, audit, hotspots, pr-summary
[Architecture](/docs/Features#architectural-understanding) Module overview, ADRs, explain code origins arch, modules, decisions, explain
[Ownership](/docs/Features#ownership--review) CODEOWNERS + git blame, reviewer suggestions ownership, ownership-drift, recent
[Code Quality](/docs/Features#code-quality--risk) Dead code, coupling, complexity, quick wins dead-code, coupling, justify, audit
[Security](/docs/Security) Secret detection, credential scanning scanSecrets, audit --factor=security_sensitive
[Documentation](/docs/Features#documentation-intelligence) Doc-symbol linking, staleness detection docs index, docs stale, docs coverage

Additional Capabilities

  • [Multi-Repo Federation](/docs/Features#multi-repo--federation) — Query across repositories, analyze API contracts
  • [Runtime Intelligence](/docs/Features#runtime-intelligence) — OpenTelemetry integration for production insights
  • [Automation & CI/CD](/docs/Features#automation--cicd) — Daemon mode, webhooks, incremental indexing

Technical Foundation

Feature Description
Multi-backend orchestration Routes queries to SCIP, LSP, Git, or LIP 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
[Tool presets](/docs/Presets) Load 25-110 tools based on task (77% token savings)
[LIP semantic layer](/docs/Hybrid-Retrieval) Optional LIP v2.3+ embedding daemon for semantic search, novelty, test discovery, boundaries, outgoing impact

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 (see Enterprise Testing)
  • Enterprise teams evaluating CKB - Step-by-step testing guide
  • 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
Enterprise Testing Evaluation guide for large codebases and monorepos
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
Code Review Unified PR review with 21 quality checks
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
Security Secret detection, credential scanning, allowlists
Compliance-Audit Map code findings to 20 regulatory frameworks
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 + LIP v2.3+ semantic embeddings

Reference

Page Description
MCP Tools Complete MCP tool reference (110 tools)
API Reference HTTP API documentation
Configuration All configuration options
Authentication API tokens and rate limiting
Architecture System design
Cartographer Architectural intelligence — what it adds and how to build with it
Performance Latency targets and benchmarks
Contributing Development guidelines

Installation

# Install globally
npm install -g @tastehub/ckb

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

Homebrew (macOS/Linux)

brew tap SimplyLiz/ckb
brew install ckb

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 110 tools through the Model Context Protocol (v9.2). Use Presets to load only what you need:

Preset Tools Best For
core 25 General development (default)
review 42 PR reviews, ownership
refactor 42 Refactoring, dead code, cycles
docs 34 Documentation maintenance
federation 46 Multi-repo work
ops 43 Daemon, jobs, webhooks
full 110 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.