CodeZaiku

CodeZaiku

ローカルモデルまたはホスト型 APIで動作する、コーディングおよび開発用ハーネスです。Claude Code や aider のようにターミナルで使える AI コーディングエージェントで、Ollama、llama.cpp、LM Studio、または OpenAI 互換サーバー上の小型モデルと連携します。また、git の差分をレビューし、許可を得た場合にはロールバック付きで壊れた docker compose スタックを修復し、サーバーの Docker コンテナ内のセキュリティ問題を報告し、出典を引用して質問を調査します。さらに、MCP サーバー、ACP エージェント、またはほかのエージェント向けに JSON を出力するコマンドとして動作します。

この種のエージェントの多くは、他社の API の背後にある最先端モデルを前提としています。CodeZaiku は逆の方向から作られています。つまり、自分が所有するハードウェア上の 9B モデルを活用し、それを実用可能にする作業をハーネスが担います。モデルの推測ではなく決定論的な根拠を用い、動作を伴うあらゆる処理をガードスタックで保護し、変更のたびにロールバック付きで検証します。

OpenAI 互換サーバーであればどれでも動作し、重みは同梱していません。リファレンスのモデル規模は 9B です。

→ ARCHITECTURE.md — 仕組みについて → LIMITATIONS.md — 測定結果

クイックスタート

OpenAI 互換モデルサーバーとJDK 21 以降が必要です。ただし、独自の Java ランタイムを含むビルドを使用する場合は不要です（0.3.2 以降、プラットフォームごとに 1 つ用意されており、Java がない場合はインストーラーが選択します）。CodeZaiku に重みは同梱されていません。

サポート対象のプラットフォームは Linux です。macOS ではコーディングと調査の機能を利用でき（ssh 経由でリモートの Linux ホストを操作することもできます）、Windows では WSL2 上で動作します。コンテナーイメージもあります。PLATFORMS.md を参照してください。

使い方は 3 通り

自分でターミナルから使う場合 — 以下を読み進めてください。コマンドは できること に記載されています。

別のエージェントやオーケストレーターの下で使う場合 — CodeZaiku はツールであると同時にバックエンドでもあります。CLI サブプロセスの契約（codezaiku run）、ACP（codezaiku acp）、MCP（codezaiku mcp）に対応しています。契約、結果の形式、失敗時の動作については DEPLOYING_AS_A_BACKEND.md を参照してください。ここではなく、まずそちらから始めてください。

Wyrdsekai の下で使う場合 — CodeZaiku は Wyrdsekai の傘下で公開されており、Wyrdsekai が呼び出せるコーディングバックエンドの 1 つです。コンパニオンに依頼すると、その作業を CodeZaiku に渡します。 WITH_WYRDSEKAI.md は上記ページの簡潔版で、接続方法と、つまずきやすい 2 つの点だけを説明しています。CodeZaiku は単体でも動作するため、ここに記載された内容は必須ではありません。

インストール

バイナリアーティファクトは 1 つだけで、プラットフォームに依存しません。 CodeZaiku はネイティブ部分を含まない JVM バイトコードのため、同じ tarball を Linux、macOS、Windows にインストールできます。.pkg や .msi を探す必要はなく、それらも不要です。

リファレンスプラットフォームは Linux です。macOS とネイティブ Windows も測定済みで、クリーンな展開状態から、3 つすべてでインストーラーの動作を確認しています。Windows ではGit Bash からインストールしてください。ハーネスは bash を呼び出し、Git for Windows がこれを提供します。プラットフォームごとの手順と、それぞれで動作する機能・動作しない機能については PLATFORMS.md を参照してください。 Linux および macOS：

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

Windowsでは、PowerShell から実行します（Git for Windows も必要です。ハーネスは bash 経由でシェルコマンドを実行します）。

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

