Kawa Code ユーザーマニュアル

Kawa Code へようこそ。リアルタイム AI 対応コラボレーションプラットフォームです。

目次

1. 概要
2. コアコンセプト
3. システム要件
4. インストール
5. AI プロバイダーの設定
6. Kawa Code 拡張機能
7. はじめに
8. CLAUDE.md のセットアップ
9. トラブルシューティング

概要

Kawa Code エコシステムは、複数の相互接続されたコンポーネントで構成されています。

アーキテクチャ

Editor (VSCode/Emacs/Vim)
    ↓ Unix sockets / Named pipes
Kawa Code (Desktop App)
    ↓ HTTP/SSE
Kawa API (Cloud)

データストレージと同期

Kawa Code は、まずデータをローカルに保存し、次にチームコラボレーションのためにクラウドに同期します。

主な機能:

• ローカルファースト: すべての操作はオフラインで動作し、接続時にデータが同期されます
• ゼロ知識暗号化: すべてのコード差分とインテントブロックの内容は、アップロード前にクライアント側で暗号化されます
• 自動チーム同期: チームメンバーのデータはローカルでダウンロードされ復号化されます
• 競合検出: コミット前に重複する作業が検出されます

コアコンセプト

以下の 4 つのアイデアが、Kawa Code のすべての機能の基盤となっています。これらを理解することで、このマニュアルの残りの部分、そして製品そのものがずっと把握しやすくなります。

差分認識型コラボレーション

Kawa Code はエディタで開いているすべてのファイルの現在の状態を継続的に追跡し、インターセクション — あなたの作業バージョンとチームメイトのバージョンが乖離している箇所 — を計算します。これは git の差分ではありません。git では見えない、コミットされていない進行中の作業を反映しています。あなたとチームメイトが同じ関数を同時に編集している場合、どちらもまだ保存もコミットもしていない段階で、Kawa Code がエディタ上でその重複をハイライトします。競合が生まれる前に調整する機会が生まれます。

スワーム認証

Kawa Code は、GitHub や GitLab のトークンを一切要求せずに、プライベートリポジトリに対してチームメンバーを認証します。代わりに、実際にリポジトリへのアクセス権を持つ人だけが提示できるコミット SHA を使用します。ブランチの最新コミットを正確に示せるなら、そのリポジトリへの読み取りアクセス権があることを実証できます。これにより、チームが新しいコミットをプッシュするたびに自然に更新される自己更新型の「アクセスプール」が形成されます。リポジトリを初めて接続する際にコミット SHA の入力を求められますが、それ以降は認証が自動的に処理されます。

ゼロ知識暗号化

Kawa Code がクラウドにアップロードするすべてのコード差分とインテントコードブロックは、あなたのマシンを離れる前に暗号化されます。暗号化キーは、リポジトリの最初のコミット SHA とオリジン URL から導出されますが、サーバーはどちらも知ることができません。Kawa API は自身では解読できない暗号文を保存します。同じリポジトリへのアクセス権を持つチームメンバーだけが、お互いの差分を復号できます。インテントや決定のメタデータは構造化されたプレーンテキストとして送信されます (検索や翻訳機能をサポートするため) が、実際のコードの内容は決してプレーンテキストでは送信されません。

テンポラルメモリ層

Kawa Code は、チームが何を構築しているか、そしてなぜそうしているかについての、永続的かつ検索可能な記録を維持します。インテントは現在のタスクを捉え、変更されている特定のコード行と関連付けます。デシジョンはアーキテクチャ上の選択の背後にある理由をリアルタイムで記録します。なぜ一つのアプローチが別のものより選ばれたのか、どの制約が代替案を除外したのかを残します。これらが合わさることで、セッションをまたいで維持されるチームメモリが形成されます。将来の貢献者は、コードが何をするかだけでなく、なぜそのように構築されたかを理解できます。MCP サーバーと併用すると、Claude Code は各セッションの開始時にこのメモリを自動的に読み込みます。

システム要件

すべてのプラットフォーム

• Git 2.25 以降
• クラウド同期のためのインターネット接続

