Back to Details

kwcode-local-coding-agent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

KWCode Local Coding Agent

KWCode 本地编码Agent

Skill by ara.so — Daily 2026 Skills collection.
KWCode is a CLI coding agent designed specifically for local open-source models (8B–30B parameters). Unlike cloud-first agents (Claude Code, Cursor), KWCode uses a deterministic expert pipeline where the LLM only classifies and generates — all routing, validation, and decision-making is handled by deterministic code. This lets small models succeed where they would otherwise hallucinate or loop.
由ara.so开发的技能 — 属于Daily 2026技能合集。
KWCode是一款专为本地开源模型（8B–30B参数）设计的CLI编码Agent。与优先适配云端的Agent（如Claude Code、Cursor）不同，KWCode采用确定性专家流程，LLM仅负责分类和生成任务，所有路由、验证和决策环节均由确定性代码处理。这让小模型能够完成原本会出现幻觉或循环的任务。

Installation

安装

bash
undefined
bash
undefined

Standard install

标准安装

pip install kwcode
pip install kwcode

China mirror (faster in mainland)

国内镜像（大陆地区更快）

pip install kwcode -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install kwcode -i https://pypi.tuna.tsinghua.edu.cn/simple

Optional: Cross-Encoder search reranking

可选：Cross-Encoder搜索重排序

pip install "kwcode[rerank]"

**Requirements:** Python 3.10+, any OpenAI-compatible API (local or cloud).

---
pip install "kwcode[rerank]"

**系统要求：** Python 3.10+，任何兼容OpenAI的API（本地或云端）。

---

Quick Start

快速开始

bash
undefined
bash
undefined

Launch interactive REPL

启动交互式REPL

kwcode

On first launch, KWCode runs a setup wizard to configure your model connection.

---
kwcode

首次启动时，KWCode会运行设置向导来配置模型连接。

---

Configuration

配置

Connect to a local inference engine (Ollama example)

连接到本地推理引擎（Ollama示例）

bash
undefined
bash
undefined

Inside kwcode REPL or as a slash command:

在kwcode REPL内或作为斜杠命令执行：

/api default http://localhost:11434/v1 ollama qwen3:8b
undefined
/api default http://localhost:11434/v1 ollama qwen3:8b
undefined

Connect to a cloud API (no local GPU needed)

连接到云端API（无需本地GPU）

bash
/api default https://api.deepseek.com $DEEPSEEK_API_KEY deepseek-coder
/api default https://api.siliconflow.cn/v1 $SILICONFLOW_API_KEY Qwen/Qwen3-8B
bash
/api default https://api.deepseek.com $DEEPSEEK_API_KEY deepseek-coder
/api default https://api.siliconflow.cn/v1 $SILICONFLOW_API_KEY Qwen/Qwen3-8B

Environment variable approach

环境变量配置方式

bash
export KWCODE_API_BASE=http://localhost:11434/v1
export KWCODE_API_KEY=ollama
export KWCODE_MODEL=qwen3:8b
kwcode
bash
export KWCODE_API_BASE=http://localhost:11434/v1
export KWCODE_API_KEY=ollama
export KWCODE_MODEL=qwen3:8b
kwcode

Recommended models by VRAM

按显存推荐的模型

VRAMModel
4 GB
gemma3:4b
8 GB
qwen3:8b
16 GB
qwen3:14b
24 GB+
qwen3:30b-a3b
显存模型
4 GB
gemma3:4b
8 GB
qwen3:8b
16 GB
qwen3:14b
24 GB+
qwen3:30b-a3b

Key Commands

核心命令

All commands are entered inside the 
kwcode
REPL (
>
prompt).
所有命令需在
kwcode
REPL（
>
提示符）内输入。

Core task commands

核心任务命令

> <natural language task description>
> 修复登录验证失败的问题
> write a FastAPI login endpoint with JWT auth
> refactor calculate_price into smaller functions
> <自然语言任务描述>
> 修复登录验证失败的问题
> write a FastAPI login endpoint with JWT auth
> refactor calculate_price into smaller functions

Planning & safety

规划与安全

> /plan <task description>
Shows execution steps and risk level (High / Medium / Low) before touching any file. Requires confirmation.
> /checkpoint
Manually snapshot current project state. KWCode also auto-snapshots before each task.
> /rollback
Restore to the last checkpoint if a task goes wrong.
> /plan <任务描述>
在修改任何文件前，展示执行步骤和风险等级（高/中/低），需确认后执行。
> /checkpoint
手动快照当前项目状态。KWCode也会在每个任务前自动创建快照。
> /rollback
若任务执行出错，恢复到上一个检查点状态。

Multi-task orchestration (DAG)

多任务编排（DAG）

