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—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

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
"Are there exposed secrets?"	Manual grep for patterns	Automated scanning with 26 patterns

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 codebase
ckb hotspots --format=human

# Check what changed and what might break
ckb diff-summary --format=human

# Scan for exposed secrets
ckb audit --format=human

# Check architecture at a glance
ckb arch --format=human

# Check system status
ckb status

Works Everywhere

AI Assistants	CI/CD	Your Tools
Claude Code, Cursor, Windsurf, VS Code, Grok	GitHub Actions, GitLab CI	CLI, HTTP API, Scripts

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

# One command to connect to Claude Code
ckb 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

Resource	Description
📖 Features Guide	Complete feature list with examples
💬 Prompt Cookbook	Real prompts for real problems
🔌 Integration Guide	Use CKB in your own tools and scripts
⚡ Impact Analysis	Blast radius, affected tests, PR risk
🔧 CI/CD Integration	GitHub Actions, GitLab CI templates

Quick Start

Option 1: npm (Recommended)

# Install globally
npm install -g @tastehub/ckb

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

Option 2: Homebrew (macOS/Linux)

brew tap SimplyLiz/ckb
brew install ckb

Option 3: Build from Source

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

Setup

# 1. Initialize in your project
cd /path/to/your/project
ckb 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 Code
ckb 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 v8.0.0
  Active tools: 14 / 76 (18%)
  Estimated context: ~1k 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?

Without CKB	With CKB
AI greps for patterns	AI navigates semantically
"I found 47 matches for Handler"	"HandleRequest is called by 3 routes via CheckoutService"
Guessing at impact	Knowing the blast radius with risk scores
Reading entire files for context	Getting exactly what's relevant
"Who owns this?" → search CODEOWNERS	Instant ownership with reviewer suggestions
"Is this safe to change?" → hope	Hotspot trends + impact analysis

Three Ways to Use It

Interface	Best For
MCP	AI-assisted development — Claude, Cursor, Windsurf, VS Code, OpenCode, Grok
CLI	Quick lookups from terminal, scripting
HTTP API	IDE plugins, CI integration, custom tooling

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 fresh
ckb 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:

Tier	Quality	Languages
Tier 1	Full support, all features	Go
Tier 2	Full support, minor edge cases	TypeScript, JavaScript, Python
Tier 3	Basic support, call graph may be incomplete	Rust, Java, Kotlin, C++, Ruby, Dart
Tier 4	Experimental	C#, PHP

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:

Method	Command	When to Use
Manual	`ckb index`	One-off updates, scripts
Watch mode	`ckb index --watch`	Auto-refresh during development
MCP watch	`ckb mcp --watch`	Auto-refresh in AI sessions
CI webhook	`POST /api/v1/refresh`	Trigger from CI/CD

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

Feature	Description
Compound Operations	`explore`, `understand`, `prepareChange` — single-call tools that reduce AI overhead by 60-70%
Code Navigation	Semantic search, call graphs, trace usage, find entrypoints
Impact Analysis	Blast radius, risk scoring, affected tests, breaking changes (`compareAPI`)
Architecture	Module overview, ADRs, dependency graphs, explain origin
Ownership	CODEOWNERS + git blame, reviewer suggestions, drift detection
Code Quality	Dead code detection (`findDeadCode`), coupling analysis, complexity
Security	Secret detection, credential scanning, allowlists
Documentation	Doc-symbol linking, staleness detection, coverage metrics
Multi-Repo	Federation, API contracts, remote index serving
Runtime	OpenTelemetry integration, observed usage, production dead code
Streaming	SSE streaming for `findReferences`, `searchSymbols` with real-time progress
Automation	Daemon mode, watch mode, webhooks, incremental indexing

📖 Full Features Guide — Detailed documentation with examples

📋 Changelog — Version history

CLI

ckb status           # System health (with remediation suggestions)
ckb search Handler   # Find symbols
ckb diff-summary     # Analyze what changed
ckb hotspots         # Risky areas
ckb arch             # Architecture overview
ckb ownership        # File/path ownership
ckb mcp              # Start MCP server

v8.0 Compound Operations (via MCP):

# These tools combine multiple queries into single calls
explore      # Area exploration: symbols, dependencies, hotspots
understand   # Symbol deep-dive: refs, callers, explanation
prepareChange # Pre-change analysis: impact, tests, risk
batchGet     # Fetch up to 50 symbols at once
batchSearch  # Run up to 10 searches at once

📖 User Guide — All CLI commands and options

HTTP API

# Start the HTTP server
ckb serve --port 8080

# Example calls
curl http://localhost:8080/health
curl http://localhost:8080/status
curl "http://localhost:8080/search?q=NewServer"
curl http://localhost:8080/architecture
curl "http://localhost:8080/ownership?path=internal/api"
curl http://localhost:8080/hotspots

# Index Server Mode (v7.3) - serve indexes to remote clients
ckb serve --port 8080 --index-server --index-config config.toml

