Skip to content

Features

Jump to bottom
Lisa edited this page Jan 2, 2026 · 11 revisions

CKB Features

CKB (Code Knowledge Backend) gives AI assistants deep understanding of your codebase. This guide organizes all features by what you can accomplish rather than by version or implementation.

What Can CKB Be Used For?

Onboarding & Code Understanding

Scenario: You just joined a team or opened an unfamiliar repo.

Task How CKB Helps
"What does this codebase do?" ckb arch shows module structure and dependencies
"Where's the main entry point?" ckb entrypoints lists API handlers, CLI commands, jobs
"What are the key concepts?" ckb concepts surfaces important domain patterns
"Who owns this code?" ckb ownership <file> shows CODEOWNERS + recent contributors

Safe Refactoring

Scenario: You need to rename, move, or delete code without breaking things.

Task How CKB Helps
"What breaks if I change this?" ckb impact <symbol> shows all callers and blast radius
"Is this code safe to delete?" ckb justify <symbol> gives keep/investigate/remove verdict
"What tests should I run?" ckb affected-tests finds tests covering your changes
"Is my refactor risky?" ckb impact diff analyzes uncommitted changes

Code Review & PR Analysis

Scenario: You're reviewing a PR or preparing one for review.

Task How CKB Helps
"Who should review this?" ckb reviewers suggests reviewers from CODEOWNERS + git history
"How risky is this PR?" ckb pr-summary gives risk assessment with impact analysis
"What's the blast radius?" ckb impact diff --base=main shows downstream effects

Reducing CI Time

Scenario: Your test suite takes 30 minutes but you only changed one file.

Task How CKB Helps
Run only affected tests ckb affected-tests --output=command generates test command
Skip if index is fresh ckb index --if-stale=24h in CI avoids redundant work
Incremental indexing Only changed files reindexed (Go projects)

Technical Debt Prioritization

Scenario: You have limited time—what should you fix first?

Task How CKB Helps
Find highest-risk code ckb hotspots shows high-churn + high-complexity files
Get quick wins ckb audit --quick-wins finds high-impact, low-effort fixes
Find dead code ckb dead-code identifies unused symbols
Find hidden coupling ckb coupling <file> shows files that change together

Documentation Maintenance

Scenario: Your docs reference code that no longer exists.

Task How CKB Helps
Find stale docs ckb docs stale --all finds broken symbol references
Check coverage ckb docs coverage shows what % of code is documented
Link docs to code ckb docs symbol <name> finds docs mentioning a symbol

Microservices & Cross-Repo Work

Scenario: You're changing an API used by other services.

Task How CKB Helps
Find API consumers ckb contracts impact <proto> shows who uses your API
Search across repos ckb federation search-modules <query> searches all repos
Aggregate hotspots ckb federation hotspots shows volatility across services

AI-Assisted Development

Scenario: You're using Claude, Cursor, or another AI coding tool.

Task How CKB Helps
Give AI context CKB provides semantic code understanding via MCP
Reduce token usage Presets expose only needed tools (~2k vs 9k tokens)
Keep AI accurate Index freshness ensures AI sees current code

CKB's MCP integration means your AI assistant can answer questions like:

  • "What will break if I rename UserService?"
  • "Find all places that handle authentication"
  • "Who should review changes to the payment module?"

Quick Reference

Jump to any feature:

Category Key Features Best For
Code Navigation Symbol Search · Call Graph · Trace Usage · Entrypoints Finding and understanding code
Impact Analysis Blast Radius · Change Impact · Affected Tests · Risk Scoring · Hotspots · PR Summary Safe refactoring and changes
Architecture Module Overview · ADRs · Explain Origin Understanding system design
Ownership CODEOWNERS · Ownership Drift · Reviewer Suggestions Code review and accountability
Code Quality Dead Code · Coupling · Justify Symbol · Quick Wins Technical debt reduction
Documentation Doc-Symbol Linking · Staleness Detection · Coverage Keeping docs accurate
Multi-Repo Federation · Contracts · Remote Serving Cross-repo visibility
Runtime Telemetry · Observed Usage · Production Dead Code Production insights
Automation Daemon · Watch Mode · Webhooks · Incremental Index CI/CD integration
System Health Enhanced Status · Reindex · Error Codes · Breaking Changes · Compound Tools Reliability & diagnostics

