Skip to content

CKB Quick Start Guide

Get CKB running in under a minute with npm, or build from source if you prefer.

The easiest way to install CKB. Works on macOS, Linux, and Windows.

Prerequisites

Install & Setup

# Install globally
npm install -g @tastehub/ckb

# Or run directly without installing
npx @tastehub/ckb --help

Set Up Your Project

cd /path/to/your/project

# Initialize CKB
ckb init   # or: npx @tastehub/ckb init

# Generate code index (auto-detects language)
ckb index  # or: npx @tastehub/ckb index

# Verify it works
ckb status

Connect to Claude Code

# Auto-configure (creates .mcp.json)
ckb setup

# Or for global config (all projects)
ckb setup --global

That's it! Claude Code now has access to CKB's code intelligence tools.

Alternative: Build from Source

If you prefer to build from source or need to modify CKB.

macOS (Build from Source)

Step 1: Install Go (if not already installed)

Open Terminal and run:

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Go
brew install go

Step 2: Download and Build CKB

# Clone the repository
git clone https://github.com/SimplyLiz/CodeMCP.git
cd CodeMCP

# Build CKB
go build -o ckb ./cmd/ckb

# Make it available everywhere (optional)
sudo cp ckb /usr/local/bin/

Step 3: Set Up Your Project

Navigate to your code project and run:

cd /path/to/your/project

# Initialize CKB
ckb init

Step 4: Generate Code Index (for Go projects)

# Install the Go indexer
go install github.com/sourcegraph/scip-go/cmd/scip-go@latest

# Generate the index
~/go/bin/scip-go --repository-root=.

Step 5: Verify It Works

ckb status

You should see output showing your backends and symbol count.

Linux (Build from Source)

Step 1: Install Go (if not already installed)

Open Terminal and run:

# Update package list
sudo apt update

# Install Go
sudo apt install -y golang-go

# Or install latest Go manually:
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc
source ~/.bashrc

Step 2: Install Git (if not already installed)

sudo apt install -y git

Step 3: Download and Build CKB

# Clone the repository
git clone https://github.com/SimplyLiz/CodeMCP.git
cd CodeMCP

# Build CKB
go build -o ckb ./cmd/ckb

# Make it available everywhere (optional)
sudo cp ckb /usr/local/bin/

Step 4: Set Up Your Project

Navigate to your code project and run:

cd /path/to/your/project

# Initialize CKB
ckb init

Step 5: Generate Code Index (for Go projects)

# Install the Go indexer
go install github.com/sourcegraph/scip-go/cmd/scip-go@latest

# Generate the index
~/go/bin/scip-go --repository-root=.

Step 6: Verify It Works

ckb status

Windows (Build from Source)

Step 1: Install Go

  1. Download Go from: https://go.dev/dl/
  2. Run the installer (e.g., go1.21.5.windows-amd64.msi)
  3. Click "Next" through the installer
  4. Restart your terminal/PowerShell after installation

Step 2: Install Git

  1. Download Git from: https://git-scm.com/download/win
  2. Run the installer
  3. Use default options (click "Next" through everything)
  4. Restart your terminal/PowerShell after installation

Step 3: Download and Build CKB

Open PowerShell and run:

# Clone the repository
git clone https://github.com/SimplyLiz/CodeMCP.git
cd CodeMCP

# Build CKB
go build -o ckb.exe ./cmd/ckb

Step 4: Add CKB to Your PATH (optional)

# Create a bin folder in your home directory
mkdir $HOME\bin -Force

# Copy CKB there
cp ckb.exe $HOME\bin\

# Add to PATH (run this once)
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$HOME\bin", "User")

Restart PowerShell for the PATH change to take effect.

Step 5: Set Up Your Project

Navigate to your code project and run:

cd C:\path\to\your\project

# Initialize CKB
ckb init

Step 6: Generate Code Index (for Go projects)

# Install the Go indexer
go install github.com/sourcegraph/scip-go/cmd/scip-go@latest

# Generate the index
& "$HOME\go\bin\scip-go.exe" --repository-root=.

Step 7: Verify It Works

ckb status

Common Commands

Once set up, here are the essential commands:

ckb search MyFunction    # Find symbols by name
ckb refs MyFunction      # Find where a symbol is used
ckb status               # Check system status
ckb arch                 # Get architecture overview
ckb doctor               # Run diagnostics

See the User Guide for the full command reference including ownership, decisions, federation, and 40+ other commands.

MCP Integration

CKB integrates with AI coding tools via MCP (Model Context Protocol). This section covers Claude Code; see MCP Integration for Cursor, Windsurf, VS Code, and others.

Easiest: Use the Setup Command

# If you installed via npm:
ckb setup              # project-level config
ckb setup --global     # user-level config for all projects

# Or with npx:
npx @tastehub/ckb setup

This automatically creates the correct configuration.

Manual Configuration

If you prefer manual setup, add to .mcp.json in your project:

Using npm/npx (recommended):

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

With a specific preset (v7.4):

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

Available presets: core (default, 14 tools), review, refactor, docs, ops, federation, full (76 tools). See Presets for details.

Using local binary (build from source):

{
  "mcpServers": {
    "ckb": {
      "command": "/path/to/ckb",
      "args": ["mcp"]
    }
  }
}

How It Works

You don't need to run ckb mcp manually. Claude Code automatically spawns the MCP server as a subprocess based on your configuration. The server auto-detects your repository from the project directory.

Restart Your AI Tool

Close and reopen Claude Code (or your AI tool). CKB tools will now be available.

For other tools, use ckb setup --tool=<name> where name is cursor, windsurf, vscode, opencode, or claude-desktop.

Starting the HTTP API (Optional)

If you want to access CKB via HTTP:

# Start the server
ckb serve --port 8080

# In another terminal, test it:
curl http://localhost:8080/health

Troubleshooting

"command not found: ckb"

If installed via npm:

  • Try: npx @tastehub/ckb status
  • Or reinstall: npm install -g @tastehub/ckb

If built from source:

  • Use the full path: /path/to/ckb status
  • Or add it to your PATH (see build instructions above)

"no SCIP index found"

CKB works without a SCIP index (fast mode), but for standard analysis with precise references:

# Easiest: let CKB auto-detect and run the indexer
ckb index

# Or manually for Go projects:
go install github.com/sourcegraph/scip-go/cmd/scip-go@latest
~/go/bin/scip-go --repository-root=.

"permission denied"

On macOS/Linux, you may need to make CKB executable:

chmod +x ckb

Go not found after installation

Restart your terminal, or run:

# macOS/Linux
source ~/.bashrc  # or ~/.zshrc

# Windows: Close and reopen PowerShell

Getting Help

# See all commands
ckb --help

# Get help for a specific command
ckb search --help

Next Steps