Kawa Code デスクトップアプリ

• macOS: 10.15 (Catalina) 以降
• Windows: Windows 10 以降
• Linux: Ubuntu 20.04+ または同等

エディタ拡張機能

• VSCode: バージョン 1.105.0 以降
• Emacs: バージョン 26.1 以降 (タブバー機能には 27.1+ を推奨)
• Vim: Python3 サポート付き 8.2+ または Neovim 0.5.0+

MCP サーバー (Claude Code 用)

• Node.js 18.0.0 以降
• Claude Code CLI がインストールされていること

インストール

1. Kawa Code デスクトップアプリ (Kawa Code)

コードネーム Kawa Code の Kawa Code メインアプリケーションは、他のすべてのコンポーネントが動作するために実行されている必要があるコアデスクトップアプリケーションです。

kawacode.ai から最新リリースをダウンロードしてください。

• macOS: KawaCode-x.x.x.dmg
• Windows: Microsoft Store からインストール
• Linux: KawaCode-x.x.x.AppImage または .deb

2. エディタ拡張機能

IDE (Visual Studio Code、emacs) を開き、Kawa Code 拡張機能をインストールしてください。 すべての拡張機能は Kawa Code が実行されている必要があります。

3. Claude Code 用 MCP サーバー

MCP (Model Context Protocol) サーバーは、Claude Code が開発インテントを追跡し、Kawa Code のコラボレーション機能と統合できるようにします。

前提条件:

• Node.js 18.0.0 以降
• Claude Code CLI がインストールされていること
• Kawa Code が実行されていること

インストール:

cd kawa.mcp

# 依存関係のインストール
npm install

# ビルド
npm run build

Claude Code の設定:

MCP サーバーを Claude Code で利用できるようにする方法は 3 つあります。セットアップに合った方法を選択してください。

オプション A: プロジェクトレベルの設定 (チームに推奨)

プロジェクトのルートディレクトリに .mcp.json ファイルを作成します。

{
  "mcpServers": {
    "kawa-intents": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/kawa.mcp/build/index.js"]
    }
  }
}

このファイルを git にコミットしてください。リポジトリをクローンしたすべてのチームメンバーは、MCP サーバーを自動的に利用できるようになります (Claude Code は初回使用時に承認を求めます)。

オプション B: ユーザーレベルの設定 (すべてのプロジェクトで利用可能)

任意のディレクトリから実行します。

claude mcp add --transport stdio kawa-intents --scope user -- node /absolute/path/to/kawa.mcp/build/index.js

これにより、Claude Code で開くすべてのプロジェクトで kawa-intents サーバーが利用できるようになります。

オプション C: 単一プロジェクトの設定 (プライベート、1 つのプロジェクトのみ)

プロジェクトディレクトリ内から実行します。

claude mcp add --transport stdio kawa-intents -- node /absolute/path/to/kawa.mcp/build/index.js

これは、プロジェクトのパスの下の ~/.claude.json に設定を保存します。この設定は、Claude Code がその特定のディレクトリから起動された場合にのみ機能します。

上記のすべての例で、/absolute/path/to/kawa.mcp を kawa.mcp ディレクトリへの実際のパスに置き換えてください。

インストールの確認:

プロジェクトディレクトリで新しい Claude Code セッションを開始し、/mcp を実行します。ツールが利用可能な kawa-intents が表示されるはずです。

利用可能な MCP ツール:

AI プロバイダーの設定

Kawa Code はコミット履歴の推論などの機能のために大規模言語モデル (LLM) を使用します。API キーはご自身でご用意いただく形式 (BYOK) で、キーがマシンを離れることはなく、料金はプロバイダーに直接お支払いいただきます。Kawa Code 側での LLM 課金はありません。

プロバイダーの選択

Kawa Code で 設定 を開きます。AI プロバイダー — グローバルデフォルト で次のいずれかを選択してください。

