codezaiku

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/brand/emblem-dark-512.png">
  <img alt="" src="docs/brand/emblem-512.png" width="190">
</picture>

# CodeZaiku

A coding and development harness that runs on **local models or hosted APIs**, through real work:
writing and maintaining code, reviewing diffs, operating a service stack, checking security posture,
and researching questions against live sources.

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](https://github.com/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

| path | needs | good for |
|---|---|---|
| **one-line install** — `curl … \| sh`, or `irm … \| iex` on Windows | a **JDK 21+**, or nothing: without one it takes the build with its own runtime | **the recommended path.** Verifies the download against the release checksums |
| **release tarball** — unpack and run; nothing to build | a **JDK 21+** | doing it by hand, or air-gapped |
| **Docker** — `packaging/docker/Dockerfile` | docker only | trying it with nothing on the host |
| **`.deb`** — from the release, or `packaging/deb/build-deb.sh` | a JRE, pulled automatically by apt | Debian/Ubuntu, no build |
| **from source** — `scripts/install.sh` | a **JDK 21+** and network for the build | development |

**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:**

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

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

```powershell
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`](scripts/install-remote.sh)
(and [`scripts/install.ps1`](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](https://github.com/Wyrdsekai/codezaiku/releases/latest) instead — it declares a JRE
dependency, so `apt` installs one for you:

```bash
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-<version>-<platform>.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 the same 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_<new>_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.

<details>
<summary>Other ways: tarball by hand, .deb, from source</summary>

```bash
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.

</details>

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

```bash
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 (CUDA in Docker on Linux, Metal on macOS, Vulkan on Windows)
codezaiku model detect        # finds Ollama / llama.cpp / LM Studio / vLLM if running
codezaiku model use http://localhost:8200

# 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:

```bash
docker run -d --name codezaiku-drive -p 8200:8200 \
  -v /path/to/models:/models ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m /models/<your-model>.gguf --port 8200 --host 0.0.0.0 --jinja --ctx-size 32768
```

`--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

```bash
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 (`<asset>.sigstore.json`):

```bash
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

```bash
codezaiku help