You've heard about CKB and want to try it. This tutorial walks you through your first session, step by step. In 10 minutes, you'll have semantic code intelligence working with your AI assistant.

What We'll Do

Install CKB
Index a project
Connect to an AI assistant
Ask some real questions
See the difference from regular grep

Let's go.

Step 1: Install CKB

Open your terminal and run:

npm install -g @tastehub/ckb

Verify it worked:

ckb --version

You should see a version number like 8.1.0.

Don't have npm? Install Node.js from nodejs.org first.

Step 2: Choose a Project

Pick a codebase you're familiar with. It can be:

Your own project
An open-source project you've cloned
Any codebase with at least a few files

For this tutorial, let's use a real project. If you don't have one handy:

# Clone a sample project
git clone https://github.com/gorilla/mux.git
cd mux

Step 3: Initialize CKB

In your project directory:

ckb init

You'll see output like:

Scanning project...
Found 45 source files
Indexing symbols...
Created index with 234 symbols

CKB initialized successfully!
Run 'ckb setup' to configure your AI assistant.

This creates a .ckb/ directory with the semantic index.

Step 4: Connect to Your AI Assistant

Run the setup command:

ckb setup

CKB will detect your installed AI tools and configure them. You'll see something like:

Detected: Claude Code
Configuring MCP server...
Done! Restart Claude Code to use CKB.

Manual setup? If auto-detection doesn't work, see our guides for:

Step 5: Your First Query

Open your AI assistant and try this:

What are the main entry points in this codebase?

The AI will use CKB to find real entry points—not just grep for "main":

AI: This codebase has the following entry points:

1. mux.NewRouter() - Creates a new router instance
   Used to initialize the HTTP routing

2. Router.HandleFunc() - Registers route handlers
   Primary way to define endpoints

3. Router.ServeHTTP() - HTTP handler implementation
   Entry point for incoming requests

The typical usage pattern:
r := mux.NewRouter()
r.HandleFunc("/users", usersHandler)
http.ListenAndServe(":8080", r)

Notice: The AI didn't just find the word "main". It understood the code structure and found the meaningful entry points.

Step 6: Try Semantic Queries

Now let's see what CKB can really do. Try these:

Find Callers

What calls the Match function?

The AI finds actual call sites, not just text matches:

AI: Match() in mux.go is called by:
- Route.Match() at route.go:45 - checks if route matches request
- Router.Match() at mux.go:123 - finds matching route for request
- matchInArray() at regexp.go:67 - helper for path matching

Impact Analysis

What would break if I changed the Route struct?

AI: Changing the Route struct would affect:

Direct dependents (14 functions):
- Route.Match, Route.URL, Route.GetName...
- Router.NewRoute, Router.Handle...

Tests (8 files):
- route_test.go, mux_test.go, bench_test.go...

Risk assessment: High
- Core data structure
- Public API (exported type)
- Extensive test coverage helps

Recommendation: Add new fields rather than modifying existing ones
for backwards compatibility.

Architecture Overview

Give me an overview of this codebase's architecture

AI: Architecture overview:

Core Components:
├── Router (mux.go) - Main routing engine
├── Route (route.go) - Individual route definitions
├── RouteMatch (mux.go) - Match result container
└── regexp.go - Path pattern matching

Key Patterns:
- Builder pattern: Router().Methods().Path().Handler()
- Interface-based: http.Handler compatibility
- Middleware support via Use()

File responsibilities:
- mux.go (280 lines) - Router implementation
- route.go (380 lines) - Route configuration
- regexp.go (180 lines) - Pattern compilation
- middleware.go (45 lines) - Middleware chain

Step 7: Compare to Grep

Let's see the difference. Try asking without CKB intelligence:

Traditional grep

grep -r "Match" *.go

Output: 47 matches including comments, strings, variable names, type names, function definitions, and actual calls—all mixed together.

CKB semantic search

What functions have "Match" in their name?

AI: Functions with "Match" in their name:
- Route.Match() - checks if route matches request
- Router.Match() - finds matching route
- matchInArray() - helper function (internal)
- RouteMatch struct - match result container

These are distinct from the string "Match" appearing in:
- Comments (23 occurrences)
- Variable names (5 occurrences)
- Test assertions (12 occurrences)

The difference: CKB understands what's a function definition vs. a comment vs. a string literal.

Step 8: Explore More

Here are more queries to try:

Code Ownership

Who should I ask about the middleware code?

Dead Code

Are there any unused functions in this project?

Test Coverage

What tests cover the Route.Match function?

Complexity

What's the most complex function in this codebase?

What Just Happened

Behind the scenes, CKB:

Parsed your code - Built an abstract syntax tree for each file
Resolved references - Figured out what symbols refer to
Built a call graph - Mapped what calls what
Analyzed git history - Determined ownership and change patterns
Created an index - Made it all queryable in milliseconds

Your AI assistant then queried this index instead of grep-ing through text.

Keeping the Index Fresh

As you work, the index needs updates. Options:

Manual update

ckb index

Automatic watching

ckb watch  # Runs in background, updates on file changes

Git hook

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

Next Steps

You've completed your first CKB session. Here's where to go next:

Prompt Cookbook - Ready-to-use prompts for common tasks
Compound Operations - Efficient multi-step queries
CI Integration - Automate analysis in your pipeline

Quick Reference

ckb init                  # Initialize project
ckb setup                 # Configure AI assistant
ckb index                 # Update index
ckb index --force         # Full rebuild
ckb watch                 # Auto-update on changes
ckb status                # Check index health

Get Help

Documentation: codeknowledge.dev/docs
GitHub Issues: SimplyLiz/CodeMCP
Feature Requests: Open an issue with "feature:" prefix

Welcome to semantic code intelligence. Your AI assistant just got a lot smarter.

Links: