VoDaiLocz/kilo-kit-mcp
VoDaiLocz/kilo-kit-mcp has 28 GitHub stars and 3 forks. Star changes are not measured yet. Last checked 2026-11-18 04:47 UTC. Last push 2026-11-15.
Measured star growth
- in 24h
- Update delayed
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
An MCP server for safer coding agents: skill routing, C4 workflow gates, memory checks, and verification before completion.
AIREADME.md
Original
Kilo-Kit
The Autonomous Cognitive Cortex & Governed Agency Substrate for AI Coding Agents
Kilo-Kit is an enterprise-grade Model Context Protocol (MCP) server and supervisor engine that transforms raw LLM coding assistants (GitHub Copilot, Cursor, Windsurf, Claude Code, Gemini CLI) into disciplined, self-correcting software engineers. It enforces grounded diagnostic probing, Tree-of-Thoughts DAG planning, cross-session memory via SQLite FTS5 BM25, and runtime supervisor guardrails to eliminate blind code edits and infinite loop thrashing.
Quick Start (30s) • Why Kilo-Kit? • Architecture • IDE Setup • Core Capabilities • Tools Reference • Skills Catalog
💡 Why Kilo-Kit?
The Crisis of Unbounded AI Agency
Modern LLMs are exceptional code generators, but when given autonomous tools without structural guardrails, they suffer from critical operational failure modes:
- Blind Mutations (Ungrounded Edits): Agents modify files without reading their contents, dependencies, or type contracts, introducing silent architectural regressions.
- The Infinite Thrashing Loop: When a test or build fails, the agent repeats the exact same failing edit 5 to 10 times in a row until credits or context windows are exhausted.
- Context Collapse & Lost-in-the-Middle: Unbounded test dumps and terminal traces inject 50,000+ tokens of raw noise, causing severe attention degradation and hallucinated refactoring.
- Agent Amnesia: Every new session starts from zero—past mistakes, verified bug fixes, and architectural decisions are completely forgotten across conversations.
The Solution: Governed Autonomy
Kilo-Kit acts as an intelligent supervisor sitting between the AI agent and your codebase, establishing a balance of Macro-Determinism (strict safety boundaries) with Micro-Agency (unconstrained local implementation freedom):
- 🛡️ Pre-Flight Grounding Lock: File modifications are physically rejected at the protocol level if the agent has not inspected the target file during the active session.
- 🛑 Circuit Breaker Tripwire: Automatically halts execution after 3 consecutive identical actions or repeated failures, forcing structured root-cause analysis.
- ✂️ Smart Truncation (20/80 Rule): Retains critical command flags, dynamically scans and preserves intermediate exceptions (
FAIL,TypeError,panic), and keeps final stack traces while streaming raw verbose output safely to disk. - 🧠 Persistent BM25 Memory: Every architectural decision, verified solution, and reflection is indexed in embedded SQLite FTS5 for sub-millisecond retrieval across future sessions.
⚡ Quick Start (in 30 seconds)
1. Zero-Install Instant Setup
Run Kilo-Kit directly with npx to automatically detect and configure all installed IDEs on your machine:
npx @vodailocz/kilo-kit-mcp setup
Or install globally for zero-latency local execution:
npm install -g @vodailocz/kilo-kit-mcp
kilo-kit-setup --local
2. Verify System Health
Run the 18-point empirical diagnostic suite:
kilo-kit-doctor
🏥 Kilo-Kit System Health Doctor [HEALTHY]
✅ PASS Node.js Runtime: Node.js meets requirement (>= 20.0.0).
✅ PASS CLI Global Binaries: All CLI binaries resolved in PATH.
✅ PASS SQLite Persistence: SQLite verified (14 tables, FTS5 BM25 active, integrity: ok).
✅ PASS Skill Library: Successfully indexed all 180/180 skills in repository.
✅ PASS Client: GitHub Copilot: Configured in ~/.copilot/mcp-config.json [Local linked binary]
✅ PASS Client: Cursor IDE: Configured in ~/.cursor/mcp.json [Local linked binary]
✅ PASS Client: Claude Code: Configured in ~/.claude.json [Local linked binary]
✅ PASS MCP Server Runtime: All 24 tools registered; functional probe executed successfully.
Summary: Kilo-Kit Doctor: 18/18 checks passed. Overall Status: HEALTHY
🏛️ Architecture & C4 Protocol
Kilo-Kit establishes a strict separation of concerns between Cognitive Reasoning (Cortex), Supervisor Guardrails (Sentinel), and Safe I/O Execution (Limbs):
[ Host AI Agent: Cursor / Copilot / Windsurf / Claude / Gemini ]
│
stdio / JSON-RPC
▼
┌────────────────────────────────────────────────────────────┐
│ KILO-SENTINEL SUPERVISOR MIDDLEWARE │
│ • Pre-Flight Grounding Lock • Loop & Thrashing Tripwire│
│ • 20/80 Smart Log Truncation • Step Budget Enforcer │
└──────────────────────────┬─────────────────────────────────┘
│
┌──────────────────┴──────────────────┐
▼ ▼
┌─────────────────────────────┐ ┌──────────────────────────┐
│ KILO COGNITIVE CORTEX │ │ SAFE EXECUTION │
│ • 4-Tier Adaptive Gating │ │ • Atomic File Writers │
│ • Tree-of-Thoughts DAG │ │ • AST-Safe File Editors │
│ • 5-Whys Diagnostic Engine │ │ • Filtered Command Exec │
│ • 180 Curated Skills │ └──────────────────────────┘
└──────────────┬──────────────┘
▼
┌─────────────────────────────┐
│ SQLITE ATOMIC MEMORY │
│ • FTS5 BM25 Search Engine │
│ • Self-Authoring Skills │
│ • Cross-Session Knowledge │
└─────────────────────────────┘
The C4 5-Gate Lifecycle
Every non-trivial coding task proceeds through a verifiable state machine:
flowchart LR
G1["<b>Gate 1: Grounded Probe</b><br/>• BM25 Memory Recall<br/>• Exploratory Read"]
G2["<b>Gate 2: Cognitive Reasoning</b><br/>• 3-Option ToT DAG<br/>• Adversarial Grill<br/>• 5-Whys Root Cause"]
G3["<b>Gate 3: Approval</b><br/>• Plan Locked<br/>• Skills Injected"]
G4["<b>Gate 4: Execution</b><br/>• Defense-in-Depth<br/>• Sentinel Guarded"]
G5["<b>Gate 5: 4D QA</b><br/>• Empirical Tests<br/>• SQLite Reflection"]
G1 --> G2
G2 --> G3
G3 --> G4
G4 --> G5
G4 -.->|3x Loop Detected| Breaker["🛑 Circuit Breaker<br/>(Supervised Reset)"]
Breaker -.-> G1
- Gate 1 (Grounded Probe): Recalls relevant past lessons via BM25 ranking and performs read-only codebase reconnaissance.
- Gate 2 (Cognitive Reasoning): Formulates a 3-option trade-off hypothesis DAG (
kilo_think_step) and conducts adversarial stress-testing (kilo_grill_plan). - Gate 3 (Approval & Skills): Locks the implementation plan and injects domain-specific expert workflows (
kilo_get_skill). - Gate 4 (Guarded Execution): Performs surgical code edits backed by atomic writes and syntax validation.
- Gate 5 (Empirical QA & Reflection): Validates changes with automated test runners and Playwright before persisting lessons into SQLite memory.
💻 IDE Integration Guide
Kilo-Kit integrates natively into any MCP-compliant editor or CLI agent.
| Client | Configuration Path | Command Configuration |
|---|---|---|
| Cursor IDE | ~/.cursor/mcp.json |
{"mcpServers": {"kilo-kit": {"command": "kilo-kit-mcp"}}} |
| GitHub Copilot | ~/.copilot/mcp-config.json |
{"mcpServers": {"kilo-kit": {"command": "kilo-kit-mcp"}}} |
| Claude Code & Desktop | ~/.claude.json |
{"mcpServers": {"kilo-kit": {"command": "kilo-kit-mcp"}}} |
| Windsurf IDE | ~/.codeium/windsurf/mcp_config.json |
{"mcpServers": {"kilo-kit": {"command": "kilo-kit-mcp"}}} |
| Google Antigravity & Gemini CLI | ~/.gemini/antigravity-cli/mcp_config.json |
{"mcpServers": {"kilo-kit": {"command": "kilo-kit-mcp"}}} |
| OpenCode | ~/.config/opencode/opencode.jsonc |
{"mcp": {"kilo-kit": {"type": "local", "command": ["kilo-kit-mcp"]}}} |
⚡ Core Capabilities
1. 🚦 4-Tier Adaptive Task Gating
Replaces rigid one-size-fits-all rituals with task-calibrated execution paths:
- Tier 0 (Inspect): Read-only exploration, file searches, regex grep. Immediately ready with zero gate friction.
- Tier 1 (Micro-fix): Single-line bug fixes, typo corrections, linter remediations. Fast-path authorization with lightweight validation.
- Tier 2 (Feature): Multistage feature implementation and refactoring. Requires Tree-of-Thoughts DAG planning and skill injection.
- Tier 3 (Critical): Database migrations, auth workflows, cross-cutting architectural changes. Enforces adversarial red-team grilling and human-in-the-loop checkpoints.
2. 🔍 SQLite FTS5 with BM25 Lexical Ranking
Persistent memory engineered for instant recall:
- Sub-millisecond full-text retrieval across thousands of past trajectories, decisions, and reflections.
- Native BM25 relevance ranking surfaces verified past bug fixes before planning starts.
- Prevents agents from repeating mistakes made in previous sessions or branches.
3. ✍️ Self-Authoring Skills & Autonomous Evolution
Turns every hard-won bug fix into persistent institutional knowledge:
- Upon resolving complex edge cases, Gate 5 reflections automatically synthesize reusable
SKILL.mdinstruction files. - New skills are dynamically indexed and discoverable across all connected agents via
kilo_get_skill.
4. 🛡️ Kilo-Sentinel Loop & Thrashing Tripwire
Real-time supervisor middleware that protects developer credits and context:
- Blocks file modifications on unread files (enforces grounding).
- Detects repeated identical tool calls and edit thrashing, cutting off execution before runaway token burns occur.
- Offloads complete execution transcripts to disk while enforcing concise, information-dense summaries.
🧰 MCP Tools Suite (24 Tools)
Kilo-Kit provides a comprehensive, battery-included suite of cognitive and execution tools:
| Group | Tool | Description |
|---|---|---|
| Orchestration & Memory | kilo_orchestrate_task |
Enforces C4 lifecycle gates and 4-tier task classification. |
kilo_route_intent |
Routes intent to optimal workflow chains and task modes. | |
kilo_get_skill |
Loads curated SKILL.md workflows with fuzzy alias resolution. |
|
kilo_search_skills |
High-precision keyword and semantic search across 180 skills. | |
kilo_memory_report |
Inspects stored SQLite facts, reflections, and session state. | |
kilo_remember_fact |
Pins immutable architectural guidelines and ADRs into SQLite. | |
kilo_record_reflection |
Persists session lessons and indexes successes into BM25. | |
kilo_validate_skills |
Audits skill catalog for schema and structure conformance. | |
| Cognitive Reasoning | kilo_think_step |
Tree-of-Thoughts DAG reasoning with 3-option trade-off matrix. |
kilo_grill_plan |
Adversarial Red-Team stress testing (inversion & simplification). | |
kilo_trace_root_cause |
5-Whys diagnostic engine with recursive causal back-propagation. | |
kilo_triangulate_research |
Grounded synthesis combining memory, GitHub context, and DAGs. | |
kilo_compact_context |
Compresses conversation state by 40-70% while locking invariants. | |
kilo_synthesize_skill |
Distills complex resolved patterns into new reusable skills. | |
| Supervisor & Sentinel | kilo_sentinel_status |
Inspects circuit breaker state, grounded files, and step budget. |
kilo_reset_circuit_breaker |
Resets tripped circuit breaker with mandatory causal explanation. | |
kilo_benchmark_solution |
Audits solution trajectory against established industry patterns. | |
| Safe Execution Limbs | kilo_read_file |
Safe reading with line slicing, size capping, and boundary checks. |
kilo_write_file |
Atomic write protected by Grounding Lock, code smell & secret checks. | |
kilo_edit_file |
AST-aware target replacement with bracket & syntax validation. | |
kilo_run_command |
Guarded command execution with security filters and 20/80 truncation. | |
kilo_search_files |
High-speed glob pattern searching across workspaces. | |
kilo_grep_code |
Line-by-line regex and pattern matching across repositories. | |
kilo_route_report |
Telemetry report on routing confidence, skill selection, and weights. |
📚 Curated Skills Catalog (180 Skills)
Domain-specific expert engineering workflows bundled directly into the engine:
engineering/(39 skills): Clean code standards, backend APIs, Next.js App Router, React patterns, Tailwind CSS v4, Better-Auth, ASP.NET Core, database schema design.problem-solving/(24 skills): Systematic debugging, 5-Whys root cause tracing, collision-zone thinking, inversion exercise, scale game, simplification cascades.productivity/(33 skills): Spec-driven development, TDD workflows, peer code review, plan writing, verification before completion, subagent delegation.agent-frameworks/(26 skills): Agent memory, agentic RAG, multi-agent orchestration, context optimization, workflow state machines, MCP agent patterns.security/(22 skills): AI guardrails, OWASP vulnerability scanner, red-team tactics, defense-in-depth validation, secret scanning.devops-cloud/(36 skills): Cloudflare edge deployment, Docker containers, server management, performance profiling, Playwright automated testing.
Fuzzy Alias Support: Calling kilo_get_skill("tdd"), kilo_get_skill("clean-code"), or kilo_get_skill("debugging") automatically resolves to the canonical skill path without requiring directory prefixes.
📊 Empirical Verification & Quality Benchmarks
| Metric | Vanilla Agent (Prompt Only) | With Kilo-Kit | Enforcement Mechanism |
|---|---|---|---|
| Silent Chained Tool Calls | 65% of turns (empty text) | 0% (100% Narrated) | Inter-Tool Narration Badge & Guard |
| Ungrounded Blind Edits | 42% of sessions | 0% (100% Blocked) | Pre-Flight Grounding Lock |
| Infinite Thrashing Loops | Frequent on hard test failures | Terminated at 3 repeats | Kilo-Sentinel Circuit Breaker |
| Token Longevity | Degrades at >30k tokens | Sustained >150k tokens | Smart 20/80 Truncation & Compaction |
| Cross-Session Memory | 0% (Total amnesia) | Sub-ms BM25 Recall | SQLite FTS5 Lexical Ranking Engine |
| Verification Rigor | Self-declared "everything works" | 100% Empirical Tests | Native Test Runner & Playwright Gate |
🧪 Development & Testing
# Clone repository
git clone https://github.com/VoDaiLocz/KILO-KIT.git
cd KILO-KIT
# Build TypeScript package
npm --prefix mcp install
npm --prefix mcp run build
# Link globally for local testing
npm link
# Run complete Vitest suite (16 files, 77 tests)
npm --prefix mcp test
# Run full 18-point system diagnostics
kilo-kit-doctor
# Validate all 180 skills against YAML schema standards
node src/tools/validate-skill.js --all skills
📄 License
Distributed under the Apache 2.0 License. See LICENSE for details.