Code Navigation & Discovery

Why This Matters

The Problem: In large codebases, developers spend 60%+ of their time reading and understanding code. AI assistants make this worse by guessing at code structure, returning text matches instead of semantic results, and missing cross-file relationships.

The Solution: CKB provides semantic code navigation—find any symbol instantly, trace how code flows through your system, and understand what matters without reading every file.

When to Use

  • Onboarding to a new codebase
  • Understanding unfamiliar code before modifying it
  • Finding all the places that use a particular function
  • Tracing how a request flows through your system
  • Identifying the main entry points of an application

Features

Symbol Search

Find functions, types, interfaces, and variables by name with semantic understanding.

ckb search "Handler"           # Find all Handler-related symbols
ckb search "User" --kind=type  # Find only types

Value: Unlike grep, this finds semantic matches—UserHandler when you search "Handler", even if "Handler" isn't a substring.

Find References

All places a symbol is used across your entire codebase.

ckb refs "internal/api.HandleRequest"

Value: Returns semantic references, not text matches. Won't match comments or strings containing the same text.

Call Graph

See who calls a function and what it calls—the backbone of impact analysis.

ckb callgraph "ProcessPayment" --depth=2

Value: Understand the dependency chain. If ProcessPayment fails, what else breaks?

Trace Usage

How is this symbol reached from system entry points?

ckb trace "sendEmail"

Value: Answers "How does a user action eventually trigger this code?" Shows the path from API handlers, CLI commands, or background jobs.

List Entrypoints

API handlers, CLI commands, scheduled jobs, event handlers.

ckb entrypoints

Value: Quickly understand what your application actually does—its public surface area.

Key Concepts

The most important symbols and patterns in the codebase.

ckb concepts

Value: Get oriented in an unfamiliar codebase. Surfaces the domain concepts that matter most.

Explain File / Explain Path

Understand why a file or directory exists.

Value: "What is internal/adapters/ for?" Get architectural context without reading every file.

Recently Relevant

What files and symbols have been active lately?

Value: Focus on what matters now, not ancient code nobody touches.

How It Works

CKB uses a backend ladder for queries:

  1. SCIP — Pre-computed index (fastest, most accurate)
  2. LSP — Language server (real-time, slightly slower)
  3. Git — Fallback for basic operations

Hybrid Retrieval (v7.4): Search combines text matching with graph-based ranking (Personalized PageRank) to surface structurally related symbols, achieving 100% recall on benchmarks.

Example Prompts

"Find all functions that handle HTTP requests" "Show me the call graph for ProcessPayment" "What code paths lead to sendEmail?" "List the main entry points in this service" "What are the key domain concepts in this codebase?"

See also: User-Guide#cli-commands, Hybrid-Retrieval

Impact Analysis & Safety

Why This Matters

The Problem: Refactoring is risky. A "simple rename" can break production. Developers either avoid changes (accumulating tech debt) or make changes blind (causing incidents).

The Solution: CKB tells you exactly what will break before you change it. Know the blast radius, understand the risk, and make informed decisions.

When to Use

  • Before refactoring any code
  • Reviewing pull requests
  • Deciding whether to delete "dead" code
  • Prioritizing which tech debt to pay down
  • Assessing risk of a change

Features

Impact Analysis

The blast radius of changing a symbol—who depends on it?

ckb impact "UserService.Authenticate"

Value: Shows all callers across all modules, with module spread and risk score. A function called from 1 place is safe to change; one called from 47 places across 12 modules needs careful planning.

v7.6 Enhancements:

  • Transitive callers: See not just direct callers, but callers-of-callers up to depth 4
  • Blast radius summary: Quick metrics—module count, file count, unique callers, risk level
  • Confidence scoring: Decreasing confidence at deeper levels (0.85 → 0.75 → 0.65)