codezaiku.org から取得するのはスクリプトのみです。成果物とチェックサムは、どちらも同じ GitHub リリースから取得します。この URL が配信するのは、このリポジトリの scripts/install-remote.sh（および scripts/install.ps1）そのものです。先にこちらで読んでおきたい場合は、サイトが配信するものと比較してください。どちらのインストーラーもリリースの tarball を取得し、インストールを始める前にリリースに含まれる SHA256SUMS と照合して検証します。不一致の場合は続行せず、拒否します。上記の URL から取得するのはスクリプトのみで、成果物とチェックサムはどちらも同じ GitHub リリースから取得するため、スクリプトがチェックサムと一致しないペイロードを渡すことはできません。スクリプトをシェルにパイプで渡すことには、一般に注意が必要です。先に取得して内容を読み、必要であれば実行してください。

インストール先は ~/.local（Windows では %LOCALAPPDATA%\Programs）です。CODEZAIKU_PREFIX で別の場所を指定でき、CODEZAIKU_VERSION でリリースを固定できます。

まだマシンに JRE がありませんか？ Debian または Ubuntu では、最新リリースから .deb を取得してください。JRE 依存関係が宣言されているため、apt が自動的にインストールします。

sudo apt install ./codezaiku_0.1.1_all.deb

ワンライナーが JRE を自らインストールしないのは、意図的なものです。シェルにパイプで渡すスクリプトが sudo を使うべきではありません。JRE の有無を確認し、見つからない場合は独自のランタイムを含むプラットフォーム向けビルド（0.3.2 以降の codezaiku-<version>-<platform>.tar.gz）をインストールします。CODEZAIKU_RUNTIME=1 を指定すれば、明示的にそのビルドを選択できます。また、codezaiku update はそのようなインストールを同じ種類のまま維持します。

アップグレードするには、codezaiku update now を実行するか、同じインストールコマンドをもう一度実行してください。 update now は最新リリースを取得し、リリースの SHA256SUMS と照合してから差し替えます。次回の起動時に新しいバージョンが実行されます。ResearchZosho がインストールされている場合は、続けて ResearchZosho 自身のアップデーターにも同じ処理を依頼し、それぞれの結果を知らせます。各プログラムのアップデーターは自身のファイルを差し替えるため、2つのプログラムが同時に更新しても競合しません。後から始めたほうは先に始めた更新を検知し、そのまま待機します。Windows では CodeZaiku の実行中に自身のファイルを差し替えられないため、インストールコマンドをもう一度実行してください。インストーラーは毎回最新リリースを確認して古いインストールを置き換えるため、古いファイルが残ることはありません。~/.codezaiku 内の設定とデータはそのまま残ります。.deb は sudo apt install ./codezaiku_<new>_all.deb で上書きアップグレードされ、/var/lib/codezaiku も維持されます。codezaiku.service を有効にしている場合、アップグレード時にサービスは再起動されず、都合のよいときに再起動するよう案内されます。

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

自分でビルドしたい場合や開発に参加する場合は、ソースからインストールしてください。

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

インストールには、独自のランチャー、jar、ナレッジライブラリが含まれており、実行時に何もダウンロードしません。JVM はバンドルされていません。install.sh は JDK 21 以降があるか確認し、見つからない場合は停止します。モデルの重みもバンドルされていません。scripts/install.sh --uninstall はプログラムを削除し、~/.codezaiku（設定、学習したカード、調査結果、監査記録）は保持します。--purge は、削除される内容を一覧表示して確認を求めたうえで、それらも削除します。

インストールせずにリポジトリ内で作業するには、チェックアウトから bin/codezaiku を実行します。

まだサーバーがない場合：

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

独自の AWS サインインを使って、自分の AWS アカウント（Amazon Bedrock）でモデルを利用する方法については、BEDROCK.md を参照してください。 --jinjaは必須です。指定しないと、モデルはツール呼び出しを文章として返すため、何も機能しません。 ハーネスがモデルに求めるもの、測定した内容、そして codezaiku smoke が重要なチェックである理由については、MODELS.md を参照してください。

Debian / Ubuntu

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

/opt/codezaiku にインストールされ、/usr/bin/codezaiku が配置されます。systemd ユニットが含まれていますが、有効化されていません。CodeZaiku は稼働中のシステムを変更できるため、起動は意図的に行うものです。

