KWCode is a command-line interface (CLI) coding agent designed to enhance local, open-source language models, particularly for developers prioritizing data privacy and local execution. It addresses the limitations of smaller models in complex coding tasks by employing a deterministic, pipeline-based architecture rather than relying solely on LLM reasoning. This approach makes it suitable for users who need a secure, efficient coding assistant that runs entirely on their machine, learning and adapting over time.

How It Works

KWCode utilizes a deterministic, five-stage expert pipeline: Gate (task classification/routing), Locator (code element identification via BM25 and AST call graphs), Generator (code modification), Verifier (syntax and test validation), and Debugger (runtime variable capture using sys.settrace). This pipeline is augmented by 15 domain-specific "SKILL.md" knowledge modules. The system avoids context window limitations through algorithmic compression and handles repetitive errors via a three-stage retry mechanism with reflection and debugging. A "flywheel" mechanism continuously accumulates experience from task trajectories, refining prompts and generating new expert capabilities through rigorous validation gates.

Quick Start & Requirements

• Primary Install: pip install kwcode
• Prerequisites: Python 3.10+, an OpenAI-compatible API endpoint (for local models like Qwen3, Gemma3, or cloud services like DeepSeek), Docker (optional, for SearXNG search enhancement).
• Hardware: Local model execution requires sufficient VRAM (e.g., 8GB for qwen3:8b, 16GB for qwen3:14b). macOS users can leverage Ollama with Apple Silicon's unified memory.
• Links: Python, License

Highlighted Details

• Data Security: All code and operations remain local; no data is sent to external servers.
• Native Windows Support: Runs directly via cmd/PowerShell without WSL2.
• Advanced Code Location: Employs BM25 keyword retrieval combined with AST call graph traversal for precise file and function identification, bypassing LLM guesswork.
• Runtime Debugging: The Debug Subagent captures real-time variable values using sys.settrace during verification failures, providing crucial data for retries.
• Multi-Task Orchestration: Supports complex workflows through a lightweight DAG scheduler, enabling parallel and serial task execution.
• Continuous Improvement: An "expert flywheel" system automatically generates and validates new domain knowledge (SKILL.mds) based on successful task patterns.

Maintenance & Community

The project is actively developed, with version 1.0.9 released recently. Contributions are welcomed, particularly in adding new domain knowledge (SKILL.mds) and improving multi-language AST support. The project references numerous academic papers, indicating a research-driven approach.

Licensing & Compatibility

Licensed under the MIT License, permitting commercial use and modification with minimal restrictions.

Limitations & Caveats

The project is currently in an MVP (Minimum Viable Product) stage and has not undergone large-scale, end-to-end testing. While robust, the core pipeline architecture and the Gate module's JSON output format are considered fixed and not intended for modification.