K0ntext

Universal AI context engineering for Claude, GitHub Copilot, Cline, Cursor, Windsurf, Aider, Continue, Antigravity, and Gemini with OpenRouter-powered intelligent analysis.

[](https://www.npmjs.com/package/k0ntext) [](https://www.npmjs.com/package/k0ntext) [](https://opensource.org/licenses/MIT) [](https://github.com/SireJeff/k0ntext/actions) [](https://nodejs.org) [](https://modelcontextprotocol.io)

---

Table of Contents

• [Quick Start](#quick-start)
• [Zero-to-Hero Workflow](#zero-to-hero-workflow)
• [Windows Support](#windows-support)
• [Features Overview](#features-overview)
• [Releases](#releases)
• [Complete CLI Reference](#complete-cli-reference)
• [MCP Server Usage](#mcp-server-usage)
• [Supported AI Tools](#supported-ai-tools)
• [Configuration](#configuration)
• [Architecture](#architecture)
• [Development](#development)
• [Documentation](#documentation)
• [Community](#community)

---

Quick Start

# Install globally
npm install -g k0ntext

# Initialize your project with intelligent analysis
k0ntext init

# Generate context files for all AI tools
k0ntext generate

# Start the MCP server for AI tools
k0ntext mcp

---

Zero-to-Hero Workflow

New Project Setup

# 1. Initialize with intelligent analysis
k0ntext init --intelligent

# 2. Index your codebase
k0ntext index

# 3. Generate context files
k0ntext generate

# 4. Start MCP server (auto-configured)
k0ntext mcp

Existing Project Setup

# 1. Check existing context
k0ntext stats

# 2. Index codebase if needed
k0ntext index --docs --code

# 3. Generate missing tool configs
k0ntext generate --force

# 4. Validate everything
k0ntext validate --strict

---

Windows Support

K0ntext uses native SQLite extensions for high-performance vector search.

For Windows Users:

• Recommended: Use Node.js LTS (v18, v20, v22) with pre-built binaries
• Instant install: These versions install without extra tools
• Non-LTS versions (v23/v24): May require Visual Studio Build Tools to compile the database driver

---

🚀 Features Overview

Interactive REPL Shell

• Auto-start: Running k0ntext with no arguments launches the interactive shell
• Session persistence: Command history and statistics saved across sessions
• Built-in commands: help, stats, index, search, config, drift, init, update, exit
• Orange gradient theme with Unicode/ASCII fallback and terminal capability detection
• Update checker with automatic version notifications on startup

Enhanced TUI Panels

• Advanced Search Panel -- Filtered, sortable search with --type, --sort, --limit flags and content previews
• Configuration UI -- Interactive editor with 4 categories (Project, AI Tools, Features, Display)
• Indexing Progress -- Real-time multi-stage progress visualization with ora spinner
• Drift Detection -- Three-axis analysis (file dates, structure, git diff) with severity-coded reporting

Intelligent Analysis

• OpenRouter-powered codebase analysis with embeddings
• Tech stack detection and documentation
• Workflow discovery and categorization
• Automatic context generation
• Centralized model configuration -- single source of truth for all AI operations

Semantic Search

• Vector database (sqlite-vec) for intelligent code retrieval
• Hybrid search (text + semantic)
• Content type filtering (workflow, agent, command, code, doc, etc.)
• Real-time indexing with watch mode

Cross-Tool Sync

• 9 AI Tools Supported: Claude, Copilot, Cline, Antigravity, Windsurf, Aider, Continue, Cursor, Gemini
• Automatic synchronization between tool configurations
• Change detection with SHA256 hashing
• Sync status monitoring
• Intelligent cross-sync -- AI-powered propagation of changes across tools

Git Hooks Automation

• Pre-commit workflow -- Automatic context maintenance
• Drift detection on every commit
• Automatic cross-sync when drift detected
• Updated context files auto-added to commits

Drift Detection

• AI-powered semantic analysis -- Detect when documentation diverges from code
• Replaces hash-based checks with intelligent understanding
• Severity-based reporting (high/medium/low)
• Automatic fix suggestions

Fact-Checking

• Validate documentation accuracy against codebase
• Identify outdated APIs, wrong file paths, missing dependencies
• Confidence scoring for each claim

Map-Based Context

• Concise, structured context files
• Reduce hallucination through precise references
• Alternative to verbose documentation format

Version Detection

• Automatic version checking -- Detects outdated context files
• Semantic version parsing -- Supports 5 version marker formats
• Update type indicators -- Major/minor/patch with emoji
• Database tracking -- Stores version history and check timestamps

User Modification Handling

• SHA-256 hash detection -- Detects when users edit generated files
• Automatic backup creation -- Creates backups before overwriting modified files
• Dual backup strategy -- File-copy with git-stash fallback
• Interactive prompts -- Asks user before overwriting custom changes

Template Engine

• Handlebars integration -- Rich template-based content generation
• 15 custom helpers -- join, first, truncate, slugify, formatDate, eq, ne, and, or, defaults, json, keys, values, length
• Rich project data -- Generated files include actual project metadata

Template Sync System

• Automatic .claude/ sync -- Syncs commands/, agents/, schemas/, standards/, tools/, automation/ from package
• Hash-based change detection -- SHA-256 for consistency with DatabaseClient
• File state classification -- identical, safe-update, conflict, new, deleted, user-only
• Interactive conflict resolution -- Show diff, keep-local, overwrite, or skip options
• Backup before overwrite -- Automatic backups to .k0ntext/backups/

Database Snapshots

• Create/restore/diff snapshots -- Full database save/restore with gzip compression
• Snapshot comparison -- Diff two snapshots to see what changed
• Persistent todo lists -- Survive context compactions via markdown files

MCP Server

• Auto-Configuration -- MCP server automatically configured in .claude/settings.json on init
• 10 Tools: searchcontext, getitem, addknowledge, analyze, gettoolconfigs, querygraph, get_stats
• 6 Prompts: context-engineer, core-architect, api-developer, database-ops, integration-hub, deployment-ops
• Real-time context access for AI assistants
• Knowledge graph traversal

Complete CLI

• init -- Initialize with intelligent analysis (auto-configures MCP)
• generate -- Generate context files for all tools
• mcp -- Start MCP server
• sync -- Sync across AI tools
• cleanup -- Clean up conflicting tool folders
• validate -- Validate context files
• export -- Export database
• import -- Import from exports
• performance -- Show performance metrics
• watch -- Auto-index file changes
• index -- Index codebase
• search -- Search indexed content
• stats -- View database statistics
• check -- Check if context files are outdated
• restore -- Restore AI tool config files from backups
• sync-templates -- Sync .claude/ templates from package
• template-status -- Show template sync status
• drift-detect -- AI-powered documentation drift detection
• cross-sync -- Intelligent sync across all AI tools
• hooks -- Git hooks management (install/uninstall/status)
• fact-check -- Validate documentation accuracy
• generate --map -- Generate concise map-based context files
• snapshot -- Create/restore/list/diff/delete database snapshots
• migrate -- Manage database migrations
• shell -- Launch interactive REPL shell

Smart Agents

• CleanupAgent -- Remove conflicting AI tool folders (.cursor, .windsurf, .cline, etc.)
• PerformanceMonitorAgent -- Track database performance and suggest optimizations
• DriftAgent -- AI-powered documentation drift detection
• FactCheckAgent -- Validate documentation accuracy against codebase

SQLite Storage

• Persistent database with SHA256 change detection
• Embeddings support for semantic search
• Knowledge graph relationships
• Automatic schema migrations

---

📦 Releases

[v3.8.0 Release](#release-v380) - 2026-02-11

📦 New Features

• Database Snapshots -- Create, restore, diff, and delete database snapshots with gzip compression
• Persistent Todo Lists -- TodoListManager service with markdown files that survive context compactions
• AI-Powered Cleanup -- CleanupAgent with OpenRouter-powered analysis for intelligent folder cleanup
• Timestamp Tracking -- TimestampTracker service for precise file synchronization tracking
• Database Schema v1.6.0 -- New tables for todo sessions, tasks, file timestamps, and generated files

🐛 Bug Fixes

• Fixed type guard errors in TimestampTracker and TodoListManager services
• Fixed import paths for SnapshotManager types in CLI commands
• Added missing description property to SnapshotListEntry interface
• Fixed snapshot command type annotations for map callbacks

See [CHANGELOG.md](CHANGELOG.md) for full release history.

[v3.8.1 Release](#release-v381) - 2026-02-12

📚 Documentation Updates

• Created comprehensive packages.md documenting all included components
• Declared MIT License explicitly in package.json
• Added project banner image to README header

---

⚙️ Complete CLI Reference

Core Commands

k0ntext init [project-name]

Initialize AI context for a project with intelligent analysis.

# Initialize current directory
k0ntext init

# Initialize specific project
k0ntext init my-project

# Skip intelligent analysis (faster)
k0ntext init --no-intelligent

Options:

• --no-intelligent -- Skip OpenRouter-powered analysis
• --no-version-check -- Skip version checking for outdated context files
• --no-template-sync -- Skip template synchronization
• -v, --verbose -- Show detailed output

k0ntext generate

Generate context files for all AI tools.

# Generate for all tools
k0ntext generate

# Generate for specific tools
k0ntext generate -ai claude,copilot,cursor

# Force regenerate all files
k0ntext generate --force

# Verbose output
k0ntext generate -v

Options:

• -ai, --ai -- Specific tools (comma-separated)
• --force -- Force regenerate all files
• --map -- Use concise map-based format
• -v, --verbose -- Show detailed output

k0ntext mcp

Start the Model Context Protocol server.

# Start with default database
k0ntext mcp

# Specify database path
k0ntext mcp --db .my-context.db

Options:

• --db -- Database file path

k0ntext sync

Synchronize context across AI tools.

# Sync all tools
k0ntext sync

# Check sync status only
k0ntext sync --check

# Sync from specific tool
k0ntext sync --from claude

# Sync to specific tool
k0ntext sync --to copilot

# Force sync
k0ntext sync --force

Options:

• --check -- Only check synchronization status
• --from -- Sync from specific tool
• --to -- Sync to specific tool
• --force -- Force sync even if up-to-date

k0ntext cleanup

Clean up context folders from other AI tools.

# Dry run to see what would be removed
k0ntext cleanup --dry-run

# Keep specific folders
k0ntext cleanup --keep .github,.vscode

# Verbose output
k0ntext cleanup -v

Options:

• --dry-run -- Show what would be removed
• --keep -- Folders to keep (comma-separated)
• --ai -- Use AI to intelligently analyze which folders can be safely removed
• -v, --verbose -- Show detailed output

k0ntext validate

Validate context files and AI tool configurations.

# Basic validation
k0ntext validate

# Auto-fix errors
k0ntext validate --fix

# Treat warnings as errors
k0ntext validate --strict

Options:

• --fix -- Automatically fix validation errors
• --strict -- Treat warnings as errors

k0ntext export

Export context database to file.

# Export as JSON
k0ntext export context.json

# Export as markdown
k0ntext export docs.md --format markdown

# Export specific type
k0ntext export workflows.json --type workflow

Options:

• --format -- Export format (json, markdown)
• --type -- Filter by context type

k0ntext import

Import context data from exported files.

# Import JSON export
k0ntext import context.json

# Import and merge with existing data
k0ntext import context.json --merge

Options:

• --format -- Import format (json, markdown)
• --merge -- Merge with existing data (default: replace)

k0ntext performance

Show performance metrics and optimization suggestions.

# Human-readable report
k0ntext performance

# JSON output
k0ntext performance --json

Options:

• --json -- Output as JSON

k0ntext watch

Watch for file changes and auto-update index.

# Start watching with 1s delay
k0ntext watch

# Custom debounce delay
k0ntext watch -d 2000

Options:

• -d, --delay -- Debounce delay in milliseconds

k0ntext index

Index codebase content into the database.

# Index everything
k0ntext index

# Index documentation only
k0ntext index --docs

# Index source code only
k0ntext index --code

# Index AI tool configs only
k0ntext index --tools

# Verbose output
k0ntext index -v

Options:

• --docs -- Index documentation files only
• --code -- Index source code only
• --tools -- Index AI tool configurations only
• --all -- Index everything (default)
• -v, --verbose -- Show detailed output

k0ntext search

Search across indexed content.

# Basic search
k0ntext search "authentication"

# Search specific type
k0ntext search "user login" -t workflow

# Text-only search
k0ntext search "API endpoint" -m text

# Semantic search (requires OPENROUTER_API_KEY)
k0ntext search "data persistence" -m semantic

# Limit results
k0ntext search "database" -l 5

Options:

• -t, --type -- Filter by type
• -l, --limit -- Maximum results (default: 10)
• -m, --mode -- Search mode: text, semantic, hybrid

k0ntext stats

Show database and indexing statistics.

# View all statistics
k0ntext stats

Context Management Commands

k0ntext check

Check if context files are outdated.

# Check all context files
k0ntext check

# Check with detailed output
k0ntext check -v

# Prompt to update outdated files
k0ntext check --update

# Force update without prompts
k0ntext check --update --force

Options:

• --update -- Prompt to update outdated files
• --force -- Update without prompting
• -v, --verbose -- Show detailed output

k0ntext restore

Restore AI tool config files from backups.

# List available backups
k0ntext restore --list

# Interactive restore mode
k0ntext restore

# Restore from specific backup
k0ntext restore --backup "AI_CONTEXT.md.2026-02-09T14.30.45.123Z.bak"

# Restore for specific tool
k0ntext restore --tool claude --list

Options:

• --list -- List available backups
• --backup -- Restore from specific backup path
• --tool -- Filter by tool name
• --force -- Restore without confirmation

k0ntext sync-templates

Sync .claude/ templates from package templates/base/.

# Sync all templates
k0ntext sync-templates

# Dry run to see what would change
k0ntext sync-templates --dry-run

# Sync specific subdirectories
k0ntext sync-templates --subdirs commands,agents

# Force overwrite all conflicts
k0ntext sync-templates --force

Options:

• --dry-run -- Show changes without applying
• --force -- Auto-overwrite conflicts without prompting
• --subdirs -- Comma-separated subdirectories to sync
• -v, --verbose -- Show detailed output including diffs
• `--no-archiv

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SireJeff
• Source: SireJeff/k0ntext
• License: MIT

Install and usage instructions live in the source repository linked above.