Universal AI context engineering for Claude, GitHub Copilot, Cline, Cursor, Windsurf, Aider, Continue, Antigravity, and Gemini with OpenRouter-powered intelligent analysis.
- Quick Start
- Zero-to-Hero Workflow
- Windows Support
- Features Overview
- Releases
- Complete CLI Reference
- MCP Server Usage
- Supported AI Tools
- Configuration
- Architecture
- Development
- Documentation
- Community
# 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 mcpNew 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 mcpExisting 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 --strictK0ntext 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
- Auto-start: Running
k0ntextwith 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
- Advanced Search Panel -- Filtered, sortable search with
--type,--sort,--limitflags 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
- 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
- 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
- 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
- Pre-commit workflow -- Automatic context maintenance
- Drift detection on every commit
- Automatic cross-sync when drift detected
- Updated context files auto-added to commits
- 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
- Validate documentation accuracy against codebase
- Identify outdated APIs, wrong file paths, missing dependencies
- Confidence scoring for each claim
- Concise, structured context files
- Reduce hallucination through precise references
- Alternative to verbose documentation format
- 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
- 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
- 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
- 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/
- 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
- Auto-Configuration -- MCP server automatically configured in
.claude/settings.jsonon init - 10 Tools: search_context, get_item, add_knowledge, analyze, get_tool_configs, query_graph, 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
init-- Initialize with intelligent analysis (auto-configures MCP)generate-- Generate context files for all toolsmcp-- Start MCP serversync-- Sync across AI toolscleanup-- Clean up conflicting tool foldersvalidate-- Validate context filesexport-- Export databaseimport-- Import from exportsperformance-- Show performance metricswatch-- Auto-index file changesindex-- Index codebasesearch-- Search indexed contentstats-- View database statisticscheck-- Check if context files are outdatedrestore-- Restore AI tool config files from backupssync-templates-- Sync.claude/templates from packagetemplate-status-- Show template sync statusdrift-detect-- AI-powered documentation drift detectioncross-sync-- Intelligent sync across all AI toolshooks-- Git hooks management (install/uninstall/status)fact-check-- Validate documentation accuracygenerate --map-- Generate concise map-based context filessnapshot-- Create/restore/list/diff/delete database snapshotsmigrate-- Manage database migrationsshell-- Launch interactive REPL shell
- 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
- Persistent database with SHA256 change detection
- Embeddings support for semantic search
- Knowledge graph relationships
- Automatic schema migrations
π¦ Releases
v3.8.0 Release - 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
TimestampTrackerandTodoListManagerservices - Fixed import paths for
SnapshotManagertypes in CLI commands - Added missing
descriptionproperty toSnapshotListEntryinterface - Fixed snapshot command type annotations for map callbacks
See CHANGELOG.md for full release history.
v3.8.1 Release - 2026-02-12
π Documentation Updates
- Created comprehensive
packages.mddocumenting all included components - Declared
MIT Licenseexplicitly in package.json - Added project banner image to README header
βοΈ Complete CLI Reference
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-intelligentOptions:
--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
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 -vOptions:
-ai, --ai <tools>-- Specific tools (comma-separated)--force-- Force regenerate all files--map-- Use concise map-based format-v, --verbose-- Show detailed output
Start the Model Context Protocol server.
# Start with default database
k0ntext mcp
# Specify database path
k0ntext mcp --db .my-context.dbOptions:
--db <path>-- Database file path
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 --forceOptions:
--check-- Only check synchronization status--from <tool>-- Sync from specific tool--to <tool>-- Sync to specific tool--force-- Force sync even if up-to-date
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 -vOptions:
--dry-run-- Show what would be removed--keep <folders>-- Folders to keep (comma-separated)--ai-- Use AI to intelligently analyze which folders can be safely removed-v, --verbose-- Show detailed output
Validate context files and AI tool configurations.
# Basic validation
k0ntext validate
# Auto-fix errors
k0ntext validate --fix
# Treat warnings as errors
k0ntext validate --strictOptions:
--fix-- Automatically fix validation errors--strict-- Treat warnings as errors
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 workflowOptions:
--format <format>-- Export format (json, markdown)--type <type>-- Filter by context type
Import context data from exported files.
# Import JSON export
k0ntext import context.json
# Import and merge with existing data
k0ntext import context.json --mergeOptions:
--format <format>-- Import format (json, markdown)--merge-- Merge with existing data (default: replace)
Show performance metrics and optimization suggestions.
# Human-readable report
k0ntext performance
# JSON output
k0ntext performance --jsonOptions:
--json-- Output as JSON
Watch for file changes and auto-update index.
# Start watching with 1s delay
k0ntext watch
# Custom debounce delay
k0ntext watch -d 2000Options:
-d, --delay <ms>-- Debounce delay in milliseconds
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 -vOptions:
--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
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 5Options:
-t, --type <type>-- Filter by type-l, --limit <n>-- Maximum results (default: 10)-m, --mode <mode>-- Search mode: text, semantic, hybrid
Show database and indexing statistics.
# View all statistics
k0ntext statsCheck 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 --forceOptions:
--update-- Prompt to update outdated files--force-- Update without prompting-v, --verbose-- Show detailed output
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 --listOptions:
--list-- List available backups--backup <path>-- Restore from specific backup path--tool <name>-- Filter by tool name--force-- Restore without confirmation
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 --forceOptions:
--dry-run-- Show changes without applying--force-- Auto-overwrite conflicts without prompting--subdirs <dirs>-- Comma-separated subdirectories to sync-v, --verbose-- Show detailed output including diffs--no-archive-- Skip archiving removed files
Show template sync status.
# Check sync status
k0ntext template-status
# Detailed status with file listings
k0ntext template-status --verboseManage database snapshots.
# Create a snapshot
k0ntext snapshot
# Restore from snapshot
k0ntext snapshot restore
# List all snapshots
k0ntext snapshots
# Diff two snapshots
k0ntext snap-diffAI-powered documentation drift detection using semantic analysis.
# Detect drift in all context files
k0ntext drift-detect
# Detect drift in specific paths
k0ntext drift-detect -p CLAUDE.md,.cursorrules
# Strict mode (fails on any drift)
k0ntext drift-detect --strictOptions:
--fix-- Automatically fix detected drift (experimental)--strict-- Fail on any drift detected-p, --paths <paths>-- Comma-separated paths to check--max-files <number>-- Maximum files to check (default: 50)-v, --verbose-- Show detailed output
Intelligently synchronize context across all AI tools after drift detection.
# Sync all affected files
k0ntext cross-sync
# Dry run to see what would be synced
k0ntext cross-sync --dry-run
# Sync to specific tools only
k0ntext cross-sync --to claude,cursorOptions:
--dry-run-- Show what would be synced without making changes--from <tool>-- Sync only from specific tool--to <tools>-- Sync only to specific tools (comma-separated)--affected <files>-- Comma-separated list of affected files-v, --verbose-- Show detailed sync output
Manage git hooks for automatic context synchronization.
# Install git hooks
k0ntext hooks install
# Uninstall git hooks
k0ntext hooks uninstall
# Check hooks status
k0ntext hooks statusSubcommands:
install-- Install pre-commit hook for automatic workflowuninstall-- Remove installed hooksstatus-- Show hook installation status
Validate documentation accuracy using AI analysis.
# Check all documentation files
k0ntext fact-check
# Check specific files
k0ntext fact-check CLAUDE.md .cursorrulesOptions:
--fix-- Automatically fix detected issues (experimental)-v, --verbose-- Show detailed output--min-confidence <number>-- Minimum confidence to report (0-1, default: 0.5)
When you install hooks with k0ntext hooks install, the pre-commit hook automatically:
- Autosync -- Sync context from source of truth
- Validate -- Check for context errors
- Drift Detect -- AI-powered drift detection
- Cross-Sync -- Update all AI tool contexts if drift found
- Auto-Add -- Include updated context files in commit
Skip hooks temporarily:
K0NTEXT_SKIP_HOOKS=1 git commit -m "message"
# or
git commit --no-verify -m "message"π MCP Server Usage
When you run k0ntext init, the MCP server is automatically configured in .claude/settings.json:
{
"mcpServers": {
"k0ntext": {
"command": "npx",
"args": ["k0ntext", "mcp"],
"env": {
"K0NTEXT_PROJECT_ROOT": "${projectFolder}"
}
}
}
}Manual setup is no longer required! The MCP server works immediately after initialization.
# Start MCP server (auto-configured)
k0ntext mcp- search_context -- Semantic search across all indexed content
- get_item -- Get a specific context item by ID or path
- add_knowledge -- Store new insights or facts
- analyze -- Run intelligent analysis on codebase
- get_tool_configs -- Get AI tool configurations
- query_graph -- Traverse knowledge graph
- get_stats -- Get database statistics
- context-engineer -- Initialize and configure AI context system
- core-architect -- Design system architecture
- api-developer -- Develop API endpoints
- database-ops -- Database operations
- integration-hub -- External integrations
- deployment-ops -- CI/CD and deployment
// Search for authentication workflows
const results = await search_context({
query: "user authentication flow",
type: "workflow",
limit: 5
});
// Get a specific item
const item = await get_item({
id: "workflow:user-auth"
});
// Add new knowledge
await add_knowledge({
name: "API Rate Limiting",
content: "Our API uses token bucket algorithm with 1000 req/min",
relatedTo: ["api:main-endpoint"]
});- Claude -- AI_CONTEXT.md
- GitHub Copilot -- .github/copilot-instructions.md
- Cursor -- .cursorrules
- Windsurf -- .windsurf/rules.md
- Cline -- .clinerules
- Aider -- .aider.conf.yml
- Continue -- .continue/config.json
- Antigravity -- .agent/README.md
- Gemini -- .gemini/config.md
- @context-engineer -- Setup and configuration
- @core-architect -- System design
- @api-developer -- API development
- @database-ops -- Database operations
- @integration-hub -- External integrations
- @deployment-ops -- CI/CD and deployment
| Variable | Description | Required |
|---|---|---|
OPENROUTER_API_KEY |
API key for intelligent analysis via OpenRouter | For --intelligent flag |
K0NTEXT_PROJECT_ROOT |
Override project root path | Optional |
K0NTEXT_DB_PATH |
Override database file path | Optional |
By default, k0ntext stores its SQLite database at .k0ntext.db in the project root. This file is automatically added to .gitignore.
Each AI tool has its own configuration file path:
- Claude:
AI_CONTEXT.md - Copilot:
.github/copilot-instructions.md - Cursor:
.cursorrules - Windsurf:
.windsurf/rules.md - Cline:
.clinerules - Aider:
.aider.conf.yml - Continue:
.continue/config.json - Antigravity:
.agent/README.md - Gemini:
.gemini/config.md
ποΈ Architecture
k0ntext/
βββ src/ # TypeScript source
β βββ agent-system/ # TodoListManager, TimestampTracker
β βββ agents/ # Smart agents (Cleanup, Performance, Drift, FactCheck)
β βββ analyzer/ # Intelligent codebase analysis
β βββ cli/ # CLI commands, REPL shell, utilities
β β βββ version/ # Version detection system
β β βββ commands/ # Command implementations
β β βββ utils/ # File detector, backup manager
β βββ config/ # Centralized model configuration
β βββ db/ # SQLite database client + migrations
β βββ embeddings/ # OpenRouter integration
β βββ services/ # SnapshotManager and services
β βββ template-engine/ # Handlebars template system
β βββ template-sync/ # Template synchronization
β βββ utils/ # Utilities (chunking, encoding)
β βββ mcp.ts # MCP server implementation
βββ agents/ # Agent definitions
βββ skills/ # RPI workflow skills
βββ templates/ # Output templates
β βββ base/ # Templates synced to user .claude/ directories
β βββ map/ # Map-based context templates
βββ .k0ntext.db # SQLite database (auto-created)
- Initialization --
k0ntext initdiscovers and analyzes codebase - Indexing --
k0ntext indexstores content in SQLite with embeddings - Generation --
k0ntext generatecreates tool-specific context files - Sync --
k0ntext synckeeps all AI tools synchronized - MCP Server --
k0ntext mcpprovides real-time context to AI assistants
The SQLite database contains:
- Context Items -- Workflows, agents, commands, code, docs
- Embeddings -- Vector embeddings for semantic search
- Relations -- Knowledge graph connections
- Sync State -- Change tracking for synchronization (with version tracking)
- Tool Configs -- AI tool configurations
- Generated Files -- File tracking with hashes and backups
- Todo Sessions/Tasks -- Persistent task management
- File Timestamps -- Sync tracking timestamps
- Snapshots -- Database snapshot metadata
π» Development
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Run tests once (no watch)
npm run test:run
# Lint code
npm run lint# Dry run
npm run publish:dry
# Publish to npm
npm run publish:public- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
src/cli/-- Command implementationssrc/db/-- Database operationssrc/analyzer/-- Code analysis logicsrc/agents/-- Smart agentstemplates/-- Context templates.claude/-- Claude Code development context
The PerformanceMonitorAgent provides insights into:
- Query execution times
- Database size and growth
- Slow query detection
- Optimization suggestions
# View performance report
k0ntext performance
# Get JSON metrics
k0ntext performance --jsonπ§ Troubleshooting
-
SQLite Native Extension Issues (Windows)
# Use Node.js LTS version node --version -
OpenRouter API Key Not Found
# Set the environment variable export OPENROUTER_API_KEY=your_api_key_here
-
Database Locked
# Close other instances of k0ntext # Or wait a few seconds
-
Permission Errors
# Check file permissions ls -la .k0ntext.db
# Verbose output for most commands
k0ntext init -v
k0ntext index -v
k0ntext generate -vSee docs/TROUBLESHOOTING.md for the full troubleshooting guide.
- User Guide - Comprehensive guide to k0ntext features, slash commands, agents, and RPI workflow
- Quick Start - Getting started with k0ntext in 5 minutes
- MCP Guide - Model Context Protocol server setup
- Troubleshooting - Common issues and solutions
- GitHub Issues: Report bugs and request features
- Discussions: Join community discussions
MIT License - see LICENSE file for details.
Repository: https://github.com/SireJeff/k0ntext npm Package: https://www.npmjs.com/package/k0ntext Issues: https://github.com/SireJeff/k0ntext/issues MCP Protocol: https://modelcontextprotocol.io
Made with care by SireJeff