> /multi task1 ; task2 ; task3          # all parallel
> /multi task1 -> task2 -> task3        # serial chain
> /multi                                # interactive builder
Interactive multi-task example:
> /multi
  + add docstring to function `add`       (parallel)
  + add docstring to function `sub`       (parallel)
  + >write tests for the modified code    (serial, depends on above two)
> /multi task1 ; task2 ; task3          # 全部并行执行
> /multi task1 -> task2 -> task3        # 串行链式执行
> /multi                                # 交互式构建器
交互式多任务示例：
> /multi
  + 为函数`add`添加文档字符串       (并行)
  + 为函数`sub`添加文档字符串       (并行)
  + >为修改后的代码编写测试用例    (串行，依赖前两项)

Search enhancement

搜索增强

bash
undefined
bash
undefined

Install SearXNG (requires Docker Desktop running)

安装SearXNG（需Docker Desktop运行）

kwcode setup-search
undefined
/search <query> # explicit search inside REPL

Without Docker, KWCode falls back to DuckDuckGo automatically.
kwcode setup-search
undefined
/search <查询内容> # 在REPL内执行显式搜索

若未安装Docker，KWCode会自动回退到DuckDuckGo搜索。

Statistics & flywheel

统计与飞轮机制

bash
kwcode stats            # CLI command (outside REPL)
Shows tasks completed, estimated time saved, and flywheel expert promotions.
bash
kwcode stats            # CLI命令（在REPL外执行）
展示已完成任务、预估节省时间以及飞轮机制的专家晋升情况。

API management

API管理

> /api list                              # show configured endpoints
> /api default <base_url> <key> [model] # set default endpoint
> /api add <name> <base_url> <key>      # add named endpoint
> /api use <name>                        # switch active endpoint
> /api list                              # 展示已配置的端点
> /api default <base_url> <key> [model] # 设置默认端点
> /api add <name> <base_url> <key>      # 添加命名端点
> /api use <name>                        # 切换到指定端点

Project Configuration Files

项目配置文件

KWCode looks for these files in your project root and injects them as context:
FilePurpose
KWCODE.md
Project-level rules, conventions, coding standards. Injected per task type.
PROJECT.md
Auto-maintained project summary (Layer 1 memory).
EXPERT.md
Domain expert knowledge accumulated by the flywheel (Layer 2).
PATTERN.md
Recurring code patterns learned from your project (Layer 3).
REFLECTION.md
Structured log of past failures and lessons (auto-updated).
KWCode会在项目根目录查找以下文件，并将其作为上下文注入：
文件用途
KWCODE.md
项目级规则、约定、编码规范，按任务类型注入上下文。
PROJECT.md
自动维护的项目摘要（第一层记忆）。
EXPERT.md
飞轮机制积累的领域专家知识（第二层记忆）。
PATTERN.md
从项目中学习到的重复代码模式（第三层记忆）。
REFLECTION.md
结构化的过往失败记录与经验总结（自动更新）。

Example 
KWCODE.md

KWCODE.md
示例

markdown
undefined
markdown
undefined

Project Rules

项目规则

bugfix

bug修复

  • Always run 
    pytest tests/
    after any fix
  • Never modify migration files directly
  • 修复后必须运行
    pytest tests/
  • 禁止直接修改迁移文件

codegen

代码生成

  • Use 
    async def
    for all new route handlers
  • Import order: stdlib → third-party → local
  • 所有新路由处理函数使用
    async def
  • 导入顺序：标准库 → 第三方库 → 本地模块

general

通用规则

  • Line length: 88 (black default)
  • All new functions must have type hints

---
  • 行长度：88（black默认值）
  • 所有新函数必须包含类型提示

---

How the Expert Pipeline Works

专家流程工作原理

Every user input flows through five deterministic stages:
Input
  └─► Gate       — classifies task, routes to skill, matches domain knowledge
        └─► Locator    — BM25 keyword recall + AST call-graph expansion (no LLM)
              └─► Generator  — generates only the changed diff, injects SKILL.md
                    └─► Verifier   — syntax check + pytest (deterministic)
                          └─► Debugger   — sys.settrace captures live variable values
                                └─► Reviewer   — LLM checks intent vs actual change
The LLM is only called at Generator and Reviewer stages. Everything else is deterministic Python.
用户输入会经过五个确定性阶段：
输入
  └─► 网关       — 分类任务、路由到对应技能、匹配领域知识
        └─► 定位器    — BM25关键词召回 + AST调用图扩展（无LLM参与）
              └─► 生成器  — 仅生成变更的diff，注入SKILL.md
                    └─► 验证器   — 语法检查 + pytest（确定性）
                          └─► 调试器   — 通过sys.settrace捕获实时变量值
                                └─► 审核器   — LLM检查意图与实际变更是否匹配
LLM仅在生成器和审核器阶段被调用，其余环节均由确定性Python代码处理。

Code Examples

代码示例

Trigger a bugfix task

