Ckb

CKB — Code Knowledge Backend

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

[npm version] [Website] [Documentation] [MCP Badge] [LIP] [LIP docs]

CKB transforms your codebase into a queryable knowledge base. Ask questions, understand impact, find owners, detect dead code—all through CLI, API, or AI assistants.

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.

Instant Answers to Hard Questions

What You Can Do

🔍 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

🚀 Compound Operations — Single-call tools (explore, understand, prepareChange) reduce AI tool calls by 60-70%

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

Try It Now

# See what's risky in your codebaseckb hotspots --format=human
# Check what changed and what might breakckb diff-summary --format=human
# Scan for exposed secretsckb audit --format=human
# Check architecture at a glanceckb arch --format=human
# Check system statusckb status

Works Everywhere

83% token reduction with smart presets—load only the tools you need.

# One command to connect to Claude Codeckb setup

Building your own tools? Use CKB as a backend via CLI, HTTP API, or MCP. See the Integration Guide for examples in Node.js, Python, Go, and shell scripts.

Learn More

Quick Start

Option 1: npm (Recommended)

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

Option 2: Homebrew (macOS/Linux)

brew install simplyliz/ckb/ckb

Use the fully-qualified name. Homebrew 6.0 requires third-party taps to be trusted before it loads them; installing this way grants that trust for this one formula. Tapping first and installing by short name fails with Refusing to load formula ... from untrusted tap.

Option 3: Build from Source

git clone https://github.com/SimplyLiz/CodeMCP.gitcd CodeMCPgo build -o ckb ./cmd/ckb

Setup

# 1. Initialize in your projectcd /path/to/your/projectckb 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 Codeckb setup  # creates .mcp.json automatically
# Or manually:claude mcp add --transport stdio ckb -- npx @tastehub/ckb mcp

Token efficiency shown at startup:

CKB MCP Server v9.3.1  Active tools: 25 / 110 (22%)  Estimated context: ~4k tokens  Preset: core

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

How Indexing Works

CKB uses SCIP indexes to understand your code. Think of it like a database that knows where every function is defined, who calls it, and how everything connects.

The Basics

# 1. Generate an index (auto-detects language)ckb index
# 2. Check if your index is freshckb status

Without an index, CKB still works using tree-sitter parsing (basic mode), but with an index you get:

• Cross-file references ("who calls this function?")
• Precise impact analysis
• Call graph navigation

Language Support

Not all languages are equal. CKB classifies languages into quality tiers based on indexer maturity:

Key limitations:

• Incremental indexing is Go-only. Other languages require full reindex.
• TypeScript monorepos may need --infer-tsconfig flag
• C/C++ requires compile_commands.json
• Python works best with activated virtual environment

Run ckb doctor --tier standard to check if your language tools are properly installed.

See Language Support for indexer installation, known issues, and the full feature matrix.

Keeping Your Index Fresh

Your index becomes stale when you make commits. CKB offers several ways to stay current:

Quick start for AI sessions:

ckb mcp --watch  # Auto-reindexes every 30s when stale

Check staleness:

ckb status# Shows: "5 commits behind HEAD" or "Up to date"

For Go projects, CKB uses incremental indexing—only changed files are processed, making updates fast.

See the Index Management Guide for complete documentation.

Features

📖 Full Features Guide — Detailed documentation with examples

📋 Changelog — Version history

PR Review

CKB review runs 21 quality checks in 5 seconds — secrets, breaking changes, dead code, complexity, test gaps, bug patterns, and more. Zero tokens, zero API calls.

When your AI assistant (Claude Code, Cursor, Windsurf) reviews a PR, it calls CKB first and gets structured analysis in ~1k tokens. Then it only reads the files that matter — saving 50-80% of tokens on large PRs.

ckb review --base=main              # Human-readable reviewckb review --base=main --ci         # CI mode (exit codes)ckb review --base=main --post=123   # Post as PR comment

Works in CI without any LLM:

- run: npx @tastehub/ckb review --base=main --ci --format=sarif > review.sarif

📖 How it helps AI review · Benchmarks · CI Integration · Quickstart

CLI

ckb status           # System health (with remediation suggestions)ckb search Handler   # Find symbolsckb diff-summary     # Analyze what changedckb hotspots         # Risky areasckb arch             # Architecture overviewckb ownership        # File/path ownershipckb mcp              # Start MCP server

Compound Operations (via MCP):