# Index server endpoints
curl http://localhost:8080/index/repos
curl http://localhost:8080/index/repos/company%2Fcore-lib/meta
curl "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 key
ckb token list                                         # List all tokens
ckb token revoke ckb_xxx                              # Revoke a token
ckb token rotate ckb_xxx                              # Rotate (new secret, same ID)

MCP Integration

CKB works with any MCP-compatible AI coding tool.

Claude Code

# Auto-configure for current project
npx @tastehub/ckb setup

# Or add globally for all projects
npx @tastehub/ckb setup --global

Or manually add to .mcp.json:

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

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

VS Code

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "ckb": {
        "type": "stdio",
        "command": "npx",
        "args": ["@tastehub/ckb", "mcp"]
      }
    }
  }
}

OpenCode

Add to opencode.json in project root:

{
  "mcp": {
    "ckb": {
      "type": "local",
      "command": ["npx", "@tastehub/ckb", "mcp"],
      "enabled": true
    }
  }
}

Grok

# Auto-configure for current project
npx @tastehub/ckb setup --tool=grok

# Or add globally
npx @tastehub/ckb setup --tool=grok --global

Or manually add to .grok/settings.json (project) or ~/.grok/user-settings.json (global):

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

Claude Desktop

Claude Desktop doesn't have a project context, so you must specify the repository path.

Automatic setup (recommended):

cd /path/to/your/repo
ckb setup --tool=claude-desktop

Manual configuration — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["-y", "@tastehub/ckb", "mcp"],
      "env": {
        "CKB_REPO": "/path/to/your/repo"
      }
    }
  }
}

The CKB_REPO environment variable tells CKB which repository to analyze. Claude Desktop can only work with one repository at a time.

Windows

Use cmd /c wrapper in any config above:

{
  "mcpServers": {
    "ckb": {
      "command": "cmd",
      "args": ["/c", "npx", "@tastehub/ckb", "mcp"]
    }
  }
}

Presets (Token Optimization)

CKB exposes 80+ tools, but most sessions only need a subset. Use presets to reduce token overhead by up to 83%:

# List all available presets with tool counts and token estimates
ckb mcp --list-presets

# Default: core preset (14 essential tools)
ckb mcp

# Workflow-specific presets
ckb mcp --preset=core        # 14 tools - search, explain, impact (default)
ckb mcp --preset=review      # 19 tools - core + diff, ownership
ckb mcp --preset=refactor    # 19 tools - core + coupling, dead code
ckb mcp --preset=federation  # 28 tools - core + cross-repo
ckb mcp --preset=docs        # 20 tools - core + doc-symbol linking
ckb mcp --preset=ops         # 25 tools - core + jobs, webhooks, metrics
ckb mcp --preset=full        # 80+ tools - all tools (legacy)

In MCP config:

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

The AI can dynamically expand the toolset mid-session using the expandToolset tool.

Under the Hood

CKB orchestrates multiple code intelligence backends:

SCIP — Precise, pre-indexed symbol data (fastest)
LSP — Real-time language server queries
Git — Blame, history, churn analysis, ownership

Results are merged intelligently and compressed for LLM context limits.

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, 80+ 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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 298 Commits
.github		.github
cmd/ckb		cmd/ckb
docs		docs
examples		examples
internal		internal
metrics		metrics
npm		npm
scripts		scripts
testdata		testdata
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
codecov.yml		codecov.yml
go.mod		go.mod
go.sum		go.sum
server.json		server.json
tasks.md		tasks.md
test-api-simple.sh		test-api-simple.sh
test-api.sh		test-api.sh
test_mcp.sh		test_mcp.sh
test_mcp_protocol.py		test_mcp_protocol.py
v8-logging-improvements.md		v8-logging-improvements.md
v8-ux-improvements.md		v8-ux-improvements.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

CKB — Code Knowledge Backend

Instant Answers to Hard Questions

What You Can Do

Try It Now

Works Everywhere

Learn More

Quick Start

Option 1: npm (Recommended)

Option 2: Homebrew (macOS/Linux)

Option 3: Build from Source

Setup

Why CKB?

Three Ways to Use It

How Indexing Works

The Basics

Language Support

Keeping Your Index Fresh

Features

CLI

HTTP API

MCP Integration

Under the Hood

Who Should Use CKB?

Limitations (Honest Take)

Documentation

Requirements

License

About

Uh oh!

Releases 10

Packages

Contributors 3

Uh oh!

Languages

License

SimplyLiz/CodeMCP

Folders and files

Latest commit

History

Repository files navigation

CKB — Code Knowledge Backend

Instant Answers to Hard Questions

What You Can Do

Try It Now

Works Everywhere

Learn More

Quick Start

Option 1: npm (Recommended)

Option 2: Homebrew (macOS/Linux)

Option 3: Build from Source

Setup

Why CKB?

Three Ways to Use It

How Indexing Works

The Basics

Language Support

Keeping Your Index Fresh

Features

CLI

HTTP API

MCP Integration

Under the Hood

Who Should Use CKB?

Limitations (Honest Take)

Documentation

Requirements

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Contributors 3

Uh oh!

Languages

Packages