ckb

# CKB — Code Knowledge Backend **Know your code. Change it safely. Ship with confidence.** [](https://www.npmjs.com/package/@tastehub/ckb) [](https://codeknowledge.dev) [](https://codeknowledge.dev/docs) [](https://crates.io/crates/lip-cli) [](https://lip-sigma.vercel.app/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 | 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 ```bash # 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. ```bash # 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](https://github.com/SimplyLiz/CodeMCP/wiki/Integration-Guide)** for examples in Node.js, Python, Go, and shell scripts. --- ## Learn More | Resource | Description | |----------|-------------| | 📖 **[Features Guide](https://github.com/SimplyLiz/CodeMCP/wiki/Features)** | Complete feature list with examples | | 💬 **[Prompt Cookbook](https://github.com/SimplyLiz/CodeMCP/wiki/Prompt-Cookbook)** | Real prompts for real problems | | 🔌 **[Integration Guide](https://github.com/SimplyLiz/CodeMCP/wiki/Integration-Guide)** | Use CKB in your own tools and scripts | | ⚡ **[Impact Analysis](https://github.com/SimplyLiz/CodeMCP/wiki/Impact-Analysis)** | Blast radius, affected tests, PR risk | | 🔧 **[CI/CD Integration](https://github.com/SimplyLiz/CodeMCP/wiki/CI-CD-Integration)** | GitHub Actions, GitLab CI templates | --- ## Quick Start ### Option 1: npm (Recommended) ```bash # Install globally npm install -g @tastehub/ckb # Or run directly with npx (no install needed) npx @tastehub/ckb init ``` ### Option 2: Homebrew (macOS/Linux) ```bash brew tap SimplyLiz/ckb brew install ckb ``` ### Option 3: Build from Source ```bash git clone https://github.com/SimplyLiz/CodeMCP.git cd CodeMCP go build -o ckb ./cmd/ckb ``` ### Setup ```bash # 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 v9.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](https://github.com/SimplyLiz/CodeMCP/wiki/MCP-Integration)** | AI-assisted development — Claude, Cursor, Windsurf, VS Code, OpenCode, Grok | | **[CLI](https://github.com/SimplyLiz/CodeMCP/wiki/User-Guide)** | Quick lookups from terminal, scripting | | **[HTTP API](https://github.com/SimplyLiz/CodeMCP/wiki/API-Reference)** | 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 ```bash # 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](https://github.com/SimplyLiz/CodeMCP/wiki/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:** ```bash ckb mcp --watch # Auto-reindexes every 30s when stale ``` **Check staleness:** ```bash 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](https://github.com/SimplyLiz/CodeMCP/wiki/Index-Management)** for complete documentation. ## Features | Feature | Description | |---------|-------------| | [**Compound Operations**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#compound-operations) | `explore`, `understand`, `prepareChange` — single-call tools that reduce AI overhead by 60-70% | | [**Code Navigation**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#code-navigation--discovery) | Semantic search, call graphs, trace usage, find entrypoints | | [**Impact Analysis**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#impact-analysis--safety) | Blast radius, risk scoring, affected tests, breaking changes (`compareAPI`) | | [**Architecture**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#architectural-understanding) | Module overview, ADRs, dependency graphs, explain origin | | [**Ownership**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#ownership--review) | CODEOWNERS + git blame, reviewer suggestions, drift detection | | [**Code Quality**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#code-quality--risk) | Dead code detection (`findDeadCode`), coupling analysis, complexity | | [**Security**](https://github.com/SimplyLiz/CodeMCP/wiki/Security) | Secret detection, credential scanning, allowlists | | [**Documentation**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#documentation-intelligence) | Doc-symbol linking, staleness detection, coverage metrics | | [**Multi-Repo**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#multi-repo--federation) | Federation, API contracts, remote index serving | | [**Runtime**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#runtime-intelligence) | OpenTelemetry integration, observed usage, production dead code | | [**Streaming**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#streaming) | SSE streaming for `findReferences`, `searchSymbols` with real-time progress | | [**Automation**](https://github.com/SimplyLiz/CodeMCP/wiki/Features#automation--cicd) | Daemon mode, watch mode, webhooks, incremental indexing | 📖 **[Full Features Guide](https://github.com/SimplyLiz/CodeMCP/wiki/Features)** — Detailed documentation with examples 📋 **[Changelog](https://github.com/SimplyLiz/CodeMCP/blob/main/CHANGELOG.md)** — Version history ## PR Review CKB review runs 20 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. ```bash ckb review --base=main # Human-readable review ckb review --base=main --ci # CI mode (exit codes) ckb review --base=main --post=123 # Post as PR comment ``` Works in CI without any LLM: ```yaml - run: npx @tastehub/ckb review --base=main --ci --format=sarif > review.sarif ``` | | Without CKB | With CKB | |---|---|---| | LLM tokens on 100-file PR | ~200k | ~50k | | Files LLM reads | all | ~10 (CKB-flagged) | | Secrets/breaking/dead-code checked | no | yes (all files) | 📖 [**How it helps AI review**](docs/marketing/ckb-review/how-it-helps-llm.md) · [**Benchmarks**](docs/marketing/ckb-review/benchmarks.md) · [**CI Integration**](docs/marketing/ckb-review/ci-integration.md) · [**Quickstart**](docs/marketing/ckb-review/quickstart.md) ## CLI ```bash 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 ``` **v9.0 Compound Operations (via MCP):** ```bash # 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](https://github.com/SimplyLiz/CodeMCP/wiki/User-Guide)** — All CLI commands and options ## HTTP API ```bash # 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. <details> <summary><strong>Claude Code</strong></summary> ```bash # 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`: ```json { "mcpServers": { "ckb": { "command": "npx", "args": ["@tastehub/ckb", "mcp"] } } } ``` </details> <details> <summary><strong>Cursor</strong></summary> Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): ```json { "mcpServers": { "ckb": { "command": "npx", "args": ["@tastehub/ckb", "mcp"] } } } ``` </details> <details> <summary><strong>Windsurf</strong></summary> Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "ckb": { "command": "npx", "args": ["@tastehub/ckb", "mcp"] } } } ``` </details> <details> <summary><strong>VS Code</strong></summary> Add to your VS Code `settings.json`: ```json { "mcp": { "servers": { "ckb": { "type": "stdio", "command": "npx", "args": ["@tastehub/ckb", "mcp"] } } } } ``` </details> <details> <summary><strong>OpenCode</strong></summary> Add to `opencode.json` in project root: ```json { "mcp": { "ckb": { "type": "local", "command": ["npx", "@tastehub/ckb", "mcp"], "enabled": true } } } ``` </details> <details> <summary><strong>Grok</strong></summary> ```bash # 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): ```json { "mcpServers": { "ckb": { "name": "ckb", "transport": "stdio", "command": "npx", "args": ["@tastehub/ckb", "mcp"] } } } ``` </details> <details> <summary><strong>Claude Desktop</strong></summary> Claude Desktop doesn't have a project context, so you must specify the repository path. **Automatic setup** (recommended): ```bash 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): ```json { "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. </details> <details> <summary><strong>Windows</strong></summary> Use `cmd /c` wrapper in any config above: ```json { "mcpServers": { "ckb": { "command": "cmd", "args": ["/c", "npx", "@tastehub/ckb", "mcp"] } } } ``` </details> <details> <summary><strong>Presets (Token Optimization)</strong></summary> CKB exposes 80+ tools, but most sessions only need a subset. Use presets to reduce token overhead by up to 83%: ```bash # 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: ```json { "mcpServers": { "ckb": { "command": "npx", "args": ["@tastehub/ckb", "mcp", "--preset=review"] } } } ``` The AI can dynamically expand the toolset mid-session using the `expandToolset` tool. </details> ## 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 - **LIP** — Semantic embedding daemon for nearest-neighbour search and re-ranking (optional, recommended) Results are merged intelligently and compressed for LLM context limits. > **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](https://github.com/SimplyLiz/CodeMCP/wiki/Hybrid-Retrieval) for details, or the [LIP documentation](https://lip-sigma.vercel.app/docs). 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](https://github.com/SimplyLiz/CodeMCP/wiki/Federation) for this) > CKB is static analysis, not magic. Always verify critical decisions by reading the actual code. 📖 **[Practical Limits](https://github.com/SimplyLiz/CodeMCP/wiki/Practical-Limits)** — Full guide on accuracy, blind spots, and when to trust results ## Documentation See the **[Full Documentation Wiki](https://github.com/SimplyLiz/CodeMCP/wiki)** for: - [Quick Start](https://github.com/SimplyLiz/CodeMCP/wiki/Quick-Start) — Step-by-step installation - [Prompt Cookbook](https://github.com/SimplyLiz/CodeMCP/wiki/Prompt-Cookbook) — Real prompts for real problems - [Language Support](https://github.com/SimplyLiz/CodeMCP/wiki/Language-Support) — SCIP indexers and support tiers - [Practical Limits](https://github.com/SimplyLiz/CodeMCP/wiki/Practical-Limits) — Accuracy notes, blind spots - [User Guide](https://github.com/SimplyLiz/CodeMCP/wiki/User-Guide) — CLI commands and best practices - [Index Management](https://github.com/SimplyLiz/CodeMCP/wiki/Index-Management) — How indexing works, auto-refresh methods - [Incremental Indexing](https://github.com/SimplyLiz/CodeMCP/wiki/Incremental-Indexing) — Fast index updates for Go projects - [Doc-Symbol Linking](https://github.com/SimplyLiz/CodeMCP/wiki/Doc-Symbol-Linking) — Symbol detection in docs, staleness checking - [Authentication](https://github.com/SimplyLiz/CodeMCP/wiki/Authentication) — API tokens, scopes, rate limiting - [MCP Integration](https://github.com/SimplyLiz/CodeMCP/wiki/MCP-Integration) — Claude Code setup, 80+ tools - [API Reference](https://github.com/SimplyLiz/CodeMCP/wiki/API-Reference) — HTTP API documentation - [Daemon Mode](https://github.com/SimplyLiz/CodeMCP/wiki/Daemon-Mode) — Always-on service with scheduler, webhooks - [Configuration](https://github.com/SimplyLiz/CodeMCP/wiki/Configuration) — All options including MODULES.toml - [Architecture](https://github.com/SimplyLiz/CodeMCP/wiki/Architecture) — System design and components - [Security](https://github.com/SimplyLiz/CodeMCP/wiki/Security) — Secret detection, credential scanning - [Telemetry](https://github.com/SimplyLiz/CodeMCP/wiki/Telemetry) — Runtime observability, dead code detection - [Federation](https://github.com/SimplyLiz/CodeMCP/wiki/Federation) — Cross-repository queries - [CI/CD Integration](https://github.com/SimplyLiz/CodeMCP/wiki/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.0](https://lip-sigma.vercel.app) semantic embedding daemon (requires Rust/cargo) — strongly recommended for best search quality ([docs](https://lip-sigma.vercel.app/docs), [crates.io](https://crates.io/crates/lip-cli)): ```bash cargo install lip-cli lip 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](https://codeknowledge.dev/pricing) for Team and Enterprise plans, or [LICENSE](LICENSE) for full terms.