• Anthropic — api.anthropic.com に直接呼び出します。お持ちの ANTHROPIC_API_KEY を使用します。キーは console.anthropic.com で取得できます。
• OpenRouter — openrouter.ai に呼び出します。OpenRouter は呼び出しを Anthropic (またはサポートされている他のモデル) に転送します。複数プロバイダーにまたがる従量課金で、高頻度タスクをより安価なモデルにルーティングしてコストを抑えたい場合に便利です。キーは openrouter.ai/keys で取得できます。

両方のキーを同時に保存できます。AI プロバイダー ラジオボタンがデフォルトで使用されるプロバイダーを決定します。キーは ~/.kawa-code/.storage.caw に暗号化されて保存され、Kawa Code のサーバーに送信されることはありません。

キーの保存

各キーをそれぞれのフィールドに貼り付けて 保存 をクリックします。保存 ボタンはフィールドに何かを入力したときにのみ表示され、キーが保存されると消えます。設定済みのキーは 「キーは設定済みです。新しいキーに置き換えることができます...」 というプレースホルダーで表示されます。

現在 LLM が使用されている箇所

現在、LLM は コミット履歴の推論 で使用されています。これは、git のコミットをストーリーにグループ化し、その過程で記録された決定や教訓を抽出する 2 パスのパイプラインです。グローバルで選択されたプロバイダーがパイプライン全体を処理します。

今後、LLM を使用する機能 (デシジョンディスティレーション、コンフリクト検出など) が追加される予定です。それらが出荷されると、設定画面に 詳細 セクションが追加され、機能ごとに別のプロバイダーにルーティングできるようになります。たとえば、長文解析には Anthropic Sonnet を使用しつつ、高頻度の分類処理は安価な OpenRouter モデルに送るといった使い分けが可能になります。

後からプロバイダーを切り替える

グローバルプロバイダーの切り替えには、対応するキーが事前に保存されている必要があります。キーが未設定のプロバイダーを選択しようとすると、設定画面にインラインでエラーが表示されます。これにより、すべての LLM 呼び出しが 401 を返す状態に陥ることを防ぎます。

Kawa Code 拡張機能

Kawa Code は スタンドアロン拡張機能 をサポートしています。これは、組み込みの Kawa Code が提供するものを超えた機能を追加する別個のプロセスです。拡張機能は、Kawa IPC プロトコルを使用して stdin/stdout 経由で Kawa Code と通信し、オプションで Kawa Code の UI 内に表示される UI コンポーネントを提供できます。

kawa.i18n (コード翻訳) 拡張機能は、最初のスタンドアロン拡張機能として出荷されています。時間の経過とともにより多くの拡張機能が利用可能になる可能性があります。または、独自の拡張機能を構築することもできます。

始める前に知っておくべき 2 つのこと:

• 拡張機能は API キーではなく、Claude Code の認証を使用します。 拡張機能を動作させるために、Kawa Code の設定で Anthropic API キーを構成する必要はありません。kawa.i18n 拡張機能はローカルにインストールされた claude CLI を呼び出し、既存の Claude Code ログインを通じてサインインします。(設定にある Anthropic API キーフィールドは、Kawa Code 自身の LLM 機能 (推論やデシジョン蒸留など) でのみ使用され、拡張機能では使用されません。)
• 拡張機能は Mac App Store 版の Kawa Code ではご利用いただけません。 Apple の App Store サンドボックスは、Kawa Code が拡張機能を実行するためのサブプロセスを生成することを禁止しています。macOS で拡張機能を使用するには、kawacode.ai から .dmg をダウンロードして Kawa Code をインストールしてください。Windows では、Microsoft Store からインストールしてください。拡張機能はそこで問題なく動作します。

拡張機能の仕組み

Editor (VSCode/Emacs/Vim)
    ↓ Huginn IPC
Kawa Code
    ├─ Gardener (built-in)          ← handles: auth, repo, sync, branch, context, user
    └─ Extensions (standalone)      ← handles: custom domains (e.g., i18n)
        ↓ stdin/stdout (JSON lines)
Extension Process

Kawa Code の起動時に、以下を行います。

1. extension.json マニフェストを含むサブディレクトリの ~/.kawa-code/extensions/ をスキャンします
2. 各マニフェストを検証します
3. 依存関係順に拡張機能をソートします
4. 各拡張機能を子プロセスとして生成します
5. ドメインサブスクリプションに基づいて IPC メッセージを拡張機能にルーティングします

