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.

Related MCP server: lnwjud

⚡ 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

1. Gate 1 (Grounded Probe): Recalls relevant past lessons via BM25 ranking and performs read-only codebase reconnaissance.

2. Gate 2 (Cognitive Reasoning): Formulates a 3-option trade-off hypothesis DAG (kilo_think_step) and conducts adversarial stress-testing (kilo_grill_plan).

3. Gate 3 (Approval & Skills): Locks the implementation plan and injects domain-specific expert workflows (kilo_get_skill).

4. Gate 4 (Guarded Execution): Performs surgical code edits backed by atomic writes and syntax validation.

5. 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.

⚡ 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.md instruction 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:

📚 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

🧪 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.