Skip to content

Quick Start

Jump to bottom
Lisa edited this page Dec 19, 2025 · 16 revisions

CKB Quick Start Guide

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

Recommended: npm Install (All Platforms)

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

Using CKB

Once set up, here are the most common commands:

Search for Code

# Find a function or type by name
ckb search MyFunction

# Find with more results
ckb search MyFunction --limit 20

Find References

# Find where a symbol is used
ckb refs MyFunction

Check System Status

# See what backends are available
ckb status

Get Architecture Overview

# See high-level code structure
ckb arch

Run Diagnostics

# Check for issues
ckb doctor

Query Code Ownership

# See who owns a file
ckb ownership internal/api/handler.go

# See who owns a module
ckb ownership --module internal/api

Work with Architectural Decisions

# List all decisions
ckb decisions

# Search decisions
ckb decisions --search "caching"

Refresh Architectural Data

# Refresh ownership, hotspots, and module info
ckb refresh

# Refresh only ownership data
ckb refresh --scope ownership

Using with Claude Code

CKB integrates directly with Claude Code via MCP (Model Context Protocol).

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"]
    }
  }
}

Using local binary (build from source):

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

Restart Claude Code

Close and reopen Claude Code. CKB tools will now be available.

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 (basic mode), but for enhanced analysis:

# 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

Clone this wiki locally