Skip to content
Back to News
guide
claude-code
setup

CKB + Claude Code: The Complete Setup Guide

By CKB Team

Claude Code is Anthropic's CLI tool for AI-assisted development. CKB supercharges it with deep code understanding. This guide walks through the complete setup.

What You'll Get

After setup, Claude Code will be able to:

  • Find all callers of any function (not just text matches)
  • Assess impact before you make changes
  • Suggest the right reviewers based on code ownership
  • Navigate your codebase semantically

Instead of "I found 47 matches for Handler", you'll get "HandleRequest is called by 3 routes, changing it affects 12 files, risk score: 73."

Prerequisites

  • Node.js 18+
  • Claude Code installed (npm install -g @anthropic-ai/claude-code)
  • A codebase to index

Quick Setup (60 seconds)

Step 1: Install CKB

npm install -g @tastehub/ckb

Step 2: Initialize Your Project

cd /your/project
ckb init

This creates a .ckb/ directory and builds the initial index. First indexing takes 10-30 seconds for most projects.

Step 3: Connect to Claude Code

ckb setup

This automatically configures Claude Code's MCP settings. Done!

Manual Configuration

If you prefer manual setup or need custom options:

Find Your Claude Code Config

# macOS/Linux
~/.config/claude-code/config.json

# Or check where Claude Code stores config
claude-code --config-path

Add CKB as an MCP Server

Edit the config file:

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

Choose a Preset (Optional)

For most work, the default core preset (21 tools, ~2k tokens) is ideal:

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

Other presets:

  • review - Adds ownership and diff tools
  • refactor - Adds coupling and dead code analysis
  • federation - Adds cross-repo queries
  • full - All 90+ tools

Verify the Connection

Start Claude Code and test:

You: "What MCP tools do you have access to?"

Claude: "I have access to CKB's code intelligence tools including:
- searchSymbols - semantic code search
- getCallGraph - find callers and callees
- prepareChange - impact analysis
- explore - area exploration
- understand - symbol deep-dive
..."

Then try a real query:

You: "What calls the main function in this project?"

Claude: [uses getCallGraph]

"The main() function in cmd/server/main.go is the entry point.
It's not called by other code (it's the program entry point),
but it calls:
- config.Load() for configuration
- server.New() to create the HTTP server
- server.Run() to start listening"

Project-Specific Configuration

For project-specific settings, create .ckb/config.json:

{
  "mcp": {
    "defaultPreset": "review",
    "autoExpand": true
  },
  "index": {
    "exclude": ["vendor/**", "node_modules/**", "*.generated.go"],
    "languages": ["go", "typescript", "python"]
  }
}

Keeping the Index Fresh

CKB's index updates automatically in most cases. For large changes:

# Incremental update (fast)
ckb index

# Full rebuild (if needed)
ckb index --force

Automatic Indexing

Add to your git hooks for always-fresh indexes:

# .git/hooks/post-checkout
#!/bin/bash
ckb index --incremental --quiet

Or use CKB's built-in watcher:

ckb watch

This runs in the background and updates the index when files change.

Example Session

Here's what a CKB-powered Claude Code session looks like:

You: "I need to add rate limiting to the API handlers"

Claude: [uses explore to understand the API structure]

"I can see your API handlers are in internal/api/handlers/.
There are 12 handler functions, all following the same pattern
using the chi router.

Let me check where middleware is applied..."

[uses searchSymbols for middleware]

"Middleware is configured in internal/api/router.go.
You already have:
- LoggingMiddleware
- AuthMiddleware
- CORSMiddleware

I'd recommend adding RateLimitMiddleware in the same chain.
Should I show you the existing middleware pattern to follow?"

You: "Yes, and what would be affected if I add it?"

Claude: [uses prepareChange]

"Adding middleware at the router level affects all 12 handlers.

Impact:
- All API endpoints will be rate limited
- 34 integration tests hit these endpoints
- No external consumers (internal API)

Risk score: 28 (Low)
- Well-tested area
- Similar middleware exists as pattern
- Easy to rollback if needed"

Troubleshooting

"MCP server not found"

Check that CKB is installed globally:

which ckb
# Should output a path

# If not found, reinstall:
npm install -g @tastehub/ckb

"Index not found"

Run ckb init in your project directory:

cd /your/project
ckb init

"Stale results"

Rebuild the index:

ckb index --force

Claude Code doesn't see CKB tools

  1. Restart Claude Code after config changes
  2. Verify config JSON is valid: cat ~/.config/claude-code/config.json | jq .
  3. Check CKB is working: ckb status

Tips for Best Results

1. Be Specific

Instead of "find the user code", ask "what calls UserService.Create?"

2. Use Impact Analysis

Before making changes, ask "what's the impact of changing X?" CKB will tell you exactly what breaks.

3. Trust the Ownership Data

When CKB suggests reviewers, they're based on actual git history and expertise.

4. Expand When Needed

If you need additional tools mid-session, Claude can request them:

You: "I need to analyze coupling between these modules"

Claude: [calls expandToolset with "refactor" preset]

"I've expanded my toolset to include coupling analysis..."

What's Next

Links: