改善 AI システム — squeeze every bit out of every watt.
An agentic AI coding harness: describe your program in words, and a pool of local (or frontier) models evolves it through a guarded pipeline — build → verify → score — while you watch every generation live.
📖 Complete reference for humans and AI agents:
MANUAL.md — every panel, every command, the spec
reference, routing, safety, and the full config. For the LLM-facing
protocol specifically: docs/KAI.md. Model
compatibility matrix: docs/MODELS.md. Release
history: CHANGELOG.md.
- First run — a setup wizard connects your model (local llama.cpp endpoint or any OpenAI-compatible API) and creates a project: one-click demo, AI agent setup (paste code + goal in words), or manual.
- The pipeline canvas — node-editor-style connected nodes. Each node is an inline python or shell script (or a harness file) with args, timeouts, and per-metric parse rules. Click to edit, arrows show flow. ▶ Test pipeline runs the real thing on the baseline in a temp copy. ✨ AI build my pipeline designs + validates it for you to review.
- Evolution — the engine feeds the champion to your models with
tier-aware prompts (tiny/small/large), extracts their code, guardrails
it, and scores every candidate for real. Linters (pyflakes/ruff,
bash -n,node --check, gcc-family) auto-fix mechanical errors. - 🧠 Agent — a multi-turn tool loop over a project: reads the spec, history, champion, lessons; runs the pipeline; edits the spec with validation. Every mutation snapshots first.
KAISEN is not only a human tool. KAI is its line-oriented protocol that lets an LLM agent spawn KAISEN as a sidecar: hand over the performance-critical part of a program, keep working on something else, and read back the improved code later. KAISEN evolves forever by default — stopping only when the agent says so (or a goal flag is set).
$ python main.py --kai # stdio server (spawns the dashboard if needed)
BASELINE c # the hot function / kernel the AI owns
static inline void hot_loop(...) { ... }
END
GOAL make this 2x faster without changing the output
ACCEPT hot-loop-fast # review the spec JSON first, then instantiate
RUN # evolve in the background — forever by default
WAIT 300 # the AI works on the GUI meanwhile
BEST # read the champion back into the project
STOP
HTTP transport: POST /kai on the dashboard (text/plain in, text/plain out;
one command per line, PROJECT <id> inside the body for stateless clients).
Command reference (case-insensitive; HELP prints this):
PROJECT <id> set session project
STATUS engine + project status
SPEC pipeline steps, metrics, goal
RUN [<n>] [FOR <secs>] [ON <pid>] start evolving NOW (background).
No goal = run FOREVER until STOP. <n> = stop
after n generations; FOR <secs> = time budget.
WAIT [<secs>] block until the in-flight run finishes
PAUSE | RESUME | STOP engine control
BEST champion source code
SMOKE run pipeline once on the baseline
BASELINE [lang] stage starting code: lines until END
CANDIDATE [lang] queue code into evolution: lines until END
SNAPSHOT [LIST|TAKE|RESTORE <id>] [ON <pid>]
SERVERS LLM servers + active set
GOAL <words...> AI designs + validates a project (blocking)
ACCEPT <id> create the project from the last GOAL spec
CREATE <id> <spec-json> create a project from a hand-written spec
Designed for small models: every reply starts with OK or ERR; command
words have loose aliases; leading OK , quotes, and punctuation are
tolerated on input; a session remembers the project, staged baseline, and
the in-flight run. RUN reports progress in scored generations (the
queue counter can run ahead of the workers).
Agent-writer notes: for local llama.cpp servers the raw /completion
endpoint applies no server-side chat template — but KAISEN frames every
instruct model's prompt in ITS OWN native chat format (the resolved
chat_template) and strips the reasoning channel from the captured reply.
So gpt-oss and Qwen3 both work without you writing template markup; set
chat_template: "none" on a server to send prompts exactly as-given.
Reasoning models think before answering — gpt-oss: tune
params.reasoning_effort: "low" for snappy turns (medium/high buy
deliberation at a latency cost); Qwen3: it always thinks, so leave a
generous n_predict. On reasoning OpenAI-compatible models, prefer
reasoning_effort: "none" (or chat_template_kwargs: {"enable_thinking": false} on llama.cpp chat endpoints) for KAI tool-call turns. Never prefix
model output with OK — the server does that.
Full protocol reference: docs/KAI.md — command table,
grammar, session semantics, and the reliability contract.
- Per-language candidate guards: process spawning, file deletion, and network egress are denied by default for every language (C-family, Python, shell, JS/TS, Java, Go, Rust, …). Inline pipeline nodes are scanned with the rule set of their script language.
- Protected data: declared data files are hashed before every stage; any modification fails the run.
- Resource limits: per-step timeouts + RSS memory limits; score early-abort kills provably-worse candidates mid-benchmark.
- Revert: every agent/config mutation snapshots the project (or the global config) first — Settings → Snapshots restores with one click.
- Secrets: API keys live in
secrets.json(0600, gitignored), never inconfig.json; env vars (KAISEN_SERVER_<ID>_API_KEY) take precedence.
The dashboard, /kai and /api have no authentication by default:
the default bind is 127.0.0.1 — loopback only. Setting server.host
to 0.0.0.0 in config.json exposes the full control surface to your
LAN; do it only on a trusted network.
Optional server password: set server.api_key in config.json (the
environment variable KAISEN_API_KEY wins). When set, every page and
endpoint requires it — browsers get the standard Basic-auth password
prompt (any username, the key as password), API clients send
Authorization: Bearer <key>. Leave it empty for the open,
loopback-only default.
The global safety switch additionally requires BOTH config.json
safety.global_off: true AND the environment variable
KAISEN_SAFETY_OFF=1 before any guardrail is relaxed — neither is ever
toggleable from the GUI.
When a build fails, KAISEN repairs in five guarded stages:
- deterministic compiler-hint fixes (missing includes, "did you mean",
_GNU_SOURCE, SIMD-target pragmas, literal\n, avxintrin rewrite); - per-compiler nudges for every language — each backend parses THAT
compiler's own diagnostics and does exactly what it suggests (rustc
missing
;/unclosed delimiter, go undefined import, bash unbalanced)/missingthen, node EOF, python ast:/indentation, perl …); - linter-backed fixes for Python candidates;
- a project's own custom fixer script (
skills.autofix_build: "path"); - LLM last-resort repair — up to
llm_repair_max(default 3) LLM rewrites per generation, each fed the candidate source plus the real compiler error. The reply is danger-scanned and length-capped, only the candidate file may change, and the result re-runs the FULL pipeline (build + verify + score) before it can count. Never on the user's baseline; switchable off (config.json→autofix.llm_repair: false).
The full generation lifecycle — prompt → guardrails → pipeline → autofix
ladder → scoring → champion — is drawn as a flowchart in
MANUAL.md §6.
KAISEN has evolved real kernels autonomously (llama.cpp experiments): an AVX2 SiLU 1.6x faster than llama.cpp's own AVX2 implementation (0.242 vs 0.389 ms, max relative error 0.19%, verified by dense sweep), and an AVX2 GELU ~74x faster than the naive scalar path (max error 2.1% — above the 1% goal, disclosed here rather than hidden).
The end-to-end effect on gpt-oss-20b Q8_K inference is zero: decode and prompt processing are ~90% Q8_K GEMM, and activation kernels are single-digit percent of the trace (measured stock vs patched parity on CPU and GPU). Real end-to-end wins on GEMM-bound models require improving the GEMM itself — which is exactly the kind of target KAISEN is built to grind. Judge results by measurement, not by headline multipliers.
pip install pytest
python -m pytest tests/Covers the HTTP API + engine pool scoping, suggest gates, every deterministic autofix rule, the KAI grammar, tier routing, cap-fill allocation, chat templates, the D language registry, temp-project best resolution, two-stage scoring, budget semantics, and the LLM repair flow (440+ tests, no network, temp dirs only).
kaisen/
engine.py evolution loop (producer → workers → champion)
pipeline.py build → verify* → score* runner (inline steps, autofix)
agent.py JSON-action tool loop per project
kai.py KAI protocol — the LLM-facing API (stdio + /kai HTTP)
suggest.py guarded AI project/pipeline builder
promptlib.py tier-aware prompt library (the single source of truth)
linters.py local lint/autofix backends
autofix/ per-compiler fixers, one module per language (c_family, rust, go, …)
languages.py 23-language registry (extensions, fences, guard patterns)
factory.py project factory — 25 algos × all 23 languages, self-checked
fuzzlib.py seeded fuzz-case generator (the anti-"fast but wrong" gate)
campaign.py resumable multi-project campaign driver + bug capture
snapshots.py project/config revert store
pages/ the dashboard (single-page, no build step)
projects/ one directory per project: project.json + harness + data
./install.sh # venv + deps; PEP-668 safe (Ubuntu 24.04/26.04, Debian 12+)
# ...or by hand: python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
./.venv/bin/python main.py # dashboard on http://127.0.0.1:8080 (loopback only)
.venv/bin/python main.py --project my-project --parallel-gens 2 --workers 4Config lives in config.json (gitignored; see config.example.json).