拡張機能のインストール

リリースバイナリから

1. プラットフォーム用の拡張機能アーカイブをダウンロードします
2. ~/.kawa-code/extensions/ に展開します (またはそこにリンクします)。

mkdir -p ~/.kawa-code/extensions
# 以下の構造になるように展開します:
# ~/.kawa-code/extensions/<extension-name>/
#   ├── extension.json
#   ├── binaries/
#   │   └── <binary-for-your-platform>
#   └── ui/dist/  (optional)

3. Kawa Code を再起動します - 拡張機能は起動時に自動的に検出されます

ソースからのビルド

ソースから拡張機能をビルドしたい場合 (例: 開発用またはビルド済みバイナリがないプラットフォーム用)、kawa.i18n を例として以下の方法があります。

前提条件

• Node.js 18.0.0 以降
• npm または yarn

ビルド手順

cd kawa.i18n

# 依存関係のインストール
npm install

# プラットフォーム用のビルド (1 つを選択):
npm run build:macos      # macOS Intel/Apple Silicon
npm run build:linux      # Linux x64
npm run build:windows    # Windows x64

これにより、TypeScript がコンパイルされ、pkg を使用してすべてを binaries/ 下のスタンドアロンバイナリにバンドルします。

ビルド後のインストール

オプション A: 開発用のシンボリックリンク (ソースへの変更が開発モードで即座に反映されます):

macOS / Linux:

# 拡張機能はセットアップスクリプトを提供します:
./setup-dev-config.sh

# または手動で:
ln -s /path/to/kawa.i18n ~/.kawa-code/extensions/kawa.i18n

Windows (Git Bash、Developer Mode が有効な場合):

ln -s ~/Projects/Odin/kawa.i18n ~/.kawa-code/extensions/kawa.i18n

または管理者権限のコマンドプロンプト / PowerShell から:

mklink /D "%USERPROFILE%\.kawa-code\extensions\kawa.i18n" "%USERPROFILE%\Projects\Odin\kawa.i18n"

注: Windows 10+ では、Developer Mode が有効な場合、Git Bash の ln -s は管理者権限なしで動作します。それ以外の場合は、管理者権限のターミナルで mklink /D を使用してください。

オプション B: 本番用のコピー:

mkdir -p ~/.kawa-code/extensions/i18n
cp extension.json ~/.kawa-code/extensions/i18n/
cp -r binaries/ ~/.kawa-code/extensions/i18n/
cp -r ui/dist/ ~/.kawa-code/extensions/i18n/ui/dist/   # UI がある場合

インストール後、Kawa Code を再起動してください。

独自の拡張機能の作成

拡張機能は、stdin から JSON メッセージを読み取り、stdout に JSON レスポンスを書き込む任意の実行可能ファイルです。任意の言語 (Node.js、Python、Rust、Go など) で拡張機能を作成できます。

最小要件

1. 拡張機能のルートディレクトリに extension.json マニフェスト
2. マニフェストで参照される 実行可能バイナリまたはスクリプト
3. メッセージルーティング用の 少なくとも 1 つのドメインサブスクリプション

マニフェスト形式 (extension.json)

以下は最小限のマニフェストです。

{
  "id": "my-extension",
  "name": "My Extension",
  "version": "1.0.0",
  "description": "What this extension does",
  "binary": {
    "path": "./binaries/my-extension"
  },
  "domains": {
    "subscribe": ["my-domain"]
  }
}

完全なマニフェストリファレンス:

IPC プロトコル

拡張機能は、stdin/stdout の JSON 行経由で Kawa Code と通信します。

メッセージの受信 (stdin、1 行に 1 つの JSON オブジェクト):

{"flow":"req","domain":"my-domain","action":"do-something","caw":"client-1","data":{"key":"value"},"_msgId":"abc-123"}

レスポンスの送信 (stdout、1 行に 1 つの JSON オブジェクト):