Blast Radius Level Criteria
Low ≤2 modules AND ≤5 callers
Medium 3-5 modules OR 6-20 callers
High >5 modules OR >20 callers

Change Impact Analysis (v7.5)

Analyze the impact of code changes from git diffs before committing.

# Analyze current working tree changes
ckb impact diff

# Analyze only staged changes
ckb impact diff --staged

# Compare against a different branch
ckb impact diff --base=main

# Deeper transitive analysis
ckb impact diff --depth=3

Value: Understand what downstream code might break before you push. Maps changed lines to SCIP symbols and runs impact analysis on each.

Key Features:

  • Confidence scoring: 1.0 (exact definition), 0.8 (body change), 0.7 (reference), 0.3 (file-level)
  • Aggregated risk: Weighted factors—symbols changed (20%), direct impact (30%), transitive impact (20%), module spread (30%)
  • Staleness detection: Warns when SCIP index is behind HEAD; use --strict to fail
  • Recommendations: Actionable suggestions (review, test, split) based on analysis
  • Coverage configuration (v7.5): Configure custom coverage paths in .ckb/config.json

See: Impact-Analysis for full documentation.

Risk Audit

Multi-factor risk scoring based on 8 weighted signals.

ckb audit "internal/payments"
ckb audit --quick-wins  # High-impact, low-risk improvements

Value: Prioritize what to fix. Don't refactor randomly—fix the highest-risk code first.

Factor Weight Description
Complexity 20% Cyclomatic/cognitive complexity
Test Coverage 20% Lack of test coverage
Bus Factor 15% Single-author code
Security 15% Handles auth, crypto, PII
Staleness 10% Not touched in 6+ months
Error Rate 10% Runtime error frequency
Coupling 5% High co-change coupling
Churn 5% Frequent modifications

Hotspot Detection

High-churn + high-complexity files—where bugs hide.

ckb hotspots
ckb hotspots --trend  # Show 30-day trend

Value: Research shows hotspots predict future bugs. Fix these first.

Diff Summary

What changed in a diff and what might break?

ckb diff-summary HEAD~1..HEAD

Value: Quick risk assessment of any commit or range of commits.

PR Summary

Pull request analysis with risk assessment and reviewer suggestions.

ckb pr-summary --base=main --head=feature-branch

Value: Automated first-pass code review. Catches risky changes before humans review.

Affected Tests (v7.5)

Find which tests to run based on your code changes.

ckb affected-tests                    # Tests for uncommitted changes
ckb affected-tests --format=list      # One test per line (for CI)
ckb affected-tests --output=command   # Ready-to-run command
ckb affected-tests --strategy=safe    # Include transitive tests (default)

Value: Dramatically reduce CI time by running only relevant tests. Maps changed symbols to test files via SCIP and coverage data.

Strategies:

Strategy Description
precise Only tests directly covering changed lines
safe Include transitive tests (default)
full All tests in affected packages

See also: Impact-Analysis#affected-tests-v75

Breaking Changes

Detect signature or contract changes that break callers.

ckb impact "MyAPI" --breaking

Value: Find changes that require updating callers—before you merge.

Example Prompts

"What will break if I rename UserService?" "Analyze the risk of this PR" "Which tests should I run for my changes?" "Which files are the most dangerous to change?" "Is it safe to delete legacyHandler?" "Give me quick wins for reducing technical debt"

See also: User-Guide#ckb-impact, User-Guide#ckb-audit

Architectural Understanding

Why This Matters

The Problem: Architecture knowledge lives in people's heads. When they leave, it's lost. New developers can't understand why code is structured the way it is. "Why did we choose Redis?" has no written answer.

The Solution: CKB captures and surfaces architectural knowledge—module boundaries, responsibilities, and decision records (ADRs). Architecture becomes queryable.

When to Use

  • Onboarding new team members
  • Understanding why past decisions were made
  • Documenting new architectural decisions
  • Reviewing module boundaries and responsibilities
  • Explaining unfamiliar code to AI assistants

Features

Architecture Overview

High-level structure showing module dependencies.

ckb arch

Value: Get a map of the system in seconds. See how modules connect without reading every import statement.

Module Overview