ダウンロードしたものを検証する

各リリースアセットには SHA256SUMS と Sigstore バンドル（<asset>.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 には GitHub CLI 2.49 以降が必要です。古い gh では理由が示されずに unknown command と表示されるため、署名に問題があると判断する前に gh --version で確認してください。

署名は、そのタグで実行されたリリースワークフローが、該当するバイト列を承認したことを示します。これは真正性を示すものであり、ビルドの来歴を示すものではありません。誰も実行していないアーティファクトに出荷する価値はないため、アーティファクトは CI ではなく実機でビルドおよび検証されます。リリースアセットは変更できません。修正は再アップロードではなく、新しいバージョンとして出荷されます。

できること

codezaiku help                                  # all commands, grouped by intent

対話する

codezaiku chat ~/myproject

ターミナルで対話できるコーディングアシスタントです。Claude Code、Codex CLI、aider と同じ種類のツールですが、背後で動くモデルは自分で選べます。自分のハードウェアで動かすモデルでも、ホスト型 API でも構いません。やりたいことを入力すると、「ログインのテストが失敗するのはなぜ？」「アップローダーにリトライを追加して」「ほかのプロジェクトがどう対処しているか調べて」といった指示に応じて、コードを読み、変更を加え、コマンドを実行したり、ウェブを検索したりして、結果を報告します。ターンごとに指示を調整できます。

デフォルトでは、変更や実行の前に確認を求め、変更内容を正確に表示します。一度だけ、またはそのコマンドについて「always」と回答します。/undo を使うと、実行された内容を段階的に取り消せます。会話は保存され、後から再開できます。また、/remember を使うと、プロジェクト内の今後のすべての会話で特定の情報を利用できます。チャット内で /help を実行すると、バックグラウンドタスク、2 つ目のエージェントへの作業委任、モデルの切り替え、コストの追跡など、ほかの機能がすべて表示されます。

codezaiku v1 ~/myproject は、同じアシスタントを OpenAI 互換 API （/v1/chat/completions）として提供するため、Open WebUI のようなチャット UI をフロントエンドとして使えます。この API 経由では読み取りのみが可能で、変更はできません。API は許可を求められないため、許可が必要になる操作は一切できないようになっています。

質問を調査する

codezaiku research "your question" broad
codezaiku research "your question" fan

ウェブを検索し、ページを読み、出典を引用した回答を作成します。broad は単独で調査を行います。fan は質問を複数の部分に分けて並行して調査し、批評役に調査範囲が十分かを確認させたうえで、回答をまとめます。処理に時間はかかりますが、複数の論点を含む質問では大幅に優れた結果が得られます。

検索はインストール直後から使え、バックエンドを設定するとさらに便利になります。 バックエンドがない場合、web_search は Wikipedia と学術文献（Crossref と OpenAlex）にフォールバックします。つまり、DOI で参照ページや論文を検索しますが、ウェブ全体を検索するわけではありません。すべての調査実行で、バックエンドにかかわらず、DOI による文献検索を行う scholar_search も利用できます。ウェブ全体を検索するには、以下の 2 つの選択肢があります。最初の方法を推奨します。

codezaiku config set CODEZAIKU_BRAVE_KEY <key>        # recommended: Brave Search API
codezaiku config set CODEZAIKU_SEARXNG http://host:8888   # or: your own SearXNG instance

Brave Search API には無料枠（月 2,000 件のクエリ）があり、検索結果が大幅に向上します。検索ツールの性能は、検索対象の質に左右されるためです。SearXNG は完全にセルフホスト可能でアカウントも不要ですが、継続的に使用するとレート制限がかかる公開検索エンジンを集約しています。両方を設定すると、まず Brave が使われ、次に SearXNG がフォールバックとして使われます。どちらかを設定すると、chat 内のウェブ検索も有効になります。

調査で見つかった内容は保存されます。~/.codezaiku/research にある調査メモリには、出典とともに各調査結果が保存されます。同じテーマの次回の調査はゼロから始めず、そこに保存された情報を活用します。これは標準で備わっている機能で、ほかに何もインストールしなくても使えます。 実際に調査を行い、何時間もかけて確認可能なレポートを作成する場合は、同じファミリーの別プログラムである ResearchZosho をご利用ください。codezaiku install researchzosho でダウンロード、検証、セットアップを実行します。以降、チャットの /research ファイルはこれを使って実行され、/librarian で所蔵内容を確認できます。また、所蔵内容は すべてのターンに反映されます。調査メモリ内の質問は、未解決の質問として渡されます。codezaiku doctor とチャットで ResearchZosho の新しいバージョンがリリースされたことが通知されます。codezaiku update now では ResearchZosho 独自の アップデーターがインストールを実行し、ライブラリと設定はそのまま維持されます。

コードベースで作業する

codezaiku code ~/myproject "add pagination to the /items endpoint"
codezaiku decompose ~/myproject "add an admin dashboard with login and audit view"
codezaiku review ~/myproject HEAD~3             # read-only review -> findings

code は目標を達成するまで会話を続けます。モデルが作業全体を一度に把握できる場合に使います。decompose はまず目標を順序付けられた単位に分割し、その計画を TODO として固定して毎ターン再注入しながら、同じループを実行します。そのため、最初の単位を終えた時点で実行可能なプログラムができ、そこから成長していきます。モデルが作業の流れを見失うほど大きな作業には、こちらを使います。loop は code の旧称で、現在も使えます。

スタックを運用する — 状況を把握し、障害が発生しているサービスを特定して修正し、検証し、失敗時にはロールバックします

codezaiku fix myproject propose                 # diagnose and propose (default, safe)
codezaiku fix myproject guarded                 # act, behind the full guard stack
codezaiku watch myproject propose 60            # continuous: fix on degraded, else report
codezaiku investigate myproject                 # diagnose only — capped at localize, never acts

対象範囲はローカル（myproject）、リモート（ssh://host/myproject）、またはコンテナー（docker://name）にできます。それ以外の項目（ヘルスエンドポイントや検証コマンドなど）は自動検出されます。

マシン全体を運用する — 対象範囲を1つのスタックではなくマシンに設定して、同じオペレーターを使用します

codezaiku triage local                          # enumerate the box, report what is broken
codezaiku triage local "" 20 guarded            # ...and repair the unhealthy compose stacks
codezaiku watch-machine local 300               # the same sweep on a loop, as a daemon

triage は、検出可能なすべてのもの（Compose スタック、障害が発生した systemd ユニット、ホストのディスクとメモリ）を列挙し、異常な各スタックに対して SRE オペレーターを実行し、systemd とホストの調査結果を人間に提示します。各スタックには引き続き影響範囲と権限の段階が適用されるため、対象範囲を広げても、個々の修正が変更できる範囲は広がりません。

デフォルト設定の違いにご注意ください。マシン全体を対象とするコマンドがスタック単位のコマンドより慎重さに欠ける唯一の点です。triage は guarded または unattended を指定しない限り、レポートを出力します。一方、watch-machine のデフォルトは guarded です。マシンを健全な状態に保つことを目的とするデーモンなので、実際に動作します。監視のみを行わせたい場合は、上限を明示的に指定します。 codezaiku watch-machine local 300 "" propose。実機では systemd の下で実行してください。

セキュリティ態勢を確認する — レポートのみを出力し、自動修復は行いません

codezaiku secure local

ライブソースを使って質問を調査する

codezaiku research "what changed in the Foo API in v3" depth

別のエージェントから操作する

codezaiku run --text "add pagination" --output-format json   # one task, one JSON result
codezaiku acp                                   # Agent Client Protocol v1 agent on stdio
codezaiku mcp                                   # MCP server on stdio, all surfaces exposed
npx -y @wyrdsekai/codezaiku-mcp                 # the same, from any client that runs npm packages; installs the release if needed
codezaiku serve 7070                            # HTTP: POST /fix, GET /health, GET /audit