触发bug修复任务

python
undefined
python
undefined

KWCode detects "bug", "fix", "error", "失败" → routes to BugFix expert

KWCode检测到"bug"、"fix"、"error"、"失败"等关键词 → 路由到BugFix专家

Inside REPL:

在REPL内执行：

> fix the KeyError in user_service.py when email is missing

> fix the KeyError in user_service.py when email is missing


KWCode will:
1. BM25-locate `user_service.py` + trace call graph for hidden dependencies
2. Generate a minimal patch (only changed lines)
3. Run `pytest` automatically
4. If failing: inject runtime variable values via `sys.settrace` and retry

KWCode会执行以下操作：
1. 通过BM25定位`user_service.py` + 追踪调用图查找隐藏依赖
2. 生成最小化补丁（仅包含变更行）
3. 自动运行`pytest`
4. 若测试失败：通过`sys.settrace`注入运行时变量值并重试

Trigger a test generation task

触发测试生成任务

> generate pytest tests for the PaymentProcessor class
KWCode injects the 
TestGen
SKILL.md, locates 
PaymentProcessor
via AST, generates tests, and verifies they pass.
> generate pytest tests for the PaymentProcessor class
KWCode会注入
TestGen
SKILL.md，通过AST定位
PaymentProcessor
，生成测试用例并验证其通过。

Use the Python API (programmatic access)

使用Python API（程序化调用）

python
from kwcode import KWCodeAgent

agent = KWCodeAgent(
    api_base="http://localhost:11434/v1",
    api_key="ollama",
    model="qwen3:8b",
    project_dir="/path/to/your/project",
)

result = agent.run("fix the login validation bug")
print(result.status)        # "success" | "failed" | "rolled_back"
print(result.files_changed) # list of modified file paths
print(result.patch)         # unified diff string
python
from kwcode import KWCodeAgent

agent = KWCodeAgent(
    api_base="http://localhost:11434/v1",
    api_key="ollama",
    model="qwen3:8b",
    project_dir="/path/to/your/project",
)

result = agent.run("fix the login validation bug")
print(result.status)        # "success" | "failed" | "rolled_back"
print(result.files_changed) # 修改文件路径列表
print(result.patch)         # 统一diff字符串

Multi-task via Python API

通过Python API执行多任务

python
from kwcode import KWCodeAgent, TaskGraph

agent = KWCodeAgent(model="qwen3:14b", project_dir=".")

graph = TaskGraph()
t1 = graph.add("add type hints to utils.py")
t2 = graph.add("add type hints to models.py")
t3 = graph.add("write tests for typed functions", depends_on=[t1, t2])

results = agent.run_graph(graph)
for task_id, result in results.items():
    print(f"{task_id}: {result.status}")
python
from kwcode import KWCodeAgent, TaskGraph

agent = KWCodeAgent(model="qwen3:14b", project_dir=".")

graph = TaskGraph()
t1 = graph.add("为utils.py添加类型提示")
t2 = graph.add("为models.py添加类型提示")
t3 = graph.add("为带类型提示的函数编写测试用例", depends_on=[t1, t2])

results = agent.run_graph(graph)
for task_id, result in results.items():
    print(f"{task_id}: {result.status}")

Three-Stage Retry Logic

三级重试逻辑

When 
Verifier
fails, KWCode does not repeat the same attempt:
AttemptStrategy
1stNormal task description sent to Generator
2ndError message + 
sys.settrace
runtime variable dump injected; LLM reflects on why attempt 1 failed
3rdMinimal-change constraint enforced; Debug Subagent provides full 
pytest --tb=long
trace
After 3 failures, task is marked failed and rolled back to checkpoint.
当
验证器
失败时，KWCode不会重复相同尝试：
尝试次数策略
第1次将常规任务描述发送给生成器
第2次注入错误信息 + 
sys.settrace
运行时变量快照；LLM反思首次尝试失败原因
第3次强制执行最小变更约束；调试子Agent提供完整的
pytest --tb=long
追踪信息
3次尝试失败后，任务标记为失败并回退到检查点。

Troubleshooting

故障排查

Model returns garbled output or loops

模型返回乱码或循环输出

/api default <your_base_url> <key> <model>   # re-confirm model name matches server
Check that your local inference engine is running:
bash
curl http://localhost:11434/v1/models        # Ollama
curl http://localhost:8080/v1/models         # llama.cpp / LM Studio
/api default <your_base_url> <key> <model>   # 确认模型名称与服务器匹配
检查本地推理引擎是否运行：
bash
curl http://localhost:11434/v1/models        # Ollama
curl http://localhost:8080/v1/models         # llama.cpp / LM Studio

KWCode can't find the right file

KWCode无法找到正确文件