Boundaries, responsibilities, and owners for any module.

ckb modules
ckb modules internal/auth

Value: Understand what a module is supposed to do, not just what files it contains.

Module Responsibilities

What each module is responsible for.

Value: "What does the internal/events module handle?" Get a concise answer.

Architectural Decision Records (ADRs)

Document and query important architectural choices.

# Create an ADR
ckb decisions create \
  --title "Use Redis for caching" \
  --context "User sessions need fast access" \
  --decision "Redis with 1-hour TTL" \
  --module internal/cache

# Query ADRs
ckb decisions --search "caching"

Value: Architecture decisions survive team changes. "Why Redis?" has a searchable answer. ADRs automatically surface in explain, justify, and impact commands.

Explain Symbol

Full context for any symbol—origin, evolution, warnings.

ckb explain "LegacyParser"

Value: Understand not just what code does, but why it exists and whether it's safe to touch.

Explain Origin

Trace history through renames and moves.

ckb origin "CurrentName"

Value: "This was called X before, renamed in commit Y by Z for reason W."

Example Prompts

"Give me an architecture overview" "What is the internal/auth module responsible for?" "Why was Redis chosen for caching?" "Explain why LegacyParser exists and who added it" "What architectural decisions affect the payment system?"

See also: Configuration#architectural-decision-records, User-Guide#ckb-decisions

Ownership & Review

Why This Matters

The Problem: Code reviews are slow because finding the right reviewer is hard. CODEOWNERS files get stale. The person who "owns" code in CODEOWNERS hasn't touched it in 2 years.

The Solution: CKB combines explicit ownership (CODEOWNERS) with actual git history to find who really owns code and who should review changes.

When to Use

  • Finding the right reviewer for a PR
  • Identifying who to ask about unfamiliar code
  • Detecting ownership drift (CODEOWNERS vs reality)
  • Understanding team boundaries

Features

Ownership Lookup

Who owns this code? Combines CODEOWNERS with git blame.

ckb ownership internal/api/handler.go
ckb ownership --module internal/auth

Value: Get the real owner, not just what CODEOWNERS says. Time-weighted blame gives higher weight to recent contributors.

Ownership Drift

When CODEOWNERS doesn't match reality.

ckb ownership-drift

Value: Keep CODEOWNERS accurate. Find modules where the listed owner hasn't contributed in months.

Reviewer Suggestions

Who should review this change?

Built into summarizePr—automatically suggests reviewers based on:

  • CODEOWNERS rules
  • Recent contributors to affected files
  • Module expertise

Value: Stop guessing who should review. Get data-driven suggestions.

Recent Contributors

Who has been active in this area?

ckb recent internal/payments

Value: Find the people who actually know this code right now.

How Ownership Works

CKB combines multiple signals:

  • CODEOWNERS — Explicit ownership rules (100% confidence)
  • Git Blame — Weighted by recency, filters bot commits
  • Commit History — Active contributors in time window

Example Prompts

"Who owns the authentication code?" "Who should review changes to payment/processor.go?" "Has ownership of the API layer changed recently?" "Who has been working on the search module?"

See also: User-Guide#ckb-ownership

Code Quality & Risk

Why This Matters

The Problem: Technical debt accumulates invisibly. Teams don't know which code is most dangerous. Dead code lingers forever. Refactoring efforts are scattered and unfocused.

The Solution: CKB quantifies code quality—find hotspots, detect dead code, analyze coupling, and prioritize improvements based on data.

When to Use

  • Planning refactoring efforts
  • Deciding what to delete
  • Finding high-risk code before it causes problems
  • Prioritizing tech debt reduction
  • Preparing codebase for new developers

Features

Hotspots

Files with high churn AND high complexity—where bugs live.

ckb hotspots
ckb hotspots --trend  # 30-day projection

Value: Research shows hotspots predict 70%+ of future defects. Fix these first.

Complexity Analysis

Cyclomatic and cognitive complexity per file.

ckb complexity internal/query/engine.go

Value: Find files that are too complex to maintain safely.

Coupling Analysis

Files that change together—hidden dependencies.