# These tools combine multiple queries into single callsexplore      # Area exploration: symbols, dependencies, hotspotsunderstand   # Symbol deep-dive: refs, callers, explanationprepareChange # Pre-change analysis: impact, tests, riskbatchGet     # Fetch up to 50 symbols at oncebatchSearch  # Run up to 10 searches at once

📖 User Guide — All CLI commands and options

HTTP API

# Start the HTTP serverckb serve --port 8080
# Example callscurl http://localhost:8080/healthcurl http://localhost:8080/statuscurl "http://localhost:8080/search?q=NewServer"curl http://localhost:8080/architecturecurl "http://localhost:8080/ownership?path=internal/api"curl http://localhost:8080/hotspots
# Index Server Mode (v7.3) - serve indexes to remote clientsckb serve --port 8080 --index-server --index-config config.toml
# Index server endpointscurl http://localhost:8080/index/reposcurl http://localhost:8080/index/repos/company%2Fcore-lib/metacurl "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 keyckb token list                                         # List all tokensckb token revoke ckb_xxx                              # Revoke a tokenckb token rotate ckb_xxx                              # Rotate (new secret, same ID)

MCP Integration

CKB works with any MCP-compatible AI coding tool.

# Auto-configure for current projectnpx @tastehub/ckb setup
# Or add globally for all projectsnpx @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    }  }}

# Auto-configure for current projectnpx @tastehub/ckb setup --tool=grok
# Or add globallynpx @tastehub/ckb setup --tool=grok --global

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

cd /path/to/your/repockb 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"]    }  }}

# List all available presets with tool counts and token estimatesckb mcp --list-presets
# Default: core preset (25 essential tools)ckb mcp
# Workflow-specific presetsckb mcp --preset=core        # 25 tools - search, explain, impact (default)ckb mcp --preset=review      # 42 tools - core + diff, ownership, PR reviewckb mcp --preset=refactor    # 42 tools - core + coupling, dead codeckb mcp --preset=federation  # 46 tools - core + cross-repockb mcp --preset=docs        # 34 tools - core + doc-symbol linkingckb mcp --preset=ops         # 43 tools - core + jobs, webhooks, metricsckb mcp --preset=full        # 110 tools - complete feature set

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

Under the Hood

CKB orchestrates multiple code intelligence backends, using whatever is available and stacking their strengths — more backends running means richer answers:

• Cartographer — Fast structural analysis (architecture, dependencies, blast-radius, coupling, directory rollup) that needs no index and works the moment CKB is installed. Compiled into the binary, so it ships in the npm and Homebrew builds by default.
• SCIP — Precise, pre-indexed symbol data for exact definitions, references, and call graphs (run ckb index)
• LSP — Real-time language server queries
• Git — Blame, history, churn analysis, ownership
• LIP — Semantic embedding daemon for nearest-neighbour search and re-ranking. Runs as a separate, optional daemon — install and start it alongside CKB.

Results are merged intelligently and compressed for LLM context limits. Every backend except Git is optional; CKB degrades gracefully to whatever is present.

LIP enhances semantic search, PR novelty detection, test discovery, file boundary analysis, and architecture coupling signals. When LIP is running alongside CKB, search quality improves significantly — especially for natural-language queries that don't match symbol names literally. See Hybrid Retrieval for details, or the LIP documentation.

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

Limitations (Honest Take)

CKB excels at:

• Static code navigation—finding definitions, references, call graphs
• Impact analysis for safe refactoring
• Ownership lookup (CODEOWNERS + git blame)
• Architecture and module understanding

CKB won't help with:

• Dynamic dispatch / runtime behavior (use debugger)
• Generated code that isn't indexed
• Code generation, linting, or formatting
• Cross-repo calls (use federation for this)

CKB is static analysis, not magic. Always verify critical decisions by reading the actual code.

📖 Practical Limits — Full guide on accuracy, blind spots, and when to trust results

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
• Index Management — How indexing works, auto-refresh methods
• 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, 110+ 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
• Security — Secret detection, credential scanning
• 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
• LIP v2.3+ semantic embedding daemon (requires Rust/cargo) — strongly recommended for best search quality (docs, crates.io):
  bash

  cargo install lip-clilip daemon --socket ~/.local/share/lip/lip.sock

License

Free for:

• Personal use
• Open source projects
• Startups & small businesses under $25k annual revenue

Commercial license required for organizations with $25k+ annual revenue. See pricing for Team and Enterprise plans, or LICENSE for full terms.