mozak

プロジェクトごとに承認済みの計画を一つ用意し、コーディングエージェントと共有して、Obsidian で確認できます。

コードではなく、アイデアや計画を扱います。複数のエージェントが互いの変更を上書きせずに一つの計画を共有し、ノートから進捗を確認できます。

概要 · 動作を見る · インストール · 仕組み · Obsidian ですべて確認 · 安全性 · テスト済みの内容 · ドキュメント

動作を見る

プレビューは 2 倍速で再生されます。76 秒の間に、エージェントに普通の言葉で頼むと、プロジェクトを読み込んで質問を一つし、計画を作成してあなたの承認を待ち、テスト結果を記録し、Obsidian のロードマップが進んでいきます。Obsidian 側は、プラグインがファイルを読み込んで画面を更新する様子をそのまま記録したものです。ターミナル側は、同じ mozak コマンドをディスク上で実行したエージェントとのチャットを、画面に再現したものです。クリックすると音声付きの完全版動画を再生できます。

概要

mozak はプロジェクトごとに一つの共有計画を用意し、プロジェクトフォルダー内のプレーンテキストファイルに保存します（公開リポジトリの場合はノート内にも保存できます）。 mozak は二つの役割を果たします。

• エージェントが同じ計画を読み込みます。 mozak のスキルまたは MCP サーバーを読み込んだエージェントは、同じ計画をもとに作業を開始するため、それぞれにコンテキストを貼り付ける必要はありません。エージェントは変更を提案しますが、あなたが承認するまでは計画に反映されません。
• Obsidian から進捗を確認できます。 各プロジェクトの計画がロードマップと進捗状況とともに保管庫に表示されるため、並行作業を一か所で確認できます。次のステップを承認するのはあなたです。エージェントがテストの実行結果など、合格を示す証拠を記録すると、成果は緑色に変わります。mozak 自体はテストを実行しません。また、自分で担当すると印を付けた成果にも、あなたの承認が必要です。

信頼できる理由：

• ファイルだけで構成されています。 mozak.json に計画を保存し、mozak.md は読みやすい形式のコピーです。これらは README.md と同じ場所にあり、そのフォルダーが git に含まれていれば、git が履歴を保持します。クラウドも、アカウントも、デーモンも必要ありません。
• 主導権はあなたにあります。 何をするかの合意と、実際に作業を始めることへの合意は、別々の承認です。
• 複数のエージェントでも混乱しません。 mozak 経由の書き込みで、古いコピーをもとにした変更は拒否されるため、他の人の作業を上書きしません。
• リポジトリとノートをまとめて扱えます。 プロジェクトにはローカルフォルダー、Obsidian 保管庫のフォルダー、あるいはまだクローンしていない GitHub リポジトリを指定できます。

コーディングエージェントをすでに利用していて、エージェント間で一つの計画を共有したい開発者や研究者向けです。スキルまたは MCP サーバーを読み込めるエージェントなら、どれでも利用できます。これまでに動作を確認したのは jcode（スキルと MCP）および Claude Code（MCP）です。

インストール

Node 24.11 以降（Node 26 も動作します）と Git が必要です。Linux と macOS に対応しています。

npm install -g mozak
mozak doctor --fix      # links the mozak skill into ~/.claude/skills, ~/.jcode/skills or ~/.codex/skills if they exist

npm パッケージには CLI と MCP サーバーが 1 つのパッケージにまとめられており、依存関係もインストールスクリプトもありません。npm install -g mozak@latest で更新できます。

エージェントを MCP サーバーに接続します（インベントリのパスはご自身のものを指定してください）。

# Claude Code
claude mcp add mozak -- mozak-mcp --config "$HOME/notes/mozak-inventory.json"
# Codex
codex mcp add mozak -- mozak-mcp --config "$HOME/notes/mozak-inventory.json"

その他の MCP クライアントの場合：コマンドは mozak-mcp、引数は --config /path/to/mozak-inventory.json です。

mozak scopes と Obsidian のサイドバーで、新しいリリースがあることを確認できます（MOZAK_NO_UPDATE_CHECK=1 を設定すると無効になります）。変更内容は CHANGELOG.md に記載されています。

git clone https://github.com/pitfa19/mozak.git && cd mozak
npm ci --ignore-scripts && npm run build
mkdir -p "$HOME/.local/share"
node scripts/install.mjs --prefix "$(cd "$HOME/.local/share" && pwd -P)/mozak" --json
"$HOME/.local/share/mozak/bin/mozak" --help

mozak upgrade --vault ~/Documents/notes   # newest tagged release; the old install is kept, plugin updated in that vault
mozak doctor --fix                        # checks the whole setup; fixes links, wrappers and plugin copies, prints the rest

詳細、終了コード、復旧方法、既知の制限については、docs/installation.md をご覧ください。

仕組み

1. プロジェクトを一覧にします。 1 つの mozak-inventory.json に、mozak が参照できるすべてのプロジェクトを記載します。スコープコマンドが操作するのは、ここに記載されたプロジェクトだけです。Obsidian プラグインが自動で見つけられるよう、ノートフォルダーの最上位に置いてください。