ckb coupling internal/query/engine.go --min-correlation=0.5

Value: High coupling means changes ripple unexpectedly. These are refactoring candidates.

Dead Code Detection

Code with no references (static) or no runtime calls (with telemetry).

ckb dead-code
ckb dead-code --min-confidence=0.8

Value: Delete code safely. Less code = fewer bugs, faster builds, easier onboarding.

Justify Symbol

Keep, investigate, or remove? A verdict for any symbol.

ckb justify "oldHelper"

Returns one of:

  • keep — Has references, is entrypoint, or has ADR justifying it
  • investigate — Unclear, needs human review
  • remove — No references, no runtime usage, safe to delete

Value: Don't guess about dead code. Get a data-driven verdict.

Quick Wins

High-impact, low-risk improvements.

ckb audit --quick-wins

Value: Get immediate ROI from refactoring. Fix the easy things first.

Export for LLM

LLM-optimized codebase export with importance ranking.

ckb export --min-complexity=10 --max-symbols=200

Value: Feed your AI assistant the most important symbols, not random files.

Example Prompts

"What are the top hotspots in this codebase?" "Is oldHelper still used anywhere?" "Which files always change together?" "Give me quick wins for reducing technical debt" "What code can I safely delete?"

See also: User-Guide#ckb-hotspots, User-Guide#ckb-justify, Telemetry

Documentation Intelligence

Why This Matters

The Problem: Documentation lies. Code changes, docs don't. References to OldClassName stay in docs forever. There's no way to know if docs are accurate.

The Solution: CKB links documentation to code symbols and detects when references become stale. Enforce documentation coverage in CI.

When to Use

  • Maintaining API documentation
  • Finding docs that reference specific code
  • Detecting outdated documentation
  • Enforcing documentation standards in CI
  • Keeping READMEs accurate

Features

Doc-Symbol Linking

Connect documentation to code symbols automatically.

ckb docs index

Value: CKB scans your markdown for code references and links them to actual symbols.

Detection methods:

  • Backticks: UserService.Authenticate in markdown
  • Directives: <!-- ckb:symbol internal.auth.UserService -->
  • Fenced Code: Parses code blocks in 8 languages

Find Docs for Symbol

What documentation mentions this code?

ckb docs symbol "Engine.Start"

Value: "Is this function documented anywhere?" Get an instant answer.

Find Symbols in Doc

What code does this document reference?

ckb docs file README.md

Value: See all the code symbols a document claims to document.

Staleness Detection

Find documentation with broken or renamed symbol references.

ckb docs stale
ckb docs stale README.md

Value: Find docs that lie. If a symbol was renamed, CKB tells you the new name.

Coverage Metrics

Documentation coverage statistics.

ckb docs coverage
ckb docs coverage --fail-under=80  # CI enforcement

Value: Track and enforce documentation standards.

Example Prompts

"What documentation mentions Engine.Start?" "Are there any stale references in our README?" "What's our documentation coverage?" "Which symbols are completely undocumented?"

See also: Doc-Symbol-Linking

Multi-Repo & Federation

Why This Matters

The Problem: Microservices and monorepos create silos. You can't search across repos. API changes in one repo break consumers in another. There's no cross-repo visibility.

The Solution: CKB federation provides unified search and analysis across multiple repositories. Find symbols, trace contracts, and analyze impact organization-wide.

When to Use

  • Searching across all your microservices
  • Understanding API consumers before changing contracts
  • Finding hotspots across an entire platform
  • Serving indexes to remote teams
  • Managing multiple local repositories

Features

Federation Management

Create and manage collections of repositories.

ckb federation create platform --description "Our microservices"
ckb federation add platform --repo-id=api --path=/code/api
ckb federation sync platform

Value: Query across all repos as if they were one codebase.

Cross-Repo Search

Search modules, ownership, and decisions across all federated repos.

Value: "Find all authentication modules across our microservices"—answered in seconds.

Cross-Repo Hotspots

Aggregated hotspots across all repositories.

ckb federation hotspots platform

Value: See which repos and files are most volatile across your entire platform.

Contract Detection