安全性

オペレーターはシステムを変更できるため、デフォルト設定は慎重に設計されており、ガードは必須です。

• 権限の段階 — observe < localize < propose < guarded < unattended。デフォルトは propose です。実行するコマンドを提示しますが、実行はしません。実証されていない修正が自動適用されることはありません。
• 影響範囲は1 — 修正で変更できるのは、障害箇所として特定されたサービスだけです。
• ロールバック — 破壊的な変更の前にスナップショットを作成し、変更後に検証し、検証に失敗した場合は復元します。 これを有効にした状態では、モデルがデータベース設定を破損した際にロールバックされ、スタックは正常な状態に戻りました。有効にしていなければ、同じ障害でサービスが停止したままでした。
• 危害チェック — 対象を修復しても、健全な依存先を壊す修正は失敗とみなされます。
• 緊急停止スイッチ — CODEZAIKU_OPS_HALT=on を設定すると、即座に observe に切り替わります。
• セキュリティ上の検出事項は、すべての段階でレポートのみです。 信頼性に関する誤った修正はサービスを再起動しますが、封じ込めに関する誤った措置は自分のロードバランサーをファイアウォールで遮断してしまいます。

信頼できない入力は、信頼できないものとして扱われます。コンテナーのログは攻撃者が書き換えられるものであり、それらを通じた実測済みのインジェクションにより、構造的に修正される前は両方のモデル層でオペレーターが 40/40 の割合で誘導されました。ARCHITECTURE.md §6 をご覧ください。

これは何ではないか

• 最先端のコーディングエージェントではありません。 9B モデルで SWE-bench Lite は約 1/8、リファクタリングは 0/8 です。はるかに大規模なモデルを基盤とするツールの代わりにはなりません。
• 本番運用向けに十分な堅牢性はありません。 長時間稼働の耐久性を示す証拠はまだありません。
• マルチエージェントフレームワークではありません。 ループは 1 つ、優れたツール、厳密な測定です。以前のブラックボード／エージェントアーキテクチャは設計され、一部実装されましたが、削除されました。

詳細な説明は LIMITATIONS.md をご覧ください。

リポジトリの構成

bench/ は意図的に含めています。LIMITATIONS.md に記載されたすべての数値は、良くない結果に終わったものも含め、これらのハーネスで測定しました。

ドキュメント

• ARCHITECTURE.md — 設計
• LIMITATIONS.md — 測定結果
• MODELS.md — モデルサーバーの選択と実行
• PLATFORMS.md — Linux、Docker、macOS、Windows
• CONFIGURATION.md — 重要な 6 つの設定と、それ以外の設定
• DEPLOYING_AS_A_BACKEND.md — 別のエージェントやオーケストレーターの配下での実行
• WITH_WYRDSEKAI.md — Wyrdsekai のコーディングバックエンドとしての接続方法
• ROADMAP.md — 次に取り組む項目。測定結果から分かったボトルネックに基づく順序です
• CONTRIBUTING.md — 測定ルールを含みます
• SECURITY.md — 報告方法と、エージェント独自の脅威モデル

お問い合わせ。 バグ報告や機能リクエストは、ほかの人も内容と回答を確認できる issues にお寄せください。それ以外のお問い合わせは [email protected] までご連絡ください。脆弱性は [email protected] または非公開のアドバイザリーで報告してください。詳細は SECURITY.md をご覧ください。行動に関する懸念は [email protected] までご連絡ください。

ファミリー

CodeZaiku は Wyrdsekai の一部で、姉妹プロジェクトは研究ライブラリの ResearchZosho です。ResearchZosho は研究の実行で見つかった内容を保持し、主張を情報源と照合して確認し、保持している情報に基づいて質問に回答します。 codezaiku install researchzosho を実行すると CodeZaiku と並べてインストールされます。2 つはモデルサーバーを共有するため、マシン上の 1 つのオンデマンドモデルで両方を利用できます。

ライセンス

Apache 2.0 — LICENSE をご覧ください。