BM25 needs indexed content. If your project is new:
> /index                    # force re-index project files
If the file uses an unusual extension, add it to 
KWCODE.md
:
markdown
undefined
BM25需要索引内容。若项目是新建的：
> /index                    # 强制重新索引项目文件
若文件使用非常规扩展名，可添加到
KWCODE.md
：
markdown
undefined

index

index

  • include: [".pyx", ".pxd", "*.proto"]
undefined
  • include: [".pyx", ".pxd", "*.proto"]
undefined

pytest not found / tests not running

pytest未找到/测试未运行

> /config verifier.test_cmd "python -m pytest tests/ -x"
Or set in 
KWCODE.md
:
markdown
undefined
> /config verifier.test_cmd "python -m pytest tests/ -x"
或在
KWCODE.md
中设置：
markdown
undefined

verifier

verifier

  • test_cmd: python -m pytest tests/ -x --tb=short
undefined
  • test_cmd: python -m pytest tests/ -x --tb=short
undefined

Search not working (DuckDuckGo blocked)

搜索无法工作（DuckDuckGo被屏蔽）

bash
undefined
bash
undefined

Install local SearXNG (requires Docker)

安装本地SearXNG（需Docker）

kwcode setup-search
kwcode setup-search

Verify it's running

验证是否运行

curl http://localhost:8080/search?q=test&format=json
undefined
curl http://localhost:8080/search?q=test&format=json
undefined

Context window overflow with large projects

大型项目上下文窗口溢出

KWCode auto-compresses context when it approaches the limit, but you can tune aggressiveness:
> /config context.compression_ratio 0.6    # keep 60% of mid-conversation history
> /config locator.max_files 3              # limit files sent to Generator
当接近上下文限制时，KWCode会自动压缩上下文，你也可以调整压缩程度：
> /config context.compression_ratio 0.6    # 保留60%的对话历史
> /config locator.max_files 3              # 限制发送给生成器的文件数量

Flywheel expert not promoting

飞轮机制专家未晋升

Promotion requires: ≥5 successes of the same task type → backtest pass rate ≥ baseline → 10-run A/B test with >10% improvement. Check flywheel status:
kwcode stats --flywheel
晋升需要满足：≥5次相同任务类型的成功 → 回溯通过率≥基准线 → 10次A/B测试提升率>10%。查看飞轮状态：
kwcode stats --flywheel

Skill Domains (SKILL.md Library)

技能领域（SKILL.md 库）

KWCode ships with 15 built-in domain skills injected at Generator stage:
SkillTriggers
BugFix
fix, bug, error, crash, 修复
FastAPI
fastapi, route, endpoint, async
TestGen
test, pytest, unittest, 测试
API
api, rest, http, request
DeepSeekAPI
deepseek, r1, v3
Docstring
docstring, document, 注释
MyBatis
mybatis, mapper, xml, sql
Office
excel, word, ppt, spreadsheet
Refactor
refactor, clean, extract, 重构
SpringBoot
spring, springboot, java
SQLOpt
sql, query, optimize, index
TypeHint
type hint, annotation, mypy
UniApp
uniapp, vue, miniprogram
Custom skills can be added by placing a 
SKILL_<name>.md
file in your project root or 
~/.kwcode/skills/
.
KWCode内置15个领域技能，会在生成器阶段注入：
技能触发词
BugFix
fix, bug, error, crash, 修复
FastAPI
fastapi, route, endpoint, async
TestGen
test, pytest, unittest, 测试
API
api, rest, http, request
DeepSeekAPI
deepseek, r1, v3
Docstring
docstring, document, 注释
MyBatis
mybatis, mapper, xml, sql
Office
excel, word, ppt, spreadsheet
Refactor
refactor, clean, extract, 重构
SpringBoot
spring, springboot, java
SQLOpt
sql, query, optimize, index
TypeHint
type hint, annotation, mypy
UniApp
uniapp, vue, miniprogram
自定义技能可通过在项目根目录或
~/.kwcode/skills/
放置
SKILL_<name>.md
文件添加。

Data & Privacy

数据与隐私

  • All processing is local. No code, file contents, or task descriptions leave your machine.
  • Model inference: your local engine or your chosen cloud API endpoint only.
  • Search: SearXNG self-hosted (recommended) or DuckDuckGo (queries only, no code).
  • Statistics: stored in 
    ~/.kwcode/stats.db
    (SQLite, local only).
  • Reflection/memory files: written to your project directory, fully under your control.
  • 所有处理均在本地完成，代码、文件内容或任务描述不会离开你的设备。
  • 模型推理：仅使用你的本地引擎或你选择的云端API端点。
  • 搜索：推荐使用自托管SearXNG，或使用DuckDuckGo（仅发送查询内容，无代码）。
  • 统计数据：存储在
    ~/.kwcode/stats.db
    （SQLite，仅本地存储）。
  • 反思/记忆文件：写入你的项目目录，完全由你掌控。