CodeZaiku

CodeZaiku

A coding and development harness that runs on local models or hosted APIs. It is an AI coding agent for your terminal, like Claude Code or aider, that works with a small model on Ollama, llama.cpp, LM Studio or any OpenAI-compatible server. It also reviews git diffs, repairs a broken docker compose stack with rollback when you allow it, reports security problems in a server's Docker containers, researches questions with cited sources, and runs as an MCP server, an ACP agent or a command that prints JSON for other agents.

Most agents like this assume a frontier model behind someone else's API. CodeZaiku is built the other way round — a 9B on hardware you own — and the harness does the work that makes that viable: deterministic evidence instead of model guesses, a guard stack around anything that acts, and verification with rollback on every change.

It runs against any OpenAI-compatible server and ships no weights. The reference tier is a 9B.

→ [ARCHITECTURE.md](docs/ARCHITECTURE.md) — how it works → [LIMITATIONS.md](docs/LIMITATIONS.md) — the measured numbers

Quick start

You need an OpenAI-compatible model server, and a JDK 21+ unless you take a build that carries its own Java runtime (from 0.3.2, one per platform; the installer picks one when Java is missing). CodeZaiku ships no weights.

Linux is the supported platform. macOS runs the coding and research surfaces (and can operate remote Linux hosts over ssh); Windows works under WSL2. There is a container image. See [PLATFORMS.md](docs/PLATFORMS.md).

Three ways to use it

At a terminal, for yourself — carry on below; the commands are in *What you can do with it*.

Underneath another agent or orchestrator — CodeZaiku is a backend as well as a tool. It speaks a CLI-subprocess contract (codezaiku run), ACP (codezaiku acp) and MCP (codezaiku mcp). The contract, the result shape and the failure modes are in [DEPLOYING_AS_A_BACKEND.md](docs/DEPLOYING_AS_A_BACKEND.md); start there rather than here.

Underneath Wyrdsekai — CodeZaiku is released under the Wyrdsekai umbrella and is one of the coding backends Wyrdsekai can summon: you ask the companion for something, it hands the work to CodeZaiku. [WITH_WYRDSEKAI.md](docs/WITH_WYRDSEKAI.md) is the short version of the page above — just the wiring, and the two things that trip people up. Nothing here depends on it; CodeZaiku runs standalone.

Installing

There is one binary artifact and it is platform-independent. CodeZaiku is JVM bytecode with no native parts, so the same tarball installs on Linux, macOS and Windows — there is no .pkg or .msi to look for, and none is needed.

Linux is the reference platform. macOS and native Windows are measured too, and the installer is verified on all three from a clean unpack. On Windows, install from Git Bash — the harness shells out through bash, and Git for Windows supplies it. See [PLATFORMS.md](docs/PLATFORMS.md) for per-platform steps and for what does and does not work on each.

Linux and macOS:

curl -fsSL https://codezaiku.org/install | sh

Windows, from PowerShell (you also want Git for Windows — the harness shells out through its bash):

irm https://codezaiku.org/install.ps1 | iex

Only the script comes from codezaiku.org; the artifact and the checksums both come from the same GitHub release. What that URL serves is scripts/install-remote.sh (and scripts/install.ps1) from this repository, verbatim — read them here first if you would rather, and diff them against what the site serves. Both installers fetch the release tarball and verify it against the release's own `SHA256SUMS` before installing anything — a mismatch refuses rather than proceeds. Only the script comes from the URL above; the artifact and the checksums both come from the same GitHub release, so the script cannot hand you a payload those checksums do not match. Piping a script into a shell is worth being wary of in general: fetch it, read it, then run it if you would rather.

They install to ~/.local (or %LOCALAPPDATA%\Programs on Windows). CODEZAIKU_PREFIX puts it somewhere else, CODEZAIKU_VERSION pins a release.

No JRE on the machine yet? On Debian or Ubuntu, take the .deb from the latest release instead — it declares a JRE dependency, so apt installs one for you:

sudo apt install ./codezaiku_0.1.1_all.deb

The one-liners deliberately do not install a JRE themselves: a script piped into a shell should not be reaching for sudo. They check for one; when it is missing they install the build for the platform that carries its own runtime (codezaiku- - .tar.gz, from 0.3.2; CODEZAIKU_RUNTIME=1 asks for it outright), and codezaiku update keeps such an install on its own kind.

To upgrade, run `codezaiku update now`, or the same install command again. update now takes the latest release, checks it against the release's SHA256SUMS and swaps it in; the next start runs it. When ResearchZosho is installed, it then asks ResearchZosho's own updater to do the same, and says what came of each. Each program's own updater replaces its files, so two programs updating at once never collide: the second finds the first at work and leaves it alone. On Windows, CodeZaiku cannot replace its own files while it runs, so there you run the install command again. The installers resolve the latest release each time and replace the old install rather than writing over it, so nothing stale is left behind. Your config and data in ~/.codezaiku are untouched. The .deb upgrades in place with sudo apt install ./codezaiku_ _all.deb and keeps /var/lib/codezaiku; if you enabled codezaiku.service, the upgrade does not restart it, it tells you to when it suits you.

