Agent Kaizen is an open-source, local-first engineering framework and harness for coding agents in VS Code and eventually other hosts, or maybe standalone. It is built around one idea of finely controlling agent output and maintaining all data in a reasonable manner, not a mess of JSONL files. Repo: https://github.com/LevyBytes/agent-kaizen.
flowchart LR
S(["Scope"]) --> A(["Adapt"]) --> V(["Verify"]) --> M(["Manage"]) --> I(["Improve"])
I -. "continual self-improvement" .-> S
SAVMI = Scope -> Adapt -> Verify -> Manage -> Improve
Note
This repo is in active development even if you do not see new commits for a while. It needs a lot of work. I will remove this note when it is ready for use.
I had three specific problems:
The controls were not deterministic. What an agent does varies with phrasing, context, and model. I wanted good code and consistent always followed behaviors. That's not how it works today unfortunately.
Subagents did not respect the sandbox. I watched them write outside the paths they were scoped to. And the more agents I ran at once, babysitting what they did became more troublesome.
I could not see what the models actually did. When something went wrong I wanted to read the sequence that produced it, not reconstruct it from a chat window that had already scrolled away.
So the project started from the assumption that if the work is not written down as it happens, in a form I can query, then it did not happen in any way I can rely on later.
Most harnesses run their own conversations; Kaizen keeps the enterprise around it. Every conversation, direct-driven against an open-weight model or harness-driven through a closed provider's own harness, lands in one durable, organized record layer. On top of that layer: fleet development across machines, local LLM companionship beside vendor services, data and file and code vectoring, temporal and knowledge graphs over the recorded history, and continual improvements to user utility. Sessions Kaizen did not drive are caught up by observation into the same records so Kaizen can take over to drive the session through a third party harness, in the same manner as a human.
I trained in judo from 1989 to 1996. Something that stayed with me was the idea of kaizen. Continual, incremental self-improvement.
I set out to build Kaizen as an anti-slop harness for people like me who aren't formally trained coders or engineers. The goal is to put deterministic checks and balances around inference generated code and make it easier for more people to build reliable, maintainable software.
SAVMI is:
write the specification, and beat this step to absolute death with your main agents and other humans. This includes establishing documents that shape how your project(s) should be developed by your agents and humans. For this project see the docs folder for Architecture, Design, and Methods defining documents. These documents are the guiding light of your whole project(s).
"Empty your mind. Be formless, shapeless, like water. Now you put water into a cup, it becomes the cup. You put water into a bottle, it becomes the bottle. You put it in a teapot, it becomes the teapot. Now water can flow, or it can crash. Be water, my friend."
Bruce Lee
To just execute the SCOPE is not sufficient here, being flexible WHILE you execute is critical to getting a job done. There's more than one "right" way to get a job done within bounded constraints. Continually look for opportunities to do a better job at execution based on the previous SCOPE step. That is what ADAPT is about.
Mental ZERO trust, micro-managing people is not a good look, but AI agents are not people with emotions (yet) and you can not trust them to do their given jobs correctly for a number of reasons you can go down a rabbit hole for hours about. So every single step needs deterministic verification if possible, and human intervention where practical. VERIFY is a critical step to stop the slop from getting out into the world.
This is a big one and missing from a lot of videos on the topic of "agentic frameworks". No one bothers to really dive into how you MANAGE your data and the pipelines. Imagine if you were running a business where every second you have multiple pages worth of dense writing of important information you need to track, just slapped onto your desk. And every second that goes by that continues to pile up faster than you can understand what is on the page let alone having time to file them away or retrieving what you need later. I don't know about you but I like neat and tidy even when there is absolute chaos unfolding. There-in good MANAGEMENT comes to save the day. Instead of a bunch of messy condensed JSONL files (what OpenAI and Anthropic use today) recording what happens, I wanted everything database managed and user retrievable and the biggest part HUMAN readable and retrievable. Standard keyword searches are not enough for retrieving relevant things as the data storage grows, so I took a play out of the RAG buzzword and applied it to the database for finding similar structures indifferent to keywords. EG vector embedding and reranking. What about multiple machines working on the same project? Fleet management, done. Not quite to Kubernetes functionality yet but the sky is the limit if this project is liked enough to be contributed to. So, that's the MANAGEMENT layer and it is absolutely critical like the rest of the layers.
Here-in is Kaizen. Continual self-improvement. Just as the ADAPT layer demands flexibility, so does this looping layer of IMPROVE. Every sprint run or code pass, do a retrospective and see what could have been done better and if time permits do a SWOT analysis of the completed run. I started with an idea of using a LEARNING record, an observed problem with AI model performance, which would be promoted to a LEARNED record only after it is validated and traceable through sufficient research, and the proof added to the record, then finally to a GOTCHA record, preferably with human-in-the-loop for this final record stage because the issue category potentially shapes the environment and codebase to address it. A GOTCHA may name the plan that carries its fix; the tooling permits that and does not require it. But that in itself is insufficient and is a band-aid of the real problem of a lack of deterministic controls for agents. IMPROVE is more than just improve results, it's a whole retrospective framework layer on finding ways to improve and then start again with those ideas to be tested and proven useful or not.
- A deep multioperational CLI (
kaizen.py) over a local control plane on stdlibsqlite3in WAL mode: tasks, plans, blocker investigations, domain evidence, ingestion, traces, reports, private policy, all shared by every agent host you point at it. - A read-back layer for session continuity: harness status, policy context, lesson lineage, verification queries, score trends. This is what an agent reads at the start of a session instead of being told to remember.
- Optional Turso-backed vector shards for semantic search.
- Development and testing currently target Windows; core and platform run automatically in owner-triggered remote CI after a push, while slow remains manual. Linux and the VS Code extension remain in development and run only when explicitly selected.
- Optional backends, all off by default: llama.cpp, Ollama, ComfyUI, vLLM, sentence-transformers.
- Local and private by design. But can be adapted to server hosting across the whole SAVMI framework.
Current development target: Windows.
I am a problem solver by skill set, not a disciplined software developer. The architecture, the contracts and the methods I believe work; the starting implementation has been built with heavy agent assistance under those contracts, which is rather the point of the project. It is a large codebase for one person and there are areas that deserve a more experienced eye than mine, particularly the concurrency and recovery paths.
Contributions, review and criticism are genuinely welcome, especially from people who have run agent fleets and know where this sort of thing breaks. See the contributions document which defines the acceptable standards for PRs. Feel free to adopt this contributions file if you never made a contributions document on GitHub before. After being on the platform since 2013, this project was the first time I used one. Standards are good to have.
- Project Description
- Why
- The Kaizen Difference
- Where the name comes from
- What is in this Agent Kaizen?
- Where it stands
- Contents
- Reading Path
- The Kaizen System
- How The Repo Maps To The System
- What This Repo Provides
- Harness Daemon And VS Code Controller
- Why Not Just Built-In Agent Memory?
- Why AGPL
- Requirements
- Setup
- Testing
- Daily Workflow
- Your First Ten Minutes
- Complete Command Index
- Local Database And Backend
- Adopting Agent Kaizen In A Project
- Skills Store
- Agentgateway
- Optional Backends
- FAQ
- Public Repository Safety
- Contributing
- License
- New to the idea: read this intro, then
KAIZEN_SYSTEM.md. - Installing it: download and run the complete installer bundle for your platform from the repo's
setup/folder (see Setup below). - Using this repo with an agent: follow the setup instructions, then retrieve bounded context through
manage harness status. LocalAGENTS.mdandCLAUDE.mdfiles can be generated or adapted to the work at hand; they are Git ignored. Each defining document states the condition on which it loads. - Adapting the system elsewhere: use Adopting Agent Kaizen In A Project as the starting point.
A memorable mnemonic because every good and bad idea has one:
SAVMI = Scope -> Adapt -> Verify -> Manage -> Improve
| Layer | Job | Typical outputs |
|---|---|---|
| Scope | Understand intent and evidence | Iterative Spec, assumptions, acceptance criteria |
| Adapt | Change the system through bounds | Execution contracts, patches, scripts |
| Verify | Decide if the work can proceed | Go/no-go result, proof, findings |
| Manage | Preserve and govern work data | DB records, hashes, reports, policy context |
| Improve | Decide what to improve next | Retrospective, next-cycle priorities |
The master concept document is KAIZEN_SYSTEM.md. This README explains the repo that implements it.
| Surface | Role |
|---|---|
KAIZEN_SYSTEM.md |
Human-facing method; only KS-0 through KS-5 serve to models |
kaizen.py |
Deterministic write path for managed records |
db/ |
Local data plane: DB, backups |
evals/ |
Command stubs plus portable evidence and learning fixtures |
AGENTS.md, CLAUDE.md |
Local, Git-ignored host instructions adapted to the current work |
docs/BOOTSTRAP.md |
Template for the pair via manage bootstrap sync |
setup/ |
Install/bootstrap scripts and the agent manual SETUP.md |
.agents/skills, .claude/skills |
Junction surfaces to external skill packages |
kaizen_components/ |
The shared engine package behind kaizen.py |
tests/ |
Tests, verification, and acceptance sources |
kaizen_components/orchestration/ |
Supervisor, policy snapshots, adapters, and replay |
vscode_ext/ |
VS Code sidebar/popout controller over the local daemon |
The important split is simple:
Kaizen System = the method.
Kaizen harness = this repo's local implementation.
Kaizen DB = the durable record store for managed work data.
Markdown = public docs, command stubs, generated views, or exported reports.
flowchart LR
CC["Claude Code"] --> CLI["kaizen.py"]
CX["Codex"] --> CLI
CLI --> ENG["kaizen_components/ engine"]
ENG --> DB[("db/kaizen.db")]
DB -->|"read-back: harness status, rules, learned trace, evidence search"| NEXT["next session"]
Every agent host writes through one CLI into one database; the next session (whichever agent runs it) starts from records, not recollection.
- Shareable system documents for agentic coding workflows.
- A local data plane backed by a direct-file stdlib-
sqlite3database, with Turso vector shards alongside it. SQL go Brrrrrrrr - A single CLI entrypoint,
kaizen.py, for structured writes and reports. - Command families for tasks, plans, ledgers, blocker investigations, domain receipts, source locks, artifacts, IRL Review, anti-patterns, learning records, evidence ingestion, activity traces, and the improvement lab.
- Project and skill
evals/surfaces for command stubs and portable fixtures. - VS Code project-shape guidance for Codex, Claude Code, and similar coding agents.
- Deterministic scripts that move repetitive mechanics out of the model context window.
- A multi-turn supervisor conversation with durable event replay, immutable permission profiles, and exactly one successful finalization on explicit close.
- An in-tree, zero-runtime-dependency VS Code controller development foundation with normal editor-tab conversations, durable daemon replay, governed tools, Audit Output, and capability-gated workflow views; it is not release-ready for public use.
What this shows. How a command entered at kaizen.py reaches a record, and how the four long-lived process classes named by the architecture contract (the on-demand engine, the fleet plane, the per-corpus vector funnel, and the model backends) hang off that same tree. Read it top to bottom: boundary, entry, dispatch, the command families, the data plane.
flowchart TD
subgraph EDGE["Boundary - same four nodes as diagram 2"]
B_CLI["CLI read path - python kaizen.py family area verb --output_json"]
B_LOOP["Loopback JSON-Lines control channel"]
B_SPAWN["Process spawn - kaizen.py daemon run"]
B_STDIN["Stdin bridge - kaizen.py profile-store"]
end
subgraph ENTRY["Entry and dispatch"]
MAIN["savmi/entrypoint.py main - argv intercept"]
SAVMI["savmi/ - shared contract, parser, help, runner; scope/, adapt/, verify/, manage/, improve/ - family services"]
DCLI["orchestration/daemon_cli.py - run, status, control verbs"]
PSTORE["composer_profile_store.py, composer_profile_persistence/"]
CSNAP["capability_snapshot_bridge.py - stdin read of the persisted capability snapshot"]
end
subgraph OPS["Record operations - one box per record plane"]
RWORK["Work and lesson records - scope/adapt tasks, gotchas, learning"]
RQUAL["Evidence, policy, reports - improve blocker_eval, manage evidence/policy/document"]
RRUN["Run and session ledger"]
REVID["Evidence plane and improvement lab - manage intake, improve lab"]
RSKILL["Skill context - manage skills"]
RGEN["Generative runs"]
RAUDIT["Code audit - verify audit"]
RVECTOR["Code vectors - manage vector"]
RMODEL["Model plane - manage model"]
RDB["Database lifecycle and recovery - manage database"]
end
subgraph ENGINE["orchestration/ - the on-demand engine"]
SUP["supervisor_core.py, supervision/ - boot, control routing, children"]
LOOPSRV["loopback.py, loopback_transport/ - server and client"]
ADAPT["adapters/ - claude_cli, codex, local_llm"]
TGATE["tool_gateway.py, tool_gateway_operations/ - policy and approval chokepoint"]
IOPROTO["model_io_protocol.py, provider_io_protocol.py - in-memory model-I/O chunks and capture envelopes"]
WFLOW["workflow_service.py, workflow_contract.py, workflow_history.py"]
end
subgraph FLEETP["fleet/ - fleet and multi-machine plane"]
FREC["records.py, store.py, reducers.py - manage fleet"]
FHTTP["control_http.py - tailnet control service"]
FLEASE["coordination_leases/, coordination_store/"]
end
BACK["backends/ - ollama, openai_compat, transformers, sentence_transformers, cross_encoder, gliner_pii"]
subgraph DATA["Data plane"]
DBM["db.py, db_schema modules, database_lifecycle/, db_recovery/"]
KDB[("db/kaizen.db - control database")]
FDB[("db/fleet.db")]
VREG["vector_registry.py - corpus catalog rows"]
VSTORE["vector_store.py - the sole client seam to vector data"]
VFUN["vector_funnel.py - one funnel process per corpus"]
VSHARD[("db/vectors/ - per-corpus shard")]
end
FOUND["Foundations - paths, denials, hashing, redaction, schemas/, output, db_retry"]
B_CLI --> MAIN
B_STDIN --> MAIN
B_SPAWN --> DCLI
B_LOOP --> LOOPSRV
MAIN -->|"daemon"| DCLI
MAIN -->|"profile-store"| PSTORE
MAIN -->|"capability-snapshot"| CSNAP
MAIN --> SAVMI
DCLI --> SUP
DCLI -->|"status, steer, approve"| LOOPSRV
SAVMI --> RWORK
SAVMI --> RQUAL
SAVMI --> RRUN
SAVMI --> REVID
SAVMI --> RSKILL
SAVMI --> RGEN
SAVMI --> RAUDIT
SAVMI --> RVECTOR
SAVMI --> RMODEL
SAVMI --> RDB
SAVMI --> FREC
LOOPSRV --> SUP
SUP --> ADAPT
SUP --> IOPROTO
SUP --> WFLOW
SUP --> FREC
ADAPT --> TGATE
ADAPT --> BACK
ADAPT --> IOPROTO
FHTTP --> FREC
FLEASE --> FREC
FREC --> FDB
RWORK --> DBM
RQUAL --> DBM
RRUN --> DBM
CSNAP --> DBM
REVID --> DBM
RSKILL --> DBM
RGEN --> DBM
RAUDIT --> DBM
RMODEL --> DBM
RDB --> DBM
RVECTOR --> DBM
VREG --> DBM
DBM --> KDB
REVID --> BACK
RMODEL --> BACK
RVECTOR --> VSTORE
VSTORE --> VREG
VSTORE --> VFUN
VFUN --> VSHARD
VSTORE -.->|"reuses transport"| LOOPSRV
VFUN -.->|"reuses transport"| LOOPSRV
SAVMI -.-> FOUND
SUP -.-> FOUND
DBM -.-> FOUND
| Box | Modules |
|---|---|
| Work and lesson records | plan_aggregate_records.py, plan_owned_task_records.py, task_records.py; CLI workflows in scope/, adapt/, verify/, and manage/ |
| Quality, policy, reports | blocker_evaluations.py, verification_receipts.py, artifact_records.py, policy_records.py, verify/contract_lint.py, manage/reports.py |
| Run and session ledger | session_record_store/, session_turn_records.py, session_message_records.py, session_conversation_support.py, model_execution_records.py |
| Zero-process capability read | orchestration/session_reads.py + orchestration/session_read_model/ |
| Evidence plane and improvement lab | manage/content_store_records.py, intake_records.py, improve/lab.py, dedup.py |
| Skill context | skill_context.py + skill_context_management/ |
| Generative runs | comfyui.py, comfy_runtime.py, comfy_mcp.py, comfyui_workflows/ |
| Code audit | verify/code_line_audit.py facade over verify/code_audit/ and the verify/code_line_audit_* modules |
| Code vectors | code_vectors/ |
| Model plane | model_ops.py, model_monitor.py, verify/pii_scan.py, backend_registry.py, model_catalog.py |
| Database lifecycle and recovery | db.py, database_lifecycle/, db_recovery/ |
It omits most of the 673 Python modules under kaizen_components/. orchestration/ alone holds 181 of them and appears as six boxes; fleet/ holds 26 and appears as three.
It omits the repository's pervasive facade / support / fragment-package pattern, because showing it once per component would triple the node count without changing the shape. The pattern is: X.py is the public facade, X_support.py holds shared primitives, and X_store/, X_management/, or X_operations/ holds bounded implementation fragments that the facade re-exports. Seen in skill_context.py:37, composer_profile_store.py:62, db.py:41, loopback.py:43, and tool_gateway.py:5-8.
It omits the foundation edges. paths, denials, hashing, redaction, schemas/, output, and db_retry are imported by almost every box; three dotted edges stand for what is really more than a hundred.
It omits control flow inside a turn (the adapter event stream, the reducer snapshot cadence, retry and lease behaviour), and it omits every test module, setup/, and evals/.
It omits process lifetime. A box is a component, not a process. Only four boxes ever become their own OS process: the supervisor engine, the fleet daemon behind control_http.py, one vector_funnel.py per corpus, and a short-lived kaizen.py CLI invocation.
The controller development foundation is in vscode_ext/. It remains under active development, is not release-ready for public use, and runs in GitHub Actions only through an explicit manual development selection. Each editor-tab conversation has its own controller while the daemon remains authoritative for transcript and policy state. Closing a renderer does not stop its daemon run, and reopening receives a complete snapshot rebuilt from durable events. The sidebar remains the approvals, sessions/timeline, and fleet/engines navigator rather than a second chat surface.
Exact model input, output, callback, control, and user-revision payloads are stored unencrypted in plaintext BLOBs in the local Kaizen database before the next Kaizen-controlled boundary. Those rows may contain prompts, responses, tool requests, and tool results, so keep db/kaizen.db private and protect it like source-bearing session data. The model-I/O store does not hold vendor credentials, does not parse vendor authentication files, and does not substitute redacted bytes for bytes sent to a provider.
The conversation lifecycle is deliberately longer than one model turn:
open -> running -> idle -> running -> ... -> explicit close -> terminal
One session and one run remain open across turns. Complete redacted user and final assistant messages are written as chat_message/point events. A successful finalization is written only by session/close; kill, fatal errors, shutdown, and orphan recovery write a non-success finalization. The UI persists only session_id, agent_run_id, and profile_hash, never transcript text, API keys, approval secrets, or Full-mode confirmation.
The equivalent CLI surface is scriptable:
python kaizen.py daemon session capabilities --output_json
python kaizen.py daemon session start --engine local_llm --prompt "First turn" --permission-mode plan --output_json
python kaizen.py daemon session turn --run <agent_run_id> --prompt "Second turn" --output_json
python kaizen.py daemon session close --run <agent_run_id> --output_json
Engine selectors come from session/capabilities; claude_cli is normalized to the public claude ID. An engine remains visible but non-drivable when the installed vendor version cannot enforce the requested permission boundary. There is no silent downgrade: unsupported profiles return structured denials. Claude runs through the installed Claude Code command line or extension under its own subscription login. The UI never accepts credential text, Kaizen never reads vendor credential files, and there is no Claude API-key fallback.
Claude requires an explicit model alias from the catalog the installed Claude Code advertises, and the Claude transport refuses a reasoning effort selection. A removed model fails before a provider call while preserving the complete composer envelope.
The installed extension uses its normal editor tabs and starts the daemon only through a visible user-stoppable terminal. Exact /workflows opens a same-tab workflow view without sending that composer text to Claude; ordinary prose containing the token remains ordinary chat. Workflow launch, status, Stop, pause, resume, restart, save, rerun, script editing, external discovery, and private transcript scanning each have an independent capability result. A route appears authoritative only after its exact bounded proof succeeds; unsupported or unproven routes remain visible with their reason, and external discovery remains read-only observation rather than Kaizen-owned state.
No surviving engine exposes the workflow boundary, so workflow launch, status, Stop, Restart, Pause, Resume, Rerun, save, edit, external discovery, and private transcript scanning each report unavailable with their reason. They remain visibly unavailable and are never relabeled or synthesized.
The controller is an application-layer mediation system. Vendor sandboxes and supported approval channels are the enforcement backbone. Genuine OS/user/container isolation, hostile native programs, computed-path escapes, and kernel-level containment belong to a later isolation layer.
Existing-target proposal modify, delete, and rename operations use the verified bounded crash-recovery path on Windows. A platform without equivalent proven primitives denies those operations before mutation; retained recovery artifacts support exact restart reconciliation, not filesystem transactionality, rollback, or broad OS containment.
Because memory and evidence are different problems. First-party agent memory (auto-generated notes, insights, per-project memory files) is good at carrying preferences and context between sessions, and Agent Kaizen does not compete with it. What it does not carry is anything you can audit: whether a claim was verified, by what command, with what result; what the agent predicted before the work versus what actually happened; which recorded "lessons" were ever validated before being treated as fact.
Agent Kaizen keeps those as structured records in one local database:
- Blocker investigations (
improve blocker_eval) preserve observations, findings, limitations, and exact subject/evidence hashes. Resolving a terminal failure separately binds an investigation to the current blocker occurrence. Domain receipts belong to delegation, source conformance, or research;manage evidenceretrieves retained evidence. - A gated AI model performance issue lesson path: a problem with AI model performance enters as a LEARNING (
adapt learning create) with write-once evidence; sufficient research promotes it to LEARNED (verify learned create) with proofs added to the record; and a GOTCHA is created or revised preferably only with the project owner's explicit permission,manage gotcha createandmanage gotcha revise. The lineage reads back withverify learned trace. Problems in the codebase are a separate track:adapt blockerrecords what stops work in the codebase and never enters the lesson pipeline. - IRL Review records that pair predictions with observed outcomes (
improve irl, work in progress), so calibration is measurable instead of anecdotal. - Individual rule and definition drafts with exact revisions in the database. Approved machine instructions live in git-ignored
user/files/machine_rules/and load only for Kaizen-driven local-model sessions. - One database and one CLI for every agent host you use: records written in a Claude Code session are read back in a Codex session, and vice versa.
| Built-in agent memory | Rules & instruction files | Agent Kaizen | |
|---|---|---|---|
| What it carries | Preferences, context notes | Standing guidance | Structured work records |
| Verified or asserted | Asserted by the agent | Asserted by the author | Verification conclusions with evidence |
| Queryable later | Rarely | No (static text) | SQL-backed queries and reports |
| Across agent hosts | Per-product silos | Per-file copies | One DB, one CLI, every host |
| Lessons | Auto-noted, unvalidated | Hand-curated | Gated promotion with full lineage |
Built-in memory is a fine consumer of these records: the harness status (manage harness status) is one small JSON payload designed to be read at session start by any agent. The records themselves need a deterministic write path, schema validation, and redaction gates, which is what this harness is.
This project is AGPL-3.0 on purpose. The license exists to help individuals and small teams, not major corporations that take open source work, wall it off behind a service, and give nothing back. That violates the spirit of open source, and the AGPL is the license that says so with teeth. If you improve this harness and offer it to others, those improvements stay open for everyone.
What it means for you in practice:
- Using Agent Kaizen to manage your projects does not make your projects AGPL. The license covers this harness's code, not your code, not your records. Your DB is yours.
- Clone it, adapt it, link the engine into private repos: all fine.
- The share-back obligation triggers only if you distribute a modified harness or run it as a service for others.
This is a plain-language summary, not legal advice. See LICENSE for the actual terms.
- Windows 10+ with PowerShell 5.1+ is the current development target. The POSIX setup path remains available for Linux/macOS development evaluation.
- Python 3.12 or newer with
venvsupport (the installers can install it for you). 3.12 is the CI-tested baseline; the installers require at least 3.12. - git 2.20+.
- ~2 GB free RAM for the core harness; a single GPU with 12 GB VRAM for the existing optional PyTorch/Ollama backends, or 16 GB VRAM for the quality-first unquantized Qwen3 code-vector profile.
Setup language
Native setup can display English or neutral South American Spanish before Python is installed. Pass -LanguagePack spanish or -Idioma spanish to PowerShell scripts and Install-Agent-Kaizen.cmd; pass --language-pack spanish or --idioma spanish to Bash scripts. SetDevRoot.cmd uses /language-pack spanish or /idioma spanish. Selection applies to that invocation: an explicit selector wins over the child-process AK_LANGUAGE_PACK value, then the default is english. This does not change the harness language in configuration.toml.
Keep the complete setup/ bundle together, including installer-language.ps1, installer-language.sh, installer-language.cmd, the platform helper folders, and languages/. Every language has the same topic keys. PowerShell and Bash read UTF-8 TSV packs; CMD uses one generated subset binding per language. English option spellings remain accepted. -Help / -Ayuda, --help / --ayuda, and SetDevRoot /help / /ayuda display help without installation effects.
setup\Install-Agent-Kaizen.cmd -Idioma spanish -Ayuda
setup\Install-Agent-Kaizen.cmd X:\dev -Idioma spanish -ListarPasos -SinPausa
setup\SetDevRoot.cmd /idioma spanish /ayudabash setup/install-agent-kaizen.sh --idioma spanish --ayuda
bash setup/install-agent-kaizen.sh "$HOME/dev" --idioma spanish --listar-pasosThe small CMD forwarder uses bilingual bootstrap diagnostics before PowerShell binds its arguments; it forwards the original arguments unchanged. Missing or invalid language data also has a bilingual recovery message. Host execution-policy restrictions remain in force. JSON plans, stored step/status/reason values, paths, hashes, private arguments, and upstream diagnostics retain their canonical identities. Confirmation defaults and no-input/assume-yes rules are unchanged. Language support does not establish installation validation on another platform.
For Windows development setup, download the setup bundle and run it. The Linux/macOS launcher remains available for explicit development evaluation. On a bare Windows machine the installer provisions DEVROOT-managed Git, GitHub CLI (gh), and Python by default, clones this repo, builds the shared venv, generates the VS Code workspace and launcher, scaffolds an empty sibling skills store, and initializes the local DB. Everything lives under a parent folder you choose, called DEVROOT:
DEVROOT/
|-- agent-kaizen/ the cloned repo
|-- Git/ managed PortableGit (default)
|-- GitHubCLI/ managed gh (default; independently selectable)
|-- SKILLS/ sibling skills store (empty by default)
`-- Python/
|-- Python312/ managed Python
`-- venvs/kaizen/ shared Python venv
Windows: download or clone the repository so the complete setup/ bundle remains together, then run Install-Agent-Kaizen.cmd. It always opens a dedicated, clearly titled elevated Windows PowerShell 5.1 window for an interactive install (approve the UAC prompt, because admin is needed to bootstrap winget/App Installer and an optional build toolchain). The defaults are hash-pinned PortableGit under DEVROOT\Git, hash-pinned gh under DEVROOT\GitHubCLI, and Python under DEVROOT\Python; detected system tools and GitHub Desktop are not silently selected. The PowerShell window explains each ownership choice before asking:
curl.exe -L -o agent-kaizen-main.zip https://github.com/LevyBytes/agent-kaizen/archive/refs/heads/main.zip
Expand-Archive .\agent-kaizen-main.zip -DestinationPath .
.\agent-kaizen-main\setup\Install-Agent-Kaizen.cmd X:\devA downloaded archive carries the "mark of the web", so SmartScreen may warn the first time. Choose More info → Run anyway or unblock the archive before extracting it.
The vector-shard engine ships as the pyturso distribution, which Agent Kaizen imports as turso; it is a required core dependency. A compatible prebuilt Windows wheel is the no-local-Rust route (drop it in DEVROOT\wheels or pass -PyTursoWheelUrl together with its required -PyTursoWheelSha256). Without one, pip compiles pyturso from source and needs Rust + Visual Studio Build Tools (a multi-GB download); .NET / CMake / Node.js / VS Code remain separate optional tools. See setup/SETUP.md for details.
Linux / macOS development path (in development, not a supported release claim): download and extract the complete repository archive, then run its setup/install-agent-kaizen.sh entry point (it installs git + Python 3 via your system package manager: apt/dnf/yum/pacman/zypper, or Homebrew on macOS; sudo where needed):
bash agent-kaizen-main/setup/install-agent-kaizen.sh "$HOME/dev"Warm reruns validate exact managed tools and dependencies before skipping work, but a failed run may already have applied earlier validated changes; review the repository's setup\state\setup-state.json and the logs in setup\logs before rerunning. Windows uses its hash-pinned PortableGit fallback when winget is unavailable and downloads managed Python from python.org; it does not silently switch to a detected system Git. An existing valid repository is reused without fetching by default (-UpdateExisting opts into fetch plus fast-forward). On Linux/macOS run bash setup/setup.sh [DEVROOT]; on Windows run setup\Install-Agent-Kaizen.cmd.
Try it in Windows Sandbox first (optional). A generic template is included at tests/windows-sandbox-template.wsb. Launch it to test the installer in a throwaway VM. The one thing a fresh Windows 11 sandbox needs is Smart App Control disabled, which the template's logon script does automatically (SAC Enforce otherwise blocks the per-user Python install). Keep any folder mappings minimal.
Installer planning and diagnostics:
.\Install-Agent-Kaizen.cmd X:\dev -ListSteps -NoPause
.\Install-Agent-Kaizen.cmd X:\dev -PlanOnly -NoNetwork -NoExternalActions -NoUserEnvWrites -EmitPlanJson X:\dev\agent-kaizen\setup\state\installer-plan.json -NoPause
.\Install-Agent-Kaizen.cmd X:\dev -SelfTest -NoNetwork -NoExternalActions -NoUserEnvWrites -NoPausebash install-agent-kaizen.sh "$HOME/dev" --list-steps
bash install-agent-kaizen.sh "$HOME/dev" --plan-only --no-network --no-external-actions --no-user-env-writes --emit-plan-json "$HOME/dev/agent-kaizen/setup/state/installer-plan.json"
bash install-agent-kaizen.sh "$HOME/dev" --self-test --no-network --no-external-actions --no-user-env-writes --no-inputThe installer entry points also accept -RepoSource / --repo-source for local-source testing, -Ref / --ref to pin a tag or branch, -NoPrompt / --no-input for deterministic non-interactive runs, and -AssumeYes / --assume-yes for explicit non-interactive acceptance. Duplicate apply on either platform requires interactive confirmation or that explicit assume-yes flag; no-input/no-prompt alone does not authorize mutation. A duplicated project chooses extension link or copy ownership with Windows -ExtensionMode or POSIX --extension-mode; copy mode additionally requires a unique publisher.name and display name through -ExtensionId / -ExtensionDisplayName or --extension-id / --extension-display-name. They write progress logs and setup state under the repository's git-ignored setup/logs/ and setup/state/ folders. Long native commands write individual command logs under setup/logs/; downloads show byte counts, percent, throughput, and ETA when the server publishes a total size. Package managers that hide totals still show elapsed time and recent output.
The extension takes its Kaizen root from the open workspace when that workspace is a fully seeded Kaizen root, otherwise from the KAIZEN environment variable, otherwise from the Agent Kaizen installation that Kaizen: Select Master Project saves in the machine-scoped user setting kaizen.masterProject, which must lie inside DEVROOT; each candidate must hold the Kaizen sentinel files. The resulting kaizenRoot owns kaizen.py, Python selection, the database, runtime, protocol, and visible daemon terminal, while the immutable activation workspaceRoot remains authoritative for source, context, diffs, process working directory, and workspace policy. Daemon capabilities must attest that exact root and every successful start must echo it; missing or mismatched proof leaves the complete composer envelope retryable and binds no conversation. One master daemon is bound to one configured workspace at a time; after switching to another governed workspace, stop the old visible daemon and start it for the new root.
Duplicate plan-only output classifies the project as ABSENT, MANAGED, or FOREIGN, reports extension state, and names the exact create/no-op/convert/deny action with zero DEVROOT mutation unless a plan-JSON path is explicitly requested. Source discovery prefers the explicitly named project, otherwise accepts one eligible renamed direct child including a dot-prefixed child, and denies ambiguity. A matching managed rerun preserves copied docs/setup, wrapper, DB, skills, workspace, extension customization, and any retained recovery link. Link-to-copy stages, filters, rewrites, and verifies a sibling copy, exclusively renames the active master link to a random sibling quarantine, verifies the moved object, and only then commits the copy; an occupied destination preserves both the racer and quarantine and reports RECOVERY REQUIRED. A successful conversion retains exactly one dot-prefixed inactive .vscode_ext.ak-link-* exact-master recovery link and prints its path; warm NOOP_COPY creates no additional artifact. Portable handle-bound deletion is unavailable across supported installer paths, so cleanup is an explicit owner-controlled filesystem action instead of an automatic pathname deletion that could race. Copy-to-link is denied. Copy IDs and display names must differ from the master and every valid visible or dot-prefixed direct-child DEVROOT/<project>/vscode_ext/package.json; a present manifest in an enumerated direct-child project fails closed when malformed, unreadable, or colliding, and foreign/reparse target topology also fails closed. The installer does not inspect or write VS Code profiles, so validate the copied publisher.name when installing its VSIX because an identical installed ID is replaced rather than installed beside itself.
Windows Sandbox guidance: pass an explicit writable DEVROOT and keep the installer source mapping read-only if desired. The Windows installer resolves DEVROOT before tool bootstrap, logs under that root, attempts App Installer registration, tries Microsoft.WinGet.Client repair, then falls back to direct App Installer package download. If App Installer was installed but the current terminal still cannot invoke winget.exe, close that setup window, open a fresh terminal or restart the sandbox session, and rerun the same command.
Pin to a reviewed tag (when available). By default the installer tracks the tip of main. To install and stay on a specific reviewed tag, pass it explicitly: on Linux/macOS AK_REF=<tag> bash install-agent-kaizen.sh, on Windows .\Install-Agent-Kaizen.cmd -Ref <tag>. Re-runs then check out that tag. Already cloned? Run git checkout <tag> in the repo, then re-run setup/setup.sh.
Skills ship empty; add a store of your own with setup/link-skills.ps1 or setup/link-skills.sh. Machine instructions also start empty. Use kaizen.py manage rules create --scope machine to save an individual draft, manage rules return --scope machine to review its exact revision, and manage rules edit --scope machine --apply to apply the Scope-approved selection. The default file is user/files/machine_rules/machine_rules.md.
This repo is developed on Windows and PowerShell, but the core Python commands are ordinary Python and can be adapted to other shells.
Prerequisites:
- Python 3.12 or newer with
venvsupport. - A VS Code checkout of this repository.
The installer uses a shared venv at $DEVROOT/Python/venvs/kaizen; the manual steps below use a repo-local .venv fallback, which works the same way.
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-kaizen.txt
.\.venv\Scripts\python.exe kaizen.py manage database reconcile --output_json
.\.venv\Scripts\python.exe kaizen.py --helppython3 -m venv .venv
./.venv/bin/python -m pip install -r requirements-kaizen.txt
./.venv/bin/python kaizen.py manage database reconcile --output_json
./.venv/bin/python kaizen.py --helpmanage database reconcile checks or initializes the DB. --help shows the current command surface.
Default local DB shape:
db/
|-- kaizen.db
|-- fleet.db
|-- vectors/
`-- backups/
For public repositories, keep db/ and user/reports/ contents private/local unless a report has been deliberately sanitized.
work/ contains deterministic allocated work and test runs. runtime/ holds engine-wide process state, the state of the one installation that serves every project, such as the managed ComfyUI server's state and the database explorer's preferences. It also holds Kaizen's own project process state, such as its supervisor daemon's control files and its vector funnels, because Kaizen's data root is the tool root. Another project's process state lives in the runtime/ folder of its data root, $DEVROOT/PROJECTS/Kaizen_<project folder name>/runtime/. Neither runtime folder is an agent-designated work root. The repository's evals/, generation/, lint/, runtime/, user/, and work/ folders each retain only a tracked top-level .gitignore file; all other contents are ignored by Git.
Markdown in this repo is formatted with Prettier settings proseWrap: never and printWidth: 100 (the config is kept local, not shipped). Prettier is optional but recommended: it is not a required gate (no CI enforcement, and you do not need it to use the harness), but if it is available it keeps docs consistently formatted.
npx prettier --check path/to/file.md # report formatting drift
npx prettier --write path/to/file.md # apply formattingThe harness ships with a standard-library unittest suite under tests/. The runner allocates one run root under work/, routes temp directories and caches beneath it, runs the selection in a child process, and removes the root when the run ends. Control-record tests build test_ tables in an in-memory database, and shard and file tests write only under the run root or under a timestamped work/ directory they remove. The no-argument runner is the core lane of control-record and unit modules; the platform lane runs the vector shard and transcript modules. Run the wrapper with the shared Kaizen venv:
& "$env:DEVROOT\Python\venvs\kaizen\Scripts\python.exe" tests/run_tests.py"$DEVROOT/Python/venvs/kaizen/bin/python" tests/run_tests.pyUse tests/run_tests.py --list-lanes to see each lane's module count, --lane platform after filesystem, shard or transcript changes, and one raw selector such as tests/run_tests.py tests.records.test_answers for a single module. See tests/records/README.md for the control-record conventions.
Run tests/lane_probe.py with the same interpreter beside a test run to follow it: the probe prints a line when the run starts, at every further 5 percent of its tests, at each new failure or error, and when the run ends.
For substantial work have your agent:
-
Check or initialize the DB, then load the harness status (what needs attention: doctrine drift, an unrecorded configuration, the ready programs, the active GOTCHAs, and the policies in force; it is the read-back half of Manage):
python kaizen.py manage database reconcile --output_json python kaizen.py manage harness status --output_json
-
Scope the task with evidence, assumptions, boundaries, and acceptance criteria. Agent should ask the user many questions until the scope layer is fully defined and free of any ambiguity.
-
Adapt through bounded changes and deterministic scripts where practical.
-
Verify with ground truth first, then structured review where judgment is needed.
-
Manage records, artifacts, hashes, evidence, source locks, and reports through the CLI.
-
Improve by promoting useful lessons through LEARNING, LEARNED, and GOTCHA into lab cases, docs, or scripts; pull them back with
verify learned trace(lessons + source chain). Useimprove lab_casefor lab inputs,improve blocker_evalfor codebase blocker investigations, andmanage evidencefor retained evidence.
Before a major task or after a compacted conversation, reload the harness status with manage harness status.
Plans and research require at least one published rule or definition in doctrine_ids. Publish the project's doctrine first, then find the IDs relevant to the work; this repository's example uses KAI-120.
A copy-paste session that ends with the payoff: the harness status your next session starts from. Effect verbs take a JSON --input_json; copy returned IDs into later request files where placeholder tokens appear. Each # name.json: comment is the file the next command reads; PLAN_ID and PLAN_REVISION_ID stand for the id and revision_id the plan create returns, and TASK_ID for the id the task create returns.
python kaizen.py manage database reconcile --output_json
python kaizen.py manage rules search --query "scope" --output_json
# plan.json: {"title": "README polish", "doctrine_ids": ["KAI-120"], "summary": "Make the README a stronger public entry point.", "body": "Rewrite the README sections that drifted from the command index."}
python kaizen.py scope plan create --input_json plan.json --output_json
# task.json: {"plan_id": "PLAN_ID", "expected_plan_revision_id": "PLAN_REVISION_ID", "title": "README polish", "summary": "Rewrite the README as a stronger public entry point."}
python kaizen.py scope task create --input_json task.json --output_json
python kaizen.py manage cli commands --check --output_json
python kaizen.py manage database schema --check --output_json
# learning.json: {"title": "README command drift", "summary": "Command tables can drift from the generated index.", "body": "The README command tables are rendered from the command map, so an edit to one without the other drifts."}
python kaizen.py adapt learning create --input_json learning.json --output_json
python kaizen.py manage harness status --output_jsonThat final manage harness status is the harness status a fresh session starts from: doctrine drift and one count per record kind, the counts at zero included, because nothing waiting is itself worth knowing.
{
"status": "OK",
"doctrine_drift": ["docs/KAIZEN_planning.md"],
"goals_ready": 0,
"programs_ready": 1,
"plans_ready": 2,
"learning_issues": 0,
"learned_issues": 0,
"gotcha_issues": 1,
"open_blockers": 0,
"help": "use --help for more info"
}doctrine_drift names the defining documents whose hash moved since the last sync, and reads unsynced when no sync has ever run. The six counts are the records waiting on you, and open_blockers the blockers still open. A section flag such as --plans or --blockers expands that section's count into the ids and titles behind it, which is what help points at.
The steps: initialize the DB and load the framework layers, create a plan and a task under it, record a verification result against the task (a go/no-go conclusion plus what was checked), then record a problem you hit along the way as a LEARNING. manage harness status is the payoff: one small JSON payload naming what is waiting, which is what a fresh session, or a different agent, starts from.
For JSON-heavy payloads, keep the request in a file and pass it with --input_json.
The generated command reference starts at docs/CLI/CLI_KAIZEN.md and continues through family pages to area folders, each containing an area index and one complete page per verb; the operational-flags and file-safety contract lives in docs/KAIZEN_governance.md. Run python kaizen.py --help for current arguments and examples.
The control database db/kaizen.db is a direct local stdlib-sqlite3 file in WAL journal mode. Vector data lives apart, in per-corpus Turso (pyturso) shard files under db/vectors/, each opened only by its own funnel daemon.
The implementation uses local DB files, WAL journal mode (many readers, one serialized writer), bounded retry behavior, app-generated IDs, and SHA-256 hashes for entries and artifacts where practical. The concept is backend-agnostic: another project can use a different database or remote service as long as records stay structured, queryable, and written through deterministic paths.
Authored-code audit. verify audit lint deterministically enforces the code-file size, purpose-naming, and path bounds without loading a model, stores normalized directory, file, and last-complete finding identities without copying source text into the database, pinning each finding to its line number and that line's content hash, and exits nonzero for a MUST violation. Its optional independently operated reviewer, a chat model served by the llama_cpp, ollama or vllm runtime configuration.toml selects, is advisory and checks only whether changed code filenames match their purpose.
Semantic code search. manage vector owns code-vector profiles, capacity, generation, promotion, reranking, search, shard/funnel state, and vector warnings over the code audit's content-hashed inventory. Its quality-first profile casts the full 4,096-dimensional embedding to Float32 before normalization and stores one 16 KiB vector for every eligible whole file and every syntactic chunk inside it, a chunk being one function, one class, or one run of module-level statements. One million embedded chunks require 15.259 GiB of raw vector payload before database overhead; the vector surface reports the exact current repository count and a calibrated growth projection before owner-gated generation. Token count affects generation cost and whole-file context eligibility, not the fixed vector size.
The default models are unquantized Qwen3-Embedding-8B and query-time Qwen3-Reranker-8B. Each checkpoint retains its declared native weight dtype; cache and offload are disabled, embedding normalization/output/storage is Float32, and reranker yes/no logits cross to Float32 before softmax. They run sequentially rather than concurrently. The full-context profile requires bounded-memory cuDNN attention and refuses quadratic fallback; on the reference RTX 5090, an exact 32,768-token embedding used 17,786 MiB peak allocated and 19,020 MiB peak reserved GPU memory. The pinned reranker completed an exact 32,768-token prompt in 4.197 seconds first-run and 4.033 seconds repeated at 18,971 MiB peak allocated and 20,192 MiB peak reserved; its repeated 128-candidate pass took 1.736 seconds after a 10.289-second process-cold load. Reranking stores no vectors of its own and no persistent relevance scores. Forced-FP32 weights or RAM offload require a separate explicitly selected hardware-benchmarked profile. A limitation is that an extremely long function may place its signature outside the bounded window. The benchmark evidence, measured storage table, fixture-language limits, and compact-vector tradeoffs are documented in docs/research/qwen3-code-line-vector-benchmark.md.
Text search. Record and report queries (the family search verbs) use escaped substring LIKE as the always-available baseline: wildcards in a query are escaped so a literal % or _ matches literally, and results are bounded by each query's --limit. This is a scan, which is fine at per-project record scale. An FTS-backed record index is not implemented: escaped-substring LIKE is the only lexical path. Configuring an embedding backend does not build an index; vector generation is a separate, owner-gated manage vector action.
You can use this repo in two ways.
Work inside this repository, keep the local DB private, and use kaizen.py to manage tasks, blocker investigations, domain evidence, learning records, reports, and policy context.
Any project can use the one Kaizen installation without copying or linking anything into it. Keep the project as an ordinary folder in DEVROOT, such as $DEVROOT/my_app, and run this once from inside it:
python "$env:KAIZEN\kaizen.py" manage projects initialize --output_jsonpython "$KAIZEN/kaizen.py" manage projects initialize --output_jsonThat makes the project's Kaizen folder, $DEVROOT/PROJECTS/Kaizen_<project folder name>, with the project's databases, its work/ folder, its documents under docs/, and the Claude Code and Codex settings for its sessions (command reference).
That folder also holds _workspace/project.code-workspace and open_<project folder name>_vscode.cmd. On Windows, open the launcher to show the Kaizen data folder and the application source folder together in VS Code. New workspaces inherit terminal profiles, Python configuration, and editor settings from $KAIZEN/_workspace/agent-kaizen-tools.code-workspace when present, with folder references adapted for the project. Developer PowerShell uses the shared tools and Python environment and starts in the project's Kaizen data folder. Initialization creates missing editor files and preserves existing customizations.
From then on every kaizen.py command selects the project from the folder it runs in: run it from the project folder or from its Kaizen folder and it reads and writes that project's records, while a command run inside the Kaizen repository works for Kaizen itself. Open Claude Code and Codex sessions in the Kaizen folder. Their settings name the project folder as an additional directory, so the agent edits the code there while every record, plan, report, and scratch file stays in the Kaizen folder. Kaizen writes nothing in the project folder, so the project's repository carries no trace of Kaizen. If you rename the project folder, the next command run from it renames the Kaizen folder to match and updates both settings files, the workspace folder references, and the launcher name.
KAIZEN must name the Kaizen installation and DEVROOT the folder that holds your projects. A command run from a project with either one unset is refused, and so is a command run from a folder outside both.
Skills are maintained in an external store. .agents/skills and .claude/skills remain optional host-native surfaces, while manage skills provides project-scoped discovery, validation, and reconciliation.
A project consumes a skill only through its folder link under .agents/skills or .claude/skills, and no leaf places a skill's prose into model context. manage skills search reports each store skill's package hashes and link state without writing, and verify skill check uses current only for snapshot, inventory, and surface freshness and reports validation and publication health separately. Before bootstrap verify skill check reports no applied snapshot; an existing database picks this additive update up on the next ordinary manage database reconcile, which applies the declared objects and reconciles the stored manifest inside the same transaction. Missing, invalid, stale, and integrity-failed packages fail closed.
| Axis | Values | Meaning |
|---|---|---|
| Publication | published, staged |
published means a configured package Git remote validates as GitHub; otherwise the package is staged. This classification uses local configuration and does not publish or fetch anything. |
| Host surface | correct or a portable failure state |
Validates the selected host's link independently of publication; examples include missing, dangling_link, wrong_target, and real_directory. |
A staged package is not automatically disabled. It may remain locally usable when its package is valid and current and its selected-host surface is correct. No inventory, synchronization, query, or status operation automatically publishes a repository, creates a link, or enables a skill.
Python tooling remains authoritative for packages, Git-remote classification, links, and indexes. The control database stores portable routing metadata, validation observations, synchronization history, and lifecycle events; it does not publish repositories, install packages, create links, or change host settings. Every apply operation recomputes its plan and requires the matching plan_sha256 in the confirm_plan field.
Edit the canonical skill store, not a duplicate mirror. Every skill should have an evals/ surface for command stubs and behavioral eval fixtures.
Agentgateway is not required for the local single-user harness. It becomes useful later when a project needs centralized identity, RBAC, remote MCP/tool federation, model routing, budgets, rate limits, failover, or auditable traces across multiple agents, users, services, or machines.
The Kaizen DB includes compatible event storage so gateway integration can be added later without changing the core record model.
The core harness is dependency-light and complete on its own: everything above works with nothing but Python and the pinned requirements. Three optional backends extend it, and each one stays entirely off until you install or point at it:
- Ollama: connects any local or remote OpenAI-compatible model server. A text model drives the engine's local-LLM adapter and the advisory LLM-as-judge of
improve lab run, which judges a lab contract's proposals against its lab cases (a signal, never a gate). Enable withKAIZEN_LLM_MODEL/KAIZEN_EMBED_MODELand their base URLs; setup insetup/OLLAMA.md. - ComfyUI: turns generative image and node-graph workflows into managed records. The agent authors the ComfyUI prompt graph,
manage workflow registerstores it with its hash,manage workflow reconcilevalidates every registered graph against the live server's node and asset inventory, andmanage runtime start/manage runtime stoprun the local server. Setup insetup/COMFYUI.md. - PyTorch (
requirements-pytorch.txt): in-process, GPU-first extras, all opt-in and advisory. They aresentence-transformersembeddings (KAIZEN_EMBED_BACKEND=sentence-transformers; the defaultF2LLM-v2-1.7Bis instruction-tuned and was chosen on a measured retrieval A-B; seedocs/EMBEDDING_BENCHMARK.md); a cross-encoder reranker (KAIZEN_RERANK_BACKEND); a localtransformerstext backend so the local-LLM adapter and theimprove lab runjudge run without a server (KAIZEN_TEXT_BACKEND=transformers); and a GLiNER2 PII scanner (verify audit pii_scan,KAIZEN_PII_MODEL) that augments, but never replaces, the regex redaction gate.manage model probeloads each configured backend. Sized to fit a 12 GB GPU; setup insetup/PYTORCH.md.
Two rules hold no matter what you enable: skip every backend and lexical search still covers the base case, and merely configuring a backend launches no build. Model output is advisory only: it never becomes the acceptance authority unless a deterministic verifier backs the call.
Does it phone home? Agent Kaizen has no product telemetry or fixed maintainer upload endpoint. The default single-user data plane is local, but network access is not limited to model backends: setup may download dependencies; explicitly enabled model, ComfyUI, and vendor-agent integrations contact their configured services; and configured fleet sync/control or Git remotes exchange data with operator-selected endpoints. Review a networked feature's configuration and data handling before enabling it.
Does AGPL make my project AGPL? No. The license covers this harness's code, not your code or your records. See Why AGPL.
Which agents work with it? Any agent that can run a CLI. Agents use Kaizen's commands to read and write its shared records.
Do I need Ollama, ComfyUI, or PyTorch? No. The core harness is dependency-light; the optional backends light up extra capabilities only when you install and point at them.
Where does my data live? Project records default to db/ inside the repo. Explicitly configured backends, vendor agents, fleet sync/control, and Git remotes can transmit operation-specific data to services or endpoints you select; that data then follows the selected service's policy.
Is it Windows-only? Windows is the current development target. Linux and the VS Code extension remain in development and require explicit selection; WSL use does not establish native Linux support, and macOS has not been validated as a supported target. Automatic remote tests cover Windows core and platform after the owner pushes, while Windows slow remains manual. Unselected development scopes are INAPPLICABLE; a selected scope that cannot run is NOT_RUN with a disposition. Remote CI runs after the owner pushes and is separate from local checks.
Treat generated DB data, reports, local policy context, artifacts, and exports as private by default. Before publishing a public repo, inspect:
- tracked files;
- ignored files that may later be force-added;
- generated reports and DB exports;
- artifact references and screenshots;
- personal paths, machine names, tokens, credentials, and secret-like strings.
Public tracked docs should explain the portable system and local harness, not private machine policy or user-specific operational constraints.
Contributions are welcome. See CONTRIBUTING.md for how to scope a change, run the tests, sign your commits (DCO), and open a pull request.
This repo is AGPL-3.0 licensed. See LICENSE for the terms and Why AGPL for the intent.