koda

Koda

コーディングエージェントのワークフローに検証と記憶を。 一度インストールすれば、重要な変更を検証し、繰り返し壊れるものを記憶します。

Open VSX で 1,000 回以上ダウンロード — Koda はすでに世界中のエディターでコミットを監視しています。

---

npm	npm install -g koda-verify (npmjs.com)
IDE	Open VSX — VS Code、Cursor、Windsurf、VSCodium で動作します
MCP	レジストリ
ランディングページ	aabxtract.github.io/koda

Koda が作られた理由

コーディングエージェントは数分で機能を書き上げます。しかし、すべてのコミットを誰が検証するのでしょうか？テストスイート全体をコミットごとに実行するには時間がかかりすぎるため、ほとんどの検証は後回しにされるか、まったく行われません。Koda はこのギャップを埋めます。コミットのたびに、変更された箇所だけを数秒から数分で検証し、繰り返し壊れるものを記憶することで、エージェントが古いバグを再び持ち込まないようにします。

Koda はコードを書きません。検証を調整し、パターンを記憶して、人間とエージェントの両方にレポートします。

3 つの利用形態

利用形態	役割	有効化方法
コア + CLI	検証、レポート、メモリ、Git フック、CI 生成	koda init、koda run
MCP サーバー	エージェントが koda_verify / koda_report / koda_memory / koda_setup_cicd を呼び出します	MCP クライアントの設定
IDE 拡張機能	常時表示のステータスバー、レポートビューアー、ワンクリックで有効化、Git の監視	ユーザーが「有効化」をクリック

仕組み — パイプライン

git commit
   │
   ▼
pre-commit ── secret guard (blocks committed API keys / private keys)
   │
   ▼
post-commit ── koda run (background, never blocks you)
   │
   ▼
1. Read diff ──────────── classify files: api / page / component / lib / config / test
2. Impact analysis ────── agent-supplied (MCP) → Groq fallback → deterministic heuristics
3. Kane browser flows ─── headless, scoped to changed UI only (page/component changes)
4. Endpoint checks ────── GET / HEAD / OPTIONS only; regressions flagged (200 → 500)
5. Integration tests ──── Jest / Vitest / Mocha / node:test, matched to changed files
6. Report ─────────────── JSON (agent-readable) + Markdown (human-readable)
7. Memory ─────────────── recurring patterns, resolution history, time-to-fix

ほとんどのコミットではブラウザーを起動しません。API／設定／テストのみの変更は、エンドポイントとテストを使って数秒で検証します。ブラウザーフローが実行されるのは UI ファイルが変更された場合だけです。

---

クイックスタート

npm install -g koda-verify
cd your-project
koda init        # creates .koda/, installs git hooks, detects your app's port
koda doctor      # verifies: git, config, Kane CLI, target URL, directories

あとはコミットを続けるだけです。コミットのたびに、検証がバックグラウンドで実行されます。

ブラウザーの初回セットアップ（任意、ユーザーごと）

ブラウザーフローは Kane CLI を利用します。IDE 拡張機能がセットアップを行います。「有効化」をクリックすると、Koda が Kane のインストールとアカウントの接続を提案します。手動で行うこともできます。

npm install -g @testmuai/kane-cli
kane-cli login --oauth        # opens your browser — use (or create) YOUR OWN Kane account

Kane アカウントについて — 必要なのはあなたのアカウントです

Koda には認証情報が一切含まれていません。Koda ユーザーはそれぞれ自分の Kane アカウントで認証します。

• 拡張機能の OAuth フローでは、あなたのブラウザーで Kane のログイン画面が開きます。新規ユーザーはそこで登録します
• セッションはあなたのマシンの ~/.testmuai/ にローカル保存され、同期もプロキシ経由の通信も行われません
• ブラウザーフローのクレジットは開発者のものではなく、あなたの Kane アカウントから使われます
• CI では、各リポジトリが KANE_USERNAME / KODA_ACCESS_KEY のようなシークレットを個別に設定します

Kane がなくても問題ありません。 Koda は機能を制限したモードで動作します。エンドポイントチェック、統合テスト、メモリ、レポートはすべて利用でき、ブラウザーフローは偽装されず、正直に SKIPPED と表示されます。

---

ターゲット URL — localhost、LAN、ホスト先

Koda はアプリが指定する URL を検証します。デフォルトは koda init の実行時に自動検出されます（一般的な開発用ポート：3000、5173、8080、8000、4200、5000 などを確認します）。次の 3 つの方法で上書きできます。

koda target https://myapp.vercel.app      # permanent — hosted URL, https auto-detected
koda target 192.168.1.5:8080              # LAN IP, http auto-detected
koda run --target https://preview-123.example.com   # one-off run
KODA_TARGET=https://staging.example.com   # per-session / CI via env

優先順位：--target フラグ → KODA_TARGET 環境変数 → .koda/config.json → 自動検出されたデフォルト。

CLI リファレンス

コマンド	内容
koda init [--force]	.koda/ を作成し、既存の動作を妨げない Git フックをインストールして、ターゲットを検出します
koda run [--project <path>] [--commit <sha>] [--target <url>] [--max-flows <n>]	コミットをすぐに検証します
koda report	最新のレポートを表示します
koda memory	プロジェクトメモリ（パターン、履歴、修正）を出力します
koda target <url>	新しいターゲット URL を検証、保存し、ヘルスチェックします
koda cicd [--force]	検証済みの GitHub Actions ワークフローを生成します（上書きは拒否されます）
koda doctor [--kane]	環境を確認します。--kane は Kane スキーマを実証的に検証します
koda mcp	MCP サーバーを起動します（stdio）