{
  "format": "mozak.local/v3",
  "scopes": [
    { "id": "my-app",     "root": "./my-app" },
    { "id": "lab-notes",  "root": "./vault/lab-notes" },
    { "id": "genome-mcp", "remote": "github:you/genome-mcp", "ref": "main" },
    { "id": "my-oss-tool", "remote": "github:you/my-oss-tool", "plans": "./vault/my-oss-tool" }
  ]
}

root を持つプロジェクトはローカルフォルダーです。remote を持つプロジェクトは GitHub リポジトリです。プランの保存場所は、誰と共有するかによって異なります。

• プライベートリポジトリ：プランはリポジトリ内に保存されるため、アクセス権を持つ全員で共有されます。mozak は README.md、AGENTS.md、mozak の 2 つのファイルだけをチェックアウトし（スパースかつシャローなクローン）、プランの変更をプッシュして戻します。
• パブリックリポジトリ：フォルダーを指定した "plans" を追加します。通常はノートフォルダー内に置きます。プランはそこに保存され、非公開のまま保たれ、リポジトリにコミットされることはありません。プランを保持しているリポジトリがパブリックになったことを mozak が検知すると、書き込みを拒否します（確認は最大 1 日に 1 回です。また、API に接続できなくても処理はブロックされません）。

mozak pull --into ~/Downloads/x を実行すると、コードを任意の場所にクローンできます。パブリックリポジトリの場合、クローンにプランファイルが含まれることはありません。クローン内で --scope を指定せずに mozak の読み取りコマンドを実行すると、クローンの Git リモートからプロジェクトが特定されます。

2. プロジェクトを開始します。 フォルダーに README.md と AGENTS.md を用意し、エージェントに mozak スキルを使ってセットアップするよう依頼するか、mozak scope init を自分で実行します（スキルの references/bootstrap.md を参照）。これにより、プロジェクトの mozak.json と mozak.md が作成されます。プロジェクトの作成はオーナー向けのコマンドです。エージェントは MCP 経由では作成できません。

3. プランに合意します。

1. 提案する。 エージェントがプランの草案を作成します。プランは 承認待ち の状態になります。
2. 方針を承認する。 何をするか に同意します。これにより計画が始まりますが、コーディングは始まりません。
3. 実装を承認する。 仕様が添付され、実装を別途承認します。
4. 記録する。 決定事項と根拠はプロジェクトのファイルに保存されるため、次のセッションで前回どこまで進んだかを確認できます。

4. エージェントが進め方を見つけられるようにします。 mozak scopes は、プランの件数とともにすべてのプロジェクトを一覧表示します。エージェントも MCP サーバーから同じ一覧を取得できます。

Obsidianですべてを確認する

packages/obsidian にあるObsidianプラグインを使うと、GitHubリポジトリも含め、インベントリ内のすべてのプロジェクトがサイドバーに表示されます。All、Open、Doneで絞り込めます。進行中のプランには小さな進捗バーが表示され、成果ごとに区切られています。プランをクリックすると、スコープの mozak.md 内にある該当セクションが開きます。メモのように、目的、成果を並べたロードマップと現在の停止位置、ステータス表、プラン全文が記載されています。サイドバーは閲覧と移動に使います。プランの承認はObsidianではなく、エージェントとのチャットで行います。プラグインがプランを承認したり変更したりすることはありません。古くなった mozak.md を再生成する場合があります。これは mozak render と同じ動作です。

Obsidianからインストールするには、Settings, Community plugins, Browseを開き、mozakを検索してから、InstallとEnableを選択します（ディレクトリのページ）。ソースをチェックアウトした状態から、次のコマンドを実行することもできます。

node scripts/install-obsidian-plugin.mjs /path/to/your/vault --build

プラグインはVaultフォルダーから上位のフォルダーを検索して mozak-inventory.json を見つけます。または、プラグイン設定でパスを指定できます。各GitHubプロジェクトには、公開リポジトリか非公開リポジトリかを示す地球儀または鍵のバッジが表示されます。

プラグインに関する開示情報（デスクトップ専用、isDesktopOnly: true）： mozak-inventory.json に現在のVault外のスコープが記載されている場合、プラグインは設定されたパスからそれらの mozak.json、mozak.md、README.md、AGENTS.md ファイルを読み取り、Auto-refreshが有効なときはそれらを監視します。インベントリに記載されていないフォルダーをスキャンすることはなく、プランを承認したり変更したりすることもありません（マージされていない手動編集がない場合、古くなった mozak.md の投影を再生成することがあります）。リモートのGitHubスコープ（Vaultにホストされた "plans" がなく、"remote": "github:owner/repo" が指定されている場合）で、Sync remote scopesをクリックするか、**Repo sync interval (seconds)**を有効にすると、既存のGitログインを使用して、非表示の .mozak-cache コピーに対しローカルの git が実行されます。実行されるのは git fetch の後、そのコピーを取得したコミットにリセットする処理です。以前のmozakによる書き込みで、プランのコミットがプッシュされずに残っている場合（たとえばネットワーク障害の後）、同期時にまず保留中の mozak.json／mozak.md の変更をコミットしてプッシュします。バックグラウンドでのgit操作を無効にするには、同期間隔を 0 に設定します。また同期では、ログインせずに公開GitHub APIへ問い合わせ、リポジトリごとに1日最大1回、各リモートリポジトリが公開かどうかを確認します。更新通知は、CLIが書き込むキャッシュファイルを読み取るだけです。プラグインが自らをインストールまたは更新することはなく、テレメトリーもありません。開示事項の一覧は、packages/obsidian/README.mdを参照してください。