Other ways: tarball by hand, .deb, from source

tar xzf codezaiku-0.1.1.tar.gz          # unpacks a ready-to-run ./codezaiku

./codezaiku/bin/codezaiku --version # works immediately sudo mv codezaiku /opt/codezaiku sudo ln -s /opt/codezaiku/bin/codezaiku /usr/local/bin/codezaiku

On Debian or Ubuntu, sudo apt install ./codezaiku_0.1.1_all.deb — it installs to /opt/codezaiku, links /usr/bin/codezaiku, and lets apt pull a JRE. The systemd unit it ships is disabled; nothing starts on its own.

From source, if you want to build it yourself or work on it:

git clone https://github.com/Wyrdsekai/codezaiku.git && cd codezaiku

1. install — builds and puts codezaiku on your PATH (~/.local by default;

--system for /usr/local, --prefix DIR for anywhere else)

scripts/install.sh

2. point it at your model server (install.sh already wrote a starter config)

codezaiku setup # the first ten minutes: the model (found, served on demand, or a hosted key), web search, your editor's agent over MCP, the library if wanted codezaiku model serve install # this machine's memory, on demand: the measured model, llama.cpp behind a proxy that starts it when asked and stops it after 20 idle minutes (on Linux llama.cpp's container for the GPU it finds: NVIDIA, AMD or Intel; Metal on macOS, Vulkan on Windows) codezaiku model detect # finds Ollama / llama.cpp / LM Studio / vLLM if running codezaiku model use http://localhost:8200 codezaiku model add deepseek openrouter deepseek/deepseek-v4.1-flash --prices 0.032/0.144/0.002 # a hosted model under a name, codezaiku model key openrouter --file ~/openrouter-key.txt # its key kept for its host,

chosen per job: codezaiku code . "…" --model deepseek; codezaiku spend says what the jobs cost

3. check the environment — names exactly what is missing and how to fix it

codezaiku doctor

4. confirm the model answers and can call a tool

codezaiku smoke

The install carries its own launcher, jars and knowledge library, and downloads nothing at runtime. It does not bundle a JVM — install.sh checks for a JDK 21+ and stops if it does not find one. No model weights are bundled either. scripts/install.sh --uninstall removes the program and keeps ~/.codezaiku — your config, learned cards, research findings and audit trail. --purge removes those too, after listing what will be lost and asking you to confirm.

To work in the repo without installing, bin/codezaiku runs from the checkout.

If you have no server yet:

docker run -d --name codezaiku-drive -p 8200:8200 \

-v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:server-cuda \ -m /models/ .gguf --port 8200 --host 0.0.0.0 --jinja --ctx-size 32768

To use the models in your own AWS account (Amazon Bedrock) with your own AWS sign-in, see [BEDROCK.md](docs/BEDROCK.md).

--jinja is required — without it the model returns tool calls as prose and nothing works. See [MODELS.md](docs/MODELS.md) for what the harness needs from a model, what we measured on, and why codezaiku smoke is the check that matters.

Debian / Ubuntu

sudo apt install ./codezaiku_0.1.1_all.deb     # build it: packaging/deb/build-deb.sh

Installs to /opt/codezaiku with /usr/bin/codezaiku. A systemd unit is included but not enabled — CodeZaiku can modify live systems, so starting it is a deliberate act.

Verifying what you downloaded

Every release asset ships with SHA256SUMS and a Sigstore bundle ( .sigstore.json):

sha256sum -c SHA256SUMS --ignore-missing

gh attestation verify codezaiku-0.1.1.tar.gz --repo Wyrdsekai/codezaiku \ --predicate-type https://codezaiku.org/attestation/release/v1

gh attestation needs GitHub CLI 2.49 or newer. An older gh reports unknown command with no hint why — check with gh --version before concluding the signature is bad.

The signature says the release workflow, running at that tag, blessed those exact bytes. It is an authenticity statement, not build provenance — the artifacts are built and validated on real hardware rather than in CI, because an artifact nobody ran is not one worth shipping. Release assets are immutable; a fix ships as a new version, never as a re-upload.

What you can do with it

codezaiku help                                  # all commands, grouped by intent

Talk to it

codezaiku chat ~/myproject

A coding assistant you talk to in your terminal — the same kind of tool as Claude Code, Codex CLI or aider, except the model behind it is yours to choose: one running on your own hardware, or a hosted API. You type what you want — "why does the login test fail?", "add a retry to the uploader", "find out how other projects handle this" — and it reads your code, makes changes, runs commands, or searches the web, then reports back. You steer it turn by turn.

By default it asks before changing or running anything, a