エージェントとの統合（MCP）

claude mcp add koda -- npx koda-verify mcp

Claude Code、Cursor、Codex、Gemini CLI、Windsurf、Zed など、あらゆる MCP クライアントで動作します。開発用チェックアウトでは、claude mcp add koda node /absolute/path/to/koda/mcp/server.js を実行します。

MCP ツール

ツール	目的
koda_verify	対象を絞った検証を実行します。エージェントが独自の影響分析（flows、endpoints、target、commit、max_flows）を指定します。コードはすでに読み込まれているため、LLM のコストも推測も必要ありません。Groq は MCP を使わない実行時のフォールバックに限り使用されます
koda_report	最新の完全な JSON レポート。判定、カバレッジ、証拠のパスを含みます
koda_memory	プロジェクトメモリ。繰り返し発生する失敗、修正の確度、修正までの時間を含みます
koda_setup_cicd	検証済みの GitHub Actions ワークフローを生成します

エージェントのループ

agent edits code → commits → hook fires koda run → report written
→ agent calls koda_verify (its own flows) / koda_report via MCP
→ reads the verdict → fixes what failed → commits again
→ memory marks the failure RESOLVED (with time-to-fix recorded)

エージェントがフローを指定した場合、レポートには analysis_source: 'agent' が記録されます。これは、ループがエージェント主導であることを検証できる証拠です。

---

レポート

実行するたびに、.koda/reports/ にタイムスタンプ付きのファイルが 2 つ生成されます。

.koda/reports/2026-08-30T14-35-28-909Z-9416b29.json   ← agent-readable
.koda/reports/2026-08-30T14-35-28-909Z-9416b29.md     ← human-readable

JSON には、コミットのメタデータ、analysis_source（agent / llm-fallback / fallback）、リスクレベル、証拠ファイルのパスを含むチェックごとの結果、メモリのコンテキスト（類似した失敗、パターン、修正の確度）、優先度と推奨される重点項目を含む action_required が記録されます。Markdown では、カバレッジの状態とともに PASS / FAIL / SKIPPED が明確に表示されます。

Kane のセッションイベントの生データは、フローごとに .koda/evidence/ に保存されます。

メモリ — 繰り返し発生する問題を記憶します

• 失敗したチェックにはそれぞれ安定したキーが割り当てられ、2 回以上再発した失敗はパターンになります
• 修正が反映され、チェックに合格すると、失敗は time_to_fix_ms とともに解決済みとして記録されます
• カバレッジ不足の検出結果（「app/page.js をカバーするテストがありません」）は、該当ファイルをカバーするテストが合格すると自動的に解決されます
• アプリがオフラインの場合にスキップされたチェックは、メモリを汚染しません
• 書き込みはアトミックに行われます。メモリファイルが破損していた場合は、削除されずに隔離されます

安全性の保証

• 非破壊的なフック — 既存の pre-commit / post-commit / pre-push フックは追記前にバックアップされます。Husky にも対応しており、マーカーを使って冪等性を確保します
• デフォルトで HTTP 読み取り専用 — GET / HEAD / OPTIONS のみ使用します。変更を伴うメソッドには、明示的なオプトイン（allow_mutating_methods: true）と、エージェントが宣言したエンドポイントの両方が必要です
• 結果に忠実 — アプリが停止している場合、チェックは SKIPPED となり、失敗として報告されることはありません。スキップされたチェックがメモリに記録されることもありません
• シークレットを同梱しません — パッケージに認証情報は一切含まれません。pre-commit ガードが、誤ってコミットされたキーをブロックします

CI/CD

koda cicd

検証済みテンプレートから .github/workflows/koda.yml を生成します。Node のセットアップ、npm ci、存在する場合のビルド、Kane CLI のインストールと GitHub シークレット（KANE_USERNAME、KANE_ACCESS_KEY）を使った認証、アプリの起動、ターゲットの起動待機、koda run --commit ${{ github.sha }} が含まれます。テンプレートを優先し、LLM が YAML を生成することはありません。--force を指定しない限り、上書きは拒否されます。

---

設定リファレンス（.koda/config.json）

{
  "kane": {
    "target": "http://localhost:3000",
    "headless": true,
    "max_steps": 30,
    "timeout_ms": 300000
  },
  "tests": {
    "browser_flows": true,
    "endpoint_tests": true,
    "integration_tests": true,
    "allow_mutating_methods": false,
    "expected_statuses": { "GET /api/health": [200] }
  },
  "notify": { "telegram": false, "discord": false }
}

環境変数

任意です。Koda はこれらを設定しなくても動作します。プロジェクトの .env から読み込み、存在しない場合は ~/.koda/.env を使用します（1 回設定すれば、どこでも使えます）。

GROQ_API_KEY=        # Groq fallback impact analysis (agent runs skip this entirely)
KODA_TARGET=         # override target URL (flag > env > config)
KODA_TEST_TOKEN=     # bearer token for authenticated endpoint checks
KODA_PROJECT=        # default project path for CLI/MCP
TELEGRAM_BOT_TOKEN=  # notifications
TELEGRAM_CHAT_ID=
DISCORD_WEBHOOK_URL=

開発

npm install
npm run check    # syntax-check all sources
npm test         # node:test suite
npm link         # local koda binary for development

実装仕様の全体については、koda-v3-build-guide.md を参照してください。

ライセンス

MIT