{"flow":"res","domain":"my-domain","action":"do-something","caw":"client-1","data":{"result":"ok"},"_msgId":"abc-123"}

メッセージフィールド:

重要: ログには stderr を使用してください。stdout に書き込まれるものは有効な JSON でなければなりません。不正なログ出力はプロトコルを壊します。

ディレクトリ構造

拡張機能を ~/.kawa-code/extensions/<your-extension-id>/ に配置します。

~/.kawa-code/extensions/my-extension/
├── extension.json          # マニフェスト (必須)
├── binaries/
│   ├── my-extension-macos  # macOS バイナリ
│   ├── my-extension-linux  # Linux バイナリ
│   └── my-extension.exe    # Windows バイナリ
├── dev.sh                  # 開発モードラッパー (オプション; Unix/macOS)
├── dev.ps1                 # Windows 用開発モードラッパー (オプション; dev.sh より優先)
└── ui/
    └── dist/
        └── my-ui.js        # Web Component バンドル (オプション)

UI 統合 (オプション)

拡張機能は、Lit Web Components を使用して UI コンポーネントを提供できます。Kawa Code は JS バンドルを読み込み、2 つの方法でコンポーネントをレンダリングします。

• Panels: Kawa Code のサイドバーまたは下部エリアに表示されます
• Screens: Kawa Code のメニューからアクセスできる全画面ビュー

両方のパターンの実用例については、kawa.i18n 拡張機能のソースを参照してください。

はじめに

1. 初期セットアップ

1. Kawa Code をインストール してアカウントを作成します
2. エディタ拡張機能をインストール (VSCode、Emacs、または Vim)
3. kawa.mcp をインストール (オプション) Claude Code で作業したい場合
4. kawa.i18n をインストール (オプション) 自分の言語でコードを読みたい場合 (Claude CLI のインストールと認証が必要)
5. Git リポジトリを開く エディタで
6. 接続を確認: エディタで Kawa Code のステータスインジケーターを確認します

2. 基本的なワークフロー

1. 通常通りコードを作業 します
2. チームメイトが変更している行のハイライトを確認 します
3. サイドバー/パネルでピア差分を表示 します
4. Claude Code にコード作成を手伝ってもらいます
5. コードを開発するにつれて進化する Intents を確認します
6. kawa.i18n がインストールされている場合は Code View をクリックします。IDE (VSCode、emacs) で移動すると、翻訳されたファイルが Code View モードで自動的に表示されます
7. 準備ができたら コミットしてプッシュ します

3. Claude Code での使用

1. MCP サーバーをインストール (上記参照)
2. Claude Code で コーディングセッションを開始 します
3. Claude は自動的に以下を行います。
   • コーディング前にアクティブインテントを確認します
   • セマンティック検索でタスク関連コンテキストを取得します (get_relevant_context)
   • 新しいタスクのインテントを作成します
   • コード変更を追跡します
   • 実装中にアーキテクチャ決定を記録します
   • コミットを支援し、決定の要約を含めます

CLAUDE.md のセットアップ

CLAUDE.md は、リポジトリで作業する際に Claude Code に指示を提供する特別なファイルです。これにより、Claude は Kawa Code のインテント追跡と決定記録の機能を使用するようになります。

最小限必要な CLAUDE.md

プロジェクトルートに以下を含む CLAUDE.md ファイルを作成してください。

# CLAUDE.md

## Project Overview
[プロジェクトの 1-2 文の説明]

## AI Code Implementation Workflow

**BEFORE exploring code or reading files** for any non-trivial task, follow these steps in order:

1. **Check active intent**: Call `check_active_intent` (kawa-intents MCP) to see if work is already tracked
2. **Get relevant context**: Call `get_relevant_context` with a description of the task to find past decisions and related intents that may inform your approach
3. **Then explore code**: Now read files, search the codebase, and analyze the problem

For trivial one-line fixes (typos, obvious bugs), skip the above and use `log_work` after completing the change.

### Repository Origin and Path
Use these for MCP tools:
- `repoOrigin`: `[email protected]:your-org/your-repo.git`
- `repoPath`: `/absolute/path/to/your-repo` (must contain `.git` directory)

