Windsurf is Codeium's AI-native code editor. It's built for AI-assisted development from the ground up. Adding CKB gives Windsurf's AI semantic understanding of your code—it knows what calls what, not just where text appears.

This guide walks through the complete setup.

What You'll Get

After connecting CKB, Windsurf's AI can:

Find all callers of any function (semantic, not text search)
Show you what breaks before you change code
Identify code owners and suggest reviewers
Navigate complex codebases intelligently

Before CKB: "I found 23 files containing 'UserService'"

After CKB: "UserService is used by 8 controllers. Changing it affects 34 files. Risk: Medium. Owners: @alice, @bob."

Prerequisites

Windsurf installed (download here)
Node.js 18 or higher
A codebase to work with

Setup Steps

Step 1: Install CKB

Open a terminal and run:

npm install -g @tastehub/ckb

Verify the installation:

ckb --version

Step 2: Initialize Your Project

Navigate to your project and create the CKB index:

cd /path/to/your/project
ckb init

This scans your codebase and builds a semantic index. First run takes 10-30 seconds for most projects.

Step 3: Configure Windsurf

Windsurf stores MCP configuration at:

# macOS
~/.codeium/windsurf/mcp_config.json

# Windows
%APPDATA%\Codeium\Windsurf\mcp_config.json

# Linux
~/.config/codeium/windsurf/mcp_config.json

Create or edit this file:

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

Step 4: Restart Windsurf

Close and reopen Windsurf for the configuration to take effect.

Step 5: Verify Connection

In Windsurf's AI chat, ask:

What MCP tools do you have access to?

You should see CKB tools listed, including searchSymbols, getCallGraph, prepareChange, etc.

Quick Test

Try a real query to confirm everything works:

You: "What are the main entry points in this codebase?"

Windsurf AI: [uses CKB's listEntrypoints and explore tools]

"This project has 3 main entry points:
1. cmd/server/main.go - HTTP server startup
2. cmd/worker/main.go - Background job processor
3. cmd/cli/main.go - Command-line interface

The server is the primary entry point, handling API routes
defined in internal/api/router.go."

Choosing a Preset

CKB offers different tool presets to optimize for your workflow:

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

Preset	Tools	Best For
`core`	21	General development (recommended)
`review`	27	Code review workflows
`refactor`	33	Large refactoring projects
`full`	92	Access to everything

Start with core—it covers most needs with minimal overhead.

Windsurf-Specific Features

Cascade Integration

Windsurf's Cascade feature (multi-step AI workflows) works great with CKB:

You: "Refactor the payment module to use the new API"

Cascade:
1. [CKB: explore payment module]
2. [CKB: prepareChange to assess impact]
3. [Identifies files to modify]
4. [Makes changes with full context]
5. [CKB: verify no broken references]

The AI uses CKB at each step for informed decisions.

Inline Editing with Context

When using Windsurf's inline edit (Cmd+I):

You: [select a function]
"This function is complex. CKB says it has 15 callers.
Simplify it without breaking any of them."

The AI considers the full dependency graph.

Chat-Based Exploration

Windsurf's AI chat is perfect for codebase exploration:

You: "I'm new to this project. Give me an overview."

AI: [uses CKB's explore and getArchitecture]

"This is a Go microservice with 3 main packages:

internal/api/ - HTTP handlers (12 endpoints)
internal/service/ - Business logic (8 services)
internal/repo/ - Database access (5 repositories)

Key patterns:
- Dependency injection via constructors
- Repository pattern for data access
- Middleware chain for auth/logging

Hot spots (frequently changed):
- internal/api/checkout.go (high churn)
- internal/service/payment.go (complex)"

Common Workflows

Understanding New Code

You: "Explain how authentication works in this codebase"

AI: [uses getCallGraph and traceUsage]

"Authentication flow:
1. Request hits AuthMiddleware
2. JWT extracted from Authorization header
3. TokenService.Validate() checks signature
4. User loaded from UserRepository
5. Context enriched with user data
6. Handler receives authenticated request

Entry: /api/login → AuthController.Login()
Protected routes: All /api/* except /api/health"

Before Making Changes

You: "I want to rename GetUser to FetchUser. What's affected?"

AI: [uses prepareChange with rename]

"Renaming GetUser → FetchUser:

Files to update: 14
- Direct callers: 8 functions
- Test files: 4
- Mocks: 2

No external API impact (internal function).
Risk score: 28 (Low)

Want me to perform the rename?"

Finding Code Owners

You: "Who should review changes to the billing module?"

AI: [uses getReviewers]

"Billing module reviewers:

1. @sarah - 62% ownership, active maintainer
2. @mike - 28% ownership, original author
3. @lisa - Reviewed 5 recent billing PRs

Recommend: @sarah as primary reviewer"

Troubleshooting

"MCP tools not showing"

Check the config file path is correct for your OS
Verify JSON syntax is valid
Restart Windsurf completely (not just reload)
Check CKB is installed: which ckb or where ckb

"Index not found" errors

Run ckb init in your project directory:

cd /your/project
ckb init

Slow responses

Use --preset=core for smaller tool overhead
Check index size: ckb status
Exclude large generated files in .ckb/config.json

Outdated results

Rebuild the index:

ckb index --force

Or set up automatic indexing:

ckb watch  # Runs in background, updates on file changes

Tips for Best Results

Be specific - "What calls UserService.Create?" beats "find user code"
Use impact analysis - Before changes, ask "what's the impact of changing X?"
Trust ownership data - CKB's reviewer suggestions are based on actual git history
Let AI expand tools - If you need more capabilities, the AI can request them mid-session

Next Steps

Try the Prompt Cookbook for ready-to-use prompts
Learn about Compound Operations
Explore All Features

Links: