agentmako

agentmako

agentmako は、AI コーディングツール向けのローカルファーストなコードベース・インテリジェンスエンジンです。

Codex、Claude Code、Cursor、ローカルハーネスなどのエージェントに、プロジェクトを編集する前に理解するための、Reef を中心としたコンパクトなツール群を提供します。Mako はリポジトリをインデックス化し、SQLite を基盤とするローカルのファクトを構築し、診断情報やレビューのメモを追跡します。また、エージェントに幅広いツールチェーンを調整させたり、生の grep ですべてを再発見させたりするのではなく、根拠に基づく質問への回答を提供します。

Mako は、コーディングエージェントの作業の第一段階を支援するために作られています。

重要なファイルはどれですか？ 関連するルート、シンボル、テーブル、診断情報、過去の調査結果は何ですか？ エージェントは次に何を読むべきですか？

利用できる機能

• コーディングエージェント向け MCP サーバー：agentmako mcp
• ローカルダッシュボード：agentmako dashboard
• プロジェクトへの主要なクエリ：コード、データベース、調査結果、診断情報、指示、鮮度、リテラルチェックを横断する reef_ask
• クエリ可能なワークフローの案内：mako_help
• 決定論的なコンテキストの展開：context_packet
• ツールの結果に付与される _hints により、エージェントに結果に応じた次の手順を提示
• クライアントが安全な読み取り、ライブ読み取り、ローカル状態の変更を区別できる、MCP アノテーションの一元管理
• コンパクトなループ／フォールバック用ツール：reef_status、reef_verify、reef_impact、live_text_search、lint_files、tool_batch
• インデックス済みの状態、作業ツリー、ステージ済みの状態にまたがる、Reef Engine のファクトと調査結果
• 認証ガード、ランタイム境界、生成パス、ルートパターン、スキーマ利用に関する Reef の規約抽出
• TypeScript、ESLint、Oxlint、Biome、ステージ済み git の診断情報の取り込み
• canonicalHelper を使った、ファイル間のヘルパーバイパスに関する基本ルールを含む、ホットリロード対応の .mako/rules YAML ルールパック
• オプションの Postgres／Supabase スキーマスナップショットと読み取り専用の DB 検査
• テーブル、RLS、トリガー、パブリケーション、サブスクリプション、レプリケーションに関するメモを残す、ローカル DB レビューコメント
• 繰り返し行うレビュー作業に役立つ、記憶、確認応答、エージェントのフィードバック

重要な機能はすべてローカルで動作します。ホスト型サービスは不要です。

インストール

Node.js 20 以降が必要です。

npm install -g agentmako

CLI が利用可能であることを確認します。

agentmako --version
agentmako doctor

設定とローカル API サービスに緑色のチェックマークが表示されます。

ソースからビルドして（たとえば、コントリビュートするために）使いたい場合は、ファイル末尾の ソースから開発するを参照してください。

最短セットアップ手順

1. 実際のプロジェクトを登録する

Mako に理解させたいプロジェクトに移動します。

cd C:/path/to/your/project

プロジェクトを登録してインデックス化します。

agentmako connect . --no-db

初回の実行では --no-db を指定してください。これにより、データベースの範囲を追加する前にコードインテリジェンスの経路を動作させられます。

2. Mako がプロジェクトを認識していることを確認する

agentmako status .
agentmako tool list

実際に Reef クエリを実行します。

agentmako --json tool call . reef_ask "{\"question\":\"where should I inspect auth route state?\"}"

根拠に基づく回答、ファクト、調査結果、または次のクエリが返されれば、基本的なセットアップは完了です。

reef_ask は、コード、データベース、永続的な調査結果、診断情報、正確なリテラルの根拠に基づいて計画します。アプリのフローに関する質問ではファイル、ルート、調査結果の根拠を優先し、RLS／スキーマに関する質問ではデータベースのファクトとレビューコメントを優先します。プロジェクトの経験則を直接確認するには、次を実行します。

agentmako --json tool call . project_conventions "{}"

3. MCP クライアントを設定する

MCP クライアントの設定に次を追加します。

{
  "mcpServers": {
    "mako-ai": {
      "command": "agentmako",
      "args": ["mcp"]
    }
  }
}

MCP クライアントを再起動し、mako-ai サーバーが起動することを確認します。

エージェントでは、デフォルトで reef_ask を使用します。コンパクトな基本セットは次のとおりです。

• reef_ask：コード、データベース、検出事項、診断、鮮度、引用符で囲まれたリテラルの確認に関するプロジェクトの質問
• reef_status：管理対象の問題、変更ファイル、古い診断、ウォッチャー／スキーマの健全性
• reef_verify：診断の鮮度と未解決の作業項目に関する完了ゲート
• reef_impact：変更ファイルの影響範囲と規約上のリスク
• mako_help：引数が事前入力された、順序付きのワークフローレシピ
• live_text_search：現在のディスク上にある内容を対象とした、正確な正規表現／glob の一覧検索
• lint_files：対象を限定した診断と .mako/rules の検出事項
• tool_batch：独立した読み取り専用の追加確認
• tool_search：コンパクトな基本セットで具体的な必要性が示された場合に限り、ルート、グラフ、DB、検出事項、更新、コンテキスト拡張の専用ツールを見つけます

4. オプション：エージェントプラグインを使用する

通常の MCP はどこでも動作しますが、同梱のプラグインを使うと、Mako 固有のスキルが追加され、同じ agentmako mcp の設定も含まれます。

前提条件：

• Claude Code がインストールされていること
• PATH 上に Node.js 20 以降があること（プラグインは npx -y agentmako mcp を実行し、公開済みの agentmako パッケージを自動で取得するため、グローバルへの個別インストールは不要です）
• 対象プロジェクトが agentmako connect ですでに接続されていること

Claude Code の安定版のパス：

claude plugin validate .\mako-ai-claude-plugin
claude --plugin-dir .\mako-ai-claude-plugin

新しく生成されたプラグインのレイアウト：

claude plugin validate ./plugins/claude-code
codex marketplace add ./plugins
ln -s "$(pwd)/plugins/cursor" ~/.cursor/plugins/local/mako-ai
gemini extensions install ./plugins/gemini

エージェント内で、mako-ai MCP サーバーが接続されていることを確認します。

プラグインは次のスキルを公開します。

• /mako-ai:mako-guide
• /mako-ai:mako-discovery
• /mako-ai:mako-trace
• /mako-ai:mako-neighborhoods
• /mako-ai:mako-graph
• /mako-ai:mako-database
• /mako-ai:mako-code-intel
• /mako-ai:mako-workflow

呼び出すツールや結果の解釈方法について、Claude Code に Mako 固有のガイダンスを読み込ませたい場合は、プラグインを使用してください。

5. オプション：ダッシュボードを起動する

対象プロジェクトで次を実行します。

agentmako dashboard .

これにより、ローカル API、ハーネスサービス、Web ダッシュボードが起動します。

6. オプション：Supabase/Postgres の認識機能を追加する

Mako はデータベースなしでも動作します。コードインテリジェンスが機能するようになってから追加してください。

一度限りの対話式セットアップを行う場合：

agentmako connect .

環境変数を使って CI またはスクリプトからセットアップする場合：

set DATABASE_URL=postgres://...
agentmako connect . --db-env DATABASE_URL --yes

次に、ローカルのスキーマスナップショットを更新して検証します。

agentmako refresh .
agentmako verify .

対話式モードでは、データベースのシークレットはデフォルトで OS のキーチェーンに保存されます。プロジェクト設定には参照が保存され、DB URL が平文で保存されることはありません。

通常の日次ループ

対象プロジェクトで次を実行します。

agentmako status .
agentmako dashboard .
agentmako --json tool call . context_packet "{\"query\":\"fix the broken auth callback route\"}"

ステージ済みのレビュー確認を行う場合：

agentmako git precommit . --json

データベースのレビュー記録を確認する場合：

agentmako --json tool call . db_review_comment "{\"objectType\":\"replication\",\"objectName\":\"supabase_database_replication\",\"category\":\"review\",\"comment\":\"Check publication coverage before relying on realtime events.\",\"tags\":[\"supabase\",\"replication\"]}"

ソースから開発する

Mako 自体を開発する場合は、npm からインストールするのではなく、クローンしてビルドしてください。

前提条件：

• Node.js 20 以降
• Git
• Corepack（corepack enable。最新の Node.js に同梱）

git clone https://github.com/drhalto/agentmako.git
cd agentmako
corepack pnpm install
corepack pnpm run build
npm link ./apps/cli

npm link ./apps/cli を実行すると、ソースからビルドした CLI が PATH 上で agentmako として使えるようになり、既存のグローバル npm インストールに置き換わります。変更をプルした後は、corepack pnpm run build を再実行してください。

公開版に戻すには、npm install -g agentmako を実行します。

開発時のチェック

corepack pnpm run typecheck
corepack pnpm run build
corepack pnpm run test:smoke:reef-tooling
corepack pnpm run test:smoke:reef-model-facing-views

完全な検証：

corepack pnpm test

リポジトリの構成

apps/
  cli/              agentmako CLI and MCP entrypoint (the published package)
  web/              local dashboard
packages/
  contracts/        public TypeScript contracts and tool schemas
  config/           shared config helpers
  logger/           shared logger
  sdk/              programmatic SDK
  store/            SQLite stores, migrations, and query helpers
  tools/            shared tool implementations
  harness-core/     local agent harness runtime
  harness-tools/    action tools available to the harness
  harness-contracts/ harness contracts and provider catalog
services/
  api/              local API and MCP transports
  engine/           Reef Engine fact/finding pipeline
  harness/          local harness HTTP service
  indexer/          repo and schema indexing logic
  worker/           background worker
extensions/         provider and integration packages
storage/            schema migrations, models, queries
test/smoke/         smoke coverage
mako-ai-claude-plugin/ Claude Code plugin with Mako skills

その他のドキュメント

• ツールの概要
• CLI ドキュメント
• Reef Engine
• ツールの注釈
• 書き込みツールの規約
• Claude Code プラグイン
• CLAUDE.md / AGENTS.md に貼り付けるエージェント向けガイダンス
• 貢献方法
• セキュリティポリシー
• 変更履歴

ライセンス

Apache-2.0。LICENSE を参照してください。