重要: repoPath は .git フォルダを含むディレクトリを指す必要があります。マルチプロジェクトセットアップ (モノレポ) では、親ディレクトリではなく、各サブプロジェクトのパスを使用してください。

これだけです。Claude は利用可能な MCP ツールを自動的に検出します。CLAUDE.md は、Claude に いつ ツールを呼び出すかを伝え、リポジトリの座標を提供するだけで十分です。

マルチプロジェクト / モノレポのセットアップ

ワークスペースに単一の親ディレクトリの下に複数の git リポジトリが含まれている場合、各サブプロジェクトには独自のオリジンとパスマッピングが必要です。CLAUDE.md に表を追加してください。

### Repository Origins and Paths

各サブプロジェクトには独自の `.git` ディレクトリがあります。MCP ツールを呼び出す際には、`repoPath` として **サブプロジェクトパス** (親ディレクトリではなく) を使用してください。

| Sub-project | `repoOrigin`                            | `repoPath`                       |
|-------------|-----------------------------------------|----------------------------------|
| my-api      | `[email protected]:my-org/my-api.git`      | `/path/to/workspace/my-api`      |
| my-frontend | `[email protected]:my-org/my-frontend.git` | `/path/to/workspace/my-frontend` |

オプション: 決定記録のガイダンス

Claude がアーキテクチャ決定の記録をより徹底的に行うようにしたい場合は、以下を追加してください。

### Recording Decisions

以下の場合に `record_decision` を使用して決定を記録します:

| Trigger                       | Decision Type |
|-------------------------------|---------------|
| 代替案の間で選択する          | `fork`        |
| 失敗するアプローチを試す      | `abandoned`   |
| 予期しない制限を見つける      | `discovery`   |
| 厳しい要件を特定する          | `constraint`  |
| 明示的なトレードオフを行う    | `tradeoff`    |
| ライブラリ/依存関係を選択する | `dependency`  |

トラブルシューティング

Kawa Code が起動しない

1. システム要件を確認してください
2. 他のインスタンスが実行されていないことを確認してください
3. ~/.kawa-code/logs/ のログを確認してください
4. ターミナルから実行してエラーメッセージを確認してください

エディタ拡張機能が接続しない

1. Kawa Code (Kawa Code) が実行されていることを確認してください
2. ソケットファイルが存在することを確認してください: ~/.kawa-code/sockets/muninn
3. Kawa Code とエディタの両方を再起動してください
4. エディタの出力/コンソールでエラーメッセージを確認してください

MCP サーバーの問題

1. Node.js のバージョンを確認してください: node --version (18+ である必要があります)
2. Claude Code で /mcp を実行して kawa-intents がリストされているか確認してください
3. 欠落している場合は、設定を確認してください。
   • Project scope: リポジトリルートの .mcp.json
   • User/Local scope: ~/.claude.json の projects → <your-project-path> → mcpServers キーの下
4. 設定のすべてのパスが絶対パスであることを確認してください (相対パスではありません)
5. kawa.mcp/ で npm run build が正常に完了したことを確認してください
6. Kawa Code が実行されているか確認してください
7. 設定変更後、Claude Code を再起動してください

Windows 固有の問題

• Unix ソケットの代わりに名前付きパイプが使用されます
• アンチウイルスが ~/.kawa-code/ をスキャンする場合があります - 除外の追加を検討してください
• 権限の問題が発生した場合は、Kawa Code を管理者として実行してください

一般的なエラーメッセージ

ヘルプの入手

• GitHub Issues: バグを報告し、機能をリクエストしてください
• Discord: リアルタイムヘルプのために コミュニティに参加 してください
• Documentation: kawacode.ai/docs を訪問してください

ライセンス

Kawa Code デスクトップアプリとクラウドAPIはプロプライエタリです。すべてのエディタ拡張機能とMCPサーバーはオープンソースです — エディタと並行して動作するものを正確に監査でき、必要に応じてフォークすることもできます。

完全なライセンスの詳細については、個々のコンポーネントリポジトリを参照してください。