Installation

This guide covers everything you need to set up Kodebase and start using AI-assisted development workflows.

Recommended Setup

Kodebase is BYOM (Bring Your Own Model) - it works with any AI assistant that supports the Model Context Protocol (MCP). Here's what you need:

What You Need

1. Node.js 22+ - Required to run Kodebase
2. An AI-capable IDE - Where you'll interact with AI assistants
3. An LLM subscription - The AI that powers your assistant

Recommended Configuration

For the best experience, we recommend:

Component	Recommendation	Why
IDE	Cursor	Best MCP integration, AI-first design
LLM	Claude (via Cursor or Claude Code)	Best reasoning for planning and code
CLI	npx kodebase@latest	Always get the latest version

Alternative Setups

Kodebase works with any MCP-compatible setup:

• VSCode + Claude Code - Full MCP support via Claude Code CLI
• Cursor + Any LLM - Cursor supports multiple LLM providers
• Any MCP client - If it speaks MCP, Kodebase works

Install the Kodebase Package

Using npx (Recommended)

The easiest way to use Kodebase is via npx, which always runs the latest version:

npx kodebase@latest

Alpha Testers: We recommend always using npx kodebase@latest to stay current with the latest features and fixes. Kodebase will notify you when updates are available.

Global Installation

For frequent use, install globally:

npm install -g kodebase

Then run commands directly:

kodebase init
kodebase start A.1.1
kodebase submit

Local Installation

For project-specific installation:

npm install --save-dev kodebase

Then use via npm scripts or npx within the project.

CLI Commands Overview

Command	Description
kb init	Initialize Kodebase in your project
kb start <id>	Start work on an artifact (creates branch & PR)
kb submit	Submit current work for review
kb status	Show current work status

Run kb --help for the full command list.

MCP Integration

Kodebase connects to your AI assistant via the Model Context Protocol (MCP). This gives your AI access to Scout and Sherpa tools.

For Claude Code

Add Kodebase to your Claude Code MCP configuration:

Config file location:

• macOS: ~/.claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "kodebase": {
      "command": "npx",
      "args": ["kodebase@latest"],
      "env": {
        "KODEBASE_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

For Cursor

Add Kodebase to your Cursor MCP configuration:

Config file location:

• Project-level: .cursor/mcp.json (in your project root)
• Global: ~/.cursor/mcp.json

Add this configuration:

{
  "mcpServers": {
    "kodebase": {
      "command": "npx",
      "args": ["kodebase@latest"],
      "env": {
        "KODEBASE_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
KODEBASE_PROJECT_ROOT	Path to your project root	Current working directory

Set KODEBASE_PROJECT_ROOT when:

• Your AI assistant runs from a different directory
• You're working in a monorepo and need to specify a package
• The MCP server can't auto-detect your project root

Verify MCP Connection

After configuring, verify the MCP tools are available:

1. Restart your AI assistant (Claude Code or Cursor)
2. Ask your assistant: "What Kodebase tools do you have access to?"
3. Expected response: The assistant should list Scout and Sherpa tools

If tools aren't showing:

• Check the config file path is correct for your OS
• Ensure Node.js 22+ is installed
• Try running npx kodebase@latest manually to check for errors

VSCode Extension

The Kodebase VSCode extension provides a visual interface for managing your workflow.

Installation

Currently available as a pre-release .vsix file:

1. Download the latest .vsix from GitHub Releases
2. In VSCode: Extensions → ... menu → Install from VSIX...
3. Select the downloaded file

Extension Features

• Work Tracker Panel - See artifact status at a glance
• Status Bar - Current working artifact always visible
• Quick Actions - Start issues, view context, submit work

Using the Extension

1. Open a project with .kodebase/ initialized
2. The Kodebase panel appears in the sidebar
3. View ready, in-progress, and blocked artifacts
4. Click artifacts to see details or start work

Next Steps

• Quickstart Guide - Create your first Kodebase workflow
• Core Concepts - Understand artifacts and lifecycle
• The Workflow - Learn Scout and Sherpa workflows

Get Help

• Discord: discord.gg/dSWFC5Da - Chat with the community
• GitHub Issues: github.com/kodebaseai/kodebase/issues - Report bugs