内部の仕組み

エージェントはプロジェクトフォルダー内にプレーンな mozak.json と mozak.md ファイルを書き込みます。Obsidianのサイドバーと、各メモ内のロードマップ図は、これらのファイルから描画されます。エージェントがUIコードを書くことはありません。

エージェントと一緒に使う

スコープ関連のコマンドには、明示的な --config が必要です。設定なしで実行できるのは、メンテナンス用コマンド（upgrade、doctor）だけです。

安全性

• 承認の範囲を限定します。 承認は、提示された正確なプランのバージョンに紐づき、1つのメッセージを2回目の承認に再利用することはできません。MCP 経由のエージェントは、いかなる場合も承認できません。スキルでは、エージェントに対し、引用やツールの出力ではなく、あなた自身のメッセージだけを受け入れるよう指示しますが、mozak は誰が入力したかを確認できません（以下の制限をご覧ください）。
• 上書きしません。 古いコピーに基づく mozak 経由の書き込みは拒否されます。ファイルを手動で編集した場合は保護されません。
• プッシュ対象を限定します。 プライベートな GitHub プロジェクトの場合、mozak は mozak.json と mozak.md だけをコミットしてプッシュします。プランがメモにあるパブリックリポジトリの場合、コミットもプッシュも行いません。
• 認証情報を扱いません。 mozak が認証情報を求めたり保存したりすることはありません。GitHub へのアクセスには、既存の git ログインを使用します。
• 制限を正直に示します。 承認は信頼できるホストでの慣例に従うものであり、認証ではありません。シェルへのアクセス権を持つエージェントであれば、所有者用コマンドを実行できてしまいます。同時実行に関する保証は、ローカルディスク上で協調して動作するプロセスを対象としており、ネットワークドライブ、電源喪失、同じファイルを編集する同期ツールは対象外です。リモートのスコープは1つのブランチに従います。

テスト済みの項目と未検証の項目

テスト済み。 450件の単体テストと統合テストに加え、74件のインストーラーテストを実施しています。すべての main へのプッシュとすべてのプルリクエストに対し、Node 24.11 および 26 を使い、Ubuntu と macOS 上の CI で実行されます。テスト対象は次のとおりです。

• 2つの CLI プロセスが同時に書き込みを行うケースも含め、古い状態からの書き込みが拒否されること
• 書き込みが途中で強制終了された場合も、データを失わずに復旧すること
• 2つの承認が分離された状態に保たれ、提示されたバージョンに紐づくこと
• MCP 経由のエージェントが承認やプロジェクトの作成をできないこと
• パブリックリポジトリにプランのコミットが送られないこと
• インストーラーが安全でないインストール先への書き込みを拒否すること

Obsidian プラグインは、Obsidian の自動コミュニティレビューに合格しました。ビルドとアテステーションは、リリースごとに確認されます。

まだ実証されていません。

• エージェントにとっての効果。 小規模なパイロット（プロキシタスク5件、エージェントセッション10件）で、mozak を使うエージェントと使わないエージェントを比較したところ、トークン使用量に有意な差はありませんでした。一方のグループは16％悪化し、もう一方は6％改善しました。より大規模な評価を予定しています。それまでは、mozak を、承認済みのプランを1つに保ち、Obsidian で確認できるようにする手段として捉えてください。速度向上が実証されたものではありません。
• エージェントホスト。 確認済み：スキルと MCP サーバーを読み込む jcode、および npm パッケージから MCP サーバーを呼び出す Claude Code 2.1。Codex やその他の MCP クライアントは、まだ検証されていません。
• Obsidian 内でのプラグインの動作。 ビューモデルは単体テスト済みで、手動でも試されていますが、Obsidian アプリ内で実行する自動テストはありません。
• 実際の GitHub。 テストではローカルの bare リポジトリを使用しています。実際の GitHub は手動で確認しました。
• サポート対象外の環境。 Windows、ネットワークファイルシステム、分岐したリモートブランチ。

プラットフォーム

Linux および macOS、Node 24.11 以降。

コントリビュート

npm ci --ignore-scripts && npm run build
npm test && npm run test:install

プルリクエストを作成する前に、テストを実行してください。グローバルの git 設定でフックや署名が追加されている場合は、GIT_CONFIG_GLOBAL=/dev/null を指定して実行してください。形式、リモートのスコープ、終了コード、既知の制限については、docs/installation.md をご覧ください。

ライセンス

MIT。LICENSE をご覧ください。