KWCode: a coding agent pipeline for models that cannot call tools

The premise: small models cannot drive a tool-calling agent

KWCode starts from a blunt observation about the agents it competes with. Frameworks such as Claude Code, Cursor and OpenCode are designed around strong language models that call tools, make their own decisions and finish a task on their own. A local open model in the 8B to 30B range cannot do that. It makes mistakes, it hallucinates, and the README is explicit that the difference is capability, not configuration. The design that follows from that is stated in one line: the language model only does classification and generation, while a deterministic pipeline does the deciding and the verifying. Domain knowledge lives in expert modules, and a background process accumulates experience from usage. The small model ends up doing one narrow thing inside a very small context window, which is a job it can actually do. The audience is a developer with a local model and a codebase they cannot send to a hosted service, and the README lists data staying on the machine as one of the five problems the project set out to solve.

The Gate, Locator, Generator, Verifier, Debugger, Reviewer chain

The pipeline is a fixed sequence of stages, and the order is the design. A Gate classifies the task in milliseconds and matches it against domain knowledge. The Locator then finds the relevant files and functions, using BM25 plus a call graph, without calling the model at all. The Generator produces only the changed part of the code, with domain knowledge injected from a SKILL.md file. The Verifier runs a syntax check and pytest on the result, and a failure triggers an immediate retry. If the Verifier still fails, the Debugger captures runtime variable values, and the Reviewer finally compares the request against the actual change. The knowledge injection layer is extensible and sits above the pipeline rather than inside it, with entries for BugFix, FastAPI, TestGen, API, Docstring, MyBatis, Refactor, SpringBoot, SQLOpt, TypeHint, UniApp, and the languages Golang, TypeScript, Rust and Java. The 1.6.1 entry in the changelog records that the earlier WholeFileImplExpert and DependencyFixExpert modules were deleted in favour of purely deterministic mechanisms, with 513 tests green at that point.

Finding the right file with BM25 and an AST call graph

One of the five problems the README names is that existing tools dump a file list to the model and let it guess which file matters, and that a wrong guess poisons everything after it. KWCode replaces the guess with two stages that run in milliseconds and never call the model. The first stage recalls candidates by keyword with BM25. The second expands the result through an AST call graph, following the call chain to find hidden dependencies. The implementation is tree-sitter for multi-language AST parsing, ast-grep predefined template queries, rank-bm25 for the keyword stage, and SQLite for persisting the call graph. Python and JavaScript are covered by the default dependencies, with TypeScript, Go, Rust and Java available as an optional extra. The README credits the approach to cited work on graph traversal and knowledge-graph approaches to software engineering tasks, and it lists a measured advantage for graph traversal over plain BM25 retrieval. The two-stage design is what lets a weak model work on a real repository, because the model never has to hold the file list in its head.

sys.settrace instead of a debugger, with a pytest fallback

The Debug Subagent exists for the case where the Verifier rejects a patch and the model has no idea why. The model decides where to place a breakpoint and which variables to inspect, and the runtime then captures the real values at that line through sys.settrace. It is non-invasive in the sense the README means: no interactive PDB session, and no modification of the source file. The captured runtime data is fed into the next Generator retry, so the second attempt works against evidence rather than against another guess. When the tracing path fails, the fallback is pytest with the --tb=long flag to obtain a full stack trace. The design is credited to work on fixing defects with weak models paired with an interactive debugger, where the pairing matched a strong model baseline. For a user, this matters because a small model rarely self-diagnoses a wrong assumption about a value, and a stack trace alone rarely shows the value that was actually wrong.

DAG scheduling for several tasks in one prompt

When you ask for several changes at once, the README shows a multi mode with parallel branches, a serial chain written with arrows between task names, and an interactive mix where one task depends on the result of the two before it. Underneath is a lightweight DAG scheduler with no new dependency, built on ThreadPoolExecutor and Kahn topological sort. The point of the dependency operator is that the third task in the chain gets to see the code produced by the first two, which is the case a flat parallel run would get wrong. The changelog also records worktree based parallel isolation, added so that parallel tasks do not fight over the working tree. This is the part of the project that leans most on LLMCompiler style decomposition, and it is also the part where the model is asked to do the least: the graph is the plan, not something the model re-derives on every turn.