Find Protocol Buffer and OpenAPI contracts.

ckb contracts list platform
Type Extensions Detection
Protocol Buffers .proto Package, imports, services
OpenAPI .yaml, .json Paths, servers, version

Value: Know what APIs exist across your organization.

Contract Impact

What breaks if you change an API?

ckb contracts impact platform --repo=api --path=proto/user.proto

Value: Before changing a proto, know all consumers—direct and transitive.

Remote Index Serving

Serve indexes over HTTP for remote clients.

ckb serve --index-server --index-config config.toml

Value: Central teams can serve indexes to the entire organization.

Remote Federation

Query remote CKB servers alongside local repos.

ckb federation add-remote platform prod --url=https://ckb.company.com
ckb federation search-hybrid platform "Handler"

Value: Distributed code intelligence—query across teams without sharing databases.

Repo Registry

Register and switch between local repositories.

ckb repo add api /code/api
ckb repo add frontend /code/frontend
ckb mcp --repo=api

Value: Manage multiple projects without changing directories.

Example Prompts

"Find all authentication modules across our microservices" "What services consume the User API?" "Show hotspots across all backend repos" "Who should I notify before changing user.proto?"

See also: Federation, Configuration#index-server-configuration-v73, Authentication

Runtime Intelligence

Why This Matters

The Problem: Static analysis can't tell you what code actually runs in production. You might delete "dead" code that's actually called by a critical cron job. Impact analysis misses runtime call patterns.

The Solution: CKB integrates with OpenTelemetry to ingest production call data. Know which functions are actually called, how often, and by whom.

When to Use

  • Finding truly dead code (never called in production)
  • Enriching impact analysis with production data
  • Understanding which code paths are critical
  • Validating static analysis with runtime reality

Features

Telemetry Integration

Ingest OTLP metrics from your production systems.

ckb telemetry status

Value: Connect production behavior to code understanding.

Service Mapping

Map service names to repositories.

{
  "telemetry": {
    "serviceMap": {
      "api-gateway": "repo-api",
      "user-service": "repo-users"
    }
  }
}

Value: CKB knows that calls to "api-gateway" map to the "repo-api" codebase.

Observed Usage

Which functions are actually called in production?

ckb telemetry usage --symbol="HandleRequest"

Value: See real call counts, not just static analysis guesses.

Dead Code from Telemetry

Find code that's never called in production.

ckb dead-code --source=telemetry

Value: Delete with confidence. If telemetry says it's never called, it's really dead.

Coverage Levels

How much of your code has telemetry coverage?

Level Score Feature Access
High ≥ 0.80 Full: dead code, impact enrichment
Medium ≥ 0.60 Partial: with warnings
Low ≥ 0.40 Limited: usage display only
Insufficient < 0.40 None: telemetry features disabled

Example Prompts

"Is legacyEndpoint actually used in production?" "What's our telemetry coverage?" "Find functions that haven't been called in 30 days" "Which endpoints are most heavily used?"

See also: Telemetry, Configuration#telemetry-v64

Automation & CI/CD

Why This Matters

The Problem: Manual index updates are forgotten. Stale indexes give wrong answers. PR analysis is manual and inconsistent. There's no automation.

The Solution: CKB runs as a service with automatic updates, scheduled tasks, webhooks, and CI integration.

When to Use

  • Keeping indexes fresh automatically
  • Running CKB as an always-on service
  • Integrating with CI/CD pipelines
  • Automating PR analysis
  • Triggering reindexing from webhooks

Features

Daemon Mode

Run CKB as an always-on service.

ckb daemon start
ckb daemon status
ckb daemon stop

Value: Background service with HTTP API, scheduled tasks, and file watching.

Watch Mode

Auto-reindex when files change.

ckb mcp --watch          # During AI sessions
ckb index --watch        # Standalone

Value: Never have a stale index. Changes are detected and indexed automatically.

Webhook Refresh

Trigger reindexing via HTTP.

curl -X POST http://localhost:9120/api/v1/refresh

Value: CI/CD can trigger reindexing after each merge.

Scheduled Tasks

Cron-style task scheduling.