A flywheel that only promotes an expert after three gates

The self-improvement claim is the most interesting part of the project and also the part with the most specific rules attached. The background flywheel accumulates experience while you use the tool, and the trigger is repetition: five successes at the same kind of task start a draft of a new expert. That draft then has to pass a backtest gate, where the new expert's success rate must be at least the original pipeline's, and an A/B gate, which requires ten real comparisons and an improvement above ten percent. Only when all three gates are cleared does the expert go into production. Everything the flywheel learns is local, the statistics are stored in a local SQLite database, and the project also carries optional anonymous telemetry that is opt-in and protected with HMAC. A separate mechanism watches for behaviour drift and injects a correction, and the changelog records the same idea under a different name, a Wink self-repair monitor, alongside an experience replay that uses BM25 over past traces. If you are evaluating the project on its learning claim, the audit log available through the kwcode log command and the model listing command are where the evidence is meant to be.

Installing kwcode and the dependency set that follows

The package is on PyPI and installs with pip, with a mirror command for slower networks given in the README.

pip install kwcode

The project metadata sets the Python floor and the entry point.

[project]
name = "kwcode"
version = "2.1.0"
requires-python = ">=3.10"

The console script is kwcode, mapped to kaiwu.cli.main:app, and the repository also ships install.sh and install.ps1 at the top level next to the kaiwu package directory. The default dependency set is small and tells you what the core does: typer and rich for the CLI, httpx for HTTP, rank-bm25 and tree-sitter for location, prompt-toolkit for the terminal, and trafilatura with beautifulsoup4 for page text. Everything beyond that is an extra. Multi-language parsing comes with pip install kwcode[multilang], a local model backend with pip install kwcode[local], a FastAPI server with SSE on port 7355 with pip install kwcode[server], and a Textual terminal interface with pip install kwcode[tui], which is also reachable as kwcode --tui. A combined pip install kwcode[full] pulls the local, multilang, server and tui extras together.

An MVP with a 53 percent eval pass rate

Two things decide whether this fits your workflow. The first is the honest framing in the project description, which calls itself an MVP that has not been tested at scale and has not been run end to end. The second is the evaluation numbers in the changelog. Version 2.1.0 reports a ReAct multi-turn loop with automatic retry on task failure, a tool set of read, write, run_test, grep, list_dir and submit, context management that keeps the system prompt, the initial user message and the six most recent turns, and safe writing with a Python syntax check and a block on writing test files. The score it reports is 26 of 50 tasks passing, up from 22 percent, a 141 percent improvement over version 2.0.0, with 6 of 9 Go tasks and 3 of 3 multi-file API tasks passing. The earlier version 2.0.0 entry records a move to an evaluation-driven architecture where the score went from 0 percent to 20 percent on 3 of 15 tasks, with 83 more tests. A pipeline that passes 53 percent of its tasks is not a replacement for an experienced engineer's attention. The project also reports three known limitations of its own kind: it is not a full Node.js compatible runtime, and its stdio host uses the main window's ordinary process flow. The last push to the repository was on 2026-05-14, and there are no GitHub releases, so versions are tracked in CHANGELOG.md and the repository's own STATUS.md, QA_LOG.md and WALKTHROUGH_REPORT.md files.

Editorial conclusion

KWCode fits a team running a small local model on its own hardware, where code cannot leave the machine and the model needs an external pipeline to check its work, and where you are willing to read STATUS.md and QA_LOG.md to judge an MVP. It does not fit a team that wants a finished tool with an end-to-end validated workflow, because the project states it has not been tested at scale, or a team that wants the model to plan its own tool calls. Before adopting it, run the same evaluation set the project scores itself with and read the entry for version 2.1.0 in CHANGELOG.md, since the last push was on 2026-05-14 and the repository has no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. README
3. val1813/kwcode on GitHub