ckb daemon schedule "0 */6 * * *" "ckb index"

Value: Regular maintenance without manual intervention.

Webhooks

Notify external systems on events.

Value: Trigger downstream actions when indexes update, decisions change, etc.

Token Management

Scoped API tokens for secure access.

ckb token create --name "CI" --scopes write
ckb token revoke ckb_key_xxx

Value: Secure multi-tenant access with rate limiting.

Update Notifications

Automatic update checking for all installation methods.

╭─────────────────────────────────────────────────────╮
│  Update available: 7.3.0 → 7.4.0                    │
│  Run: npm update -g @tastehub/ckb                   │
╰─────────────────────────────────────────────────────╯

Value: Never miss updates. Shows at command start from 24-hour cache. Disable with CKB_NO_UPDATE_CHECK=1.

Orphaned Index Detection

ckb doctor detects indexes pointing to repos that no longer exist.

ckb doctor
# ✓ orphaned-indexes: Index cache: 234 MB (12 repos), 2 orphaned
#   → ckb cache clean --orphaned

Value: Clean up stale index data after moving or deleting projects.

Incremental Indexing

Fast updates—only reindex changed files (Go only).

Scenario Full Index Incremental
10,000 files ~60s ~2-5s
Single file change ~60s ~1s

Value: Keep indexes fresh without waiting minutes for each update.

PR Analysis

Automated risk assessment in CI.

- name: Analyze PR
  run: |
    ckb index
    ckb pr-summary --base=main --head=${{ github.head_ref }}

Value: Catch risky changes before human review. Automate first-pass analysis.

Example CI Workflow

name: CKB Analysis
on: [pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for blame

      - name: Install CKB
        run: npm install -g @tastehub/ckb

      - name: Index
        run: ckb index

      - name: Analyze PR
        run: ckb pr-summary --base=main

See also: Daemon-Mode, CI-CD-Integration, Incremental-Indexing, Authentication

MCP Integration

Why This Matters

The Problem: MCP tool definitions consume tokens. Some servers use 50-80k tokens just for tool definitions before you ask a single question.

The Solution: CKB uses presets—load only the tools you need. Start with 14 core tools (~2k tokens) and expand dynamically.

Tool Presets

Preset Tools Tokens Best For
core 14 ~2k General development (default)
review 19 ~2k PR reviews, ownership
refactor 19 ~2k Refactoring, dead code
docs 20 ~2k Documentation maintenance
ops 25 ~2k CKB administration
federation 28 ~3k Multi-repo work
full 81 ~9k Everything 
ckb mcp --preset=review
ckb mcp --list-presets

Dynamic Expansion

Start with core and let the AI expand mid-session:

{
  "name": "expandToolset",
  "arguments": {
    "preset": "federation",
    "reason": "User asked about cross-repository dependencies"
  }
}

Value: 83% token savings while maintaining full functionality.

See also: Presets, MCP-Integration

Analysis Tiers

CKB operates in three tiers based on available backends:

Tier Requirements Features
Fast None Tree-sitter parsing, basic search
Standard SCIP index Full cross-references, call graphs
Full SCIP + Telemetry Runtime usage, dead code detection 
ckb search "Handler" --tier=fast
export CKB_TIER=standard
ckb doctor --tier=standard

See also: User-Guide#analysis-tiers-v72, Practical-Limits

System Health & Reliability (v8.0)

Why This Matters

The Problem: When CKB returns incomplete or stale results, it's not always clear why. Is the index outdated? Is a backend unavailable? What should you do to fix it?

The Solution: v8.0 focuses on reliability and error clarity—every response includes health context, and every error includes actionable remediation.

Features

Enhanced Status

The getStatus tool now provides comprehensive health information:

ckb status

Returns:

  • Backend health tiers: available, degraded, unavailable
  • Remediation: Specific steps to fix unavailable backends
  • Index freshness: Commits behind, stale detection
  • Suggestions: Actionable next steps

Value: Know immediately why results might be incomplete and how to fix it.

Reindex Tool

Trigger index refresh without restarting CKB:

# Via MCP
{"tool": "reindex", "params": {"scope": "full"}}

# CLI
ckb index

Scope options:

  • full — Reindex everything
  • incremental — Only changed files (Go only)

Value: Keep indexes fresh during AI sessions without leaving your tool.

Structured Error Codes

All errors include remediation guidance:

{
  "code": "INDEX_STALE",
  "message": "SCIP index is 5 commits behind HEAD",
  "remediation": "Run 'ckb index' or use the reindex MCP tool",
  "drilldowns": [{"tool": "getStatus", "reason": "Check full system status"}]
}

Key error codes:

Code Description
INDEX_STALE Index needs refresh
BACKEND_UNAVAILABLE Backend not available
AMBIGUOUS_QUERY Multiple symbols match
PARTIAL_RESULT Incomplete but usable result

Value: Never wonder why something failed. Every error tells you what to do.

Breaking Change Detection

Compare API versions to detect breaking changes:

ckb compare-api --base=main --head=feature

Value: Catch signature changes, removed symbols, and contract breaks before merging.

Compound Operations

v8.0 introduces compound tools that aggregate multiple granular queries, reducing AI tool calls by 60-70%:

Tool Replaces Use Case
explore explainFile + searchSymbols + getCallGraph + getHotspots Initial codebase exploration
understand searchSymbols + getSymbol + explainSymbol + findReferences + getCallGraph Deep-dive into a symbol
prepareChange analyzeImpact + getAffectedTests + analyzeCoupling Pre-change risk assessment
batchGet Multiple getSymbol calls Fetch many symbols by ID
batchSearch Multiple searchSymbols calls Search for multiple patterns

Example:

// Before: 4 separate tool calls
explainFile({ "filePath": "internal/query" })
searchSymbols({ "query": "Engine" })
getHotspots({ "scope": "internal/query" })
getCallGraph({ "symbolId": "..." })

// After: 1 compound call
explore({ "target": "internal/query", "depth": "standard" })

Value: Faster AI workflows, lower token usage, comprehensive responses in single calls.

See also: MCP-Tools#compound-operations-v80, API-Reference#error-codes-v80, MCP-Tools#getStatus, MCP-Tools#reindex

Language Support

CKB classifies languages into quality tiers:

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

Key limitations:

  • Incremental indexing is Go-only
  • TypeScript monorepos may need --infer-tsconfig
  • C/C++ requires compile_commands.json
  • Python works best with activated virtual environment
ckb doctor --tier standard

See also: Language-Support

Response Quality

CKB provides metadata about result quality.

Confidence Tiers

Tier Score Meaning
High ≥ 0.95 Fresh SCIP data, definitive
Medium 0.70-0.94 Good data, minor caveats
Low 0.30-0.69 Stale or incomplete data
Speculative < 0.30 Cross-repo or heuristic

Provenance

Results show which backends contributed:

  • scip — From SCIP index
  • git — From git history
  • lsp — From language server
  • treesitter — From tree-sitter parsing

Drilldowns

When results are truncated, CKB suggests follow-up queries:

{
  "suggestedNextCalls": [
    {
      "tool": "findReferences",
      "params": {"symbolId": "..."},
      "reason": "47 references found, showing 10"
    }
  ]
}

See also: API-Reference

What CKB Doesn't Do

CKB is static analysis with optional runtime enrichment. It has known limitations:

Limitation Why Workaround
Dynamic dispatch Can't see runtime types Check implementations manually
Generated code May not be indexed Regenerate before indexing
Cross-repo callers Indexes one repo at a time Use federation
Runtime behavior Static analysis only Use debugger/profiler
Code generation Not CKB's job Use AI assistant directly
Linting/formatting Not CKB's job Use ESLint, Prettier, etc.

See also: Practical-Limits

Getting Started

# 1. Install
npm install -g @tastehub/ckb

# 2. Initialize
cd /your/project
ckb init

# 3. Index
ckb index

# 4. Configure AI tool
ckb setup --tool=claude-code

# 5. Start exploring
ckb arch
ckb search "Handler"
ckb hotspots

See also: Quick-Start, User-Guide, MCP-Integration

Clone this wiki locally