agentmako

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

Codex、Claude Code、Cursor、およびローカル環境などのエージェントに対し、編集前にプロジェクトを理解するための型定義されたMCPツールセットを提供します。Makoはリポジトリをインデックス化し、SQLiteベースの事実情報をローカルに構築し、診断結果やレビューメモを追跡します。また、エージェントがraw grepですべてを再発見させるのではなく、構造化されたコンテキストパケットを返します。

Makoは、コーディングエージェントの作業の初期段階（ファーストマイル）のために構築されています：

どのファイルが重要か？どのルート、シンボル、テーブル、診断、以前の調査結果が関連しているか？エージェントは次に何を読み込むべきか？

提供機能

• コーディングエージェント用MCPサーバー: agentmako mcp

• ローカルダッシュボード: agentmako dashboard

• 決定論的なコンテキストパケット: context_packet, reef_scout

• コード検索および構造化ツール: cross_search, live_text_search, ast_find_pattern, repo_map

• Reef Engine による、インデックス済み、ワーキングツリー、ステージング状態にわたる事実と調査結果

• TypeScript、ESLint、Oxlint、Biome、およびステージングされたgit診断の取り込み

• オプションのPostgres/Supabaseスキーマスナップショットと読み取り専用DB検査

• テーブル、RLS、トリガー、パブリケーション、サブスクリプション、レプリケーションに関するメモのためのローカルDBレビューコメント

• 繰り返しレビュー作業のためのリコール、承認、エージェントフィードバック

重要なものはすべてローカルで実行されます。ホスト型サービスは不要です。

Related MCP server: Context Zero Engine

インストール

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

npm install -g agentmako

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

agentmako doctor

設定とローカルAPIサービスに対して緑色のチェックマークが表示されるはずです。

ソースからビルドしたい場合（貢献する場合など）は、このファイルの最後にある Develop From Source を参照してください。

基本的なセットアップ

1. 実際のプロジェクトをアタッチする

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

cd C:/path/to/your/project

アタッチしてインデックス化します：

agentmako connect . --no-db

最初の実行時は --no-db を使用してください。データベーススコープを追加する前に、コードインテリジェンスのパスを機能させます。

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

agentmako status .
agentmako tool list

実際のスカウトクエリを実行します：

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

これでランク付けされた候補、事実、または調査結果が返されれば、コアセットアップは機能しています。

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

MCPクライアントの設定に以下を追加します：

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

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

エージェント内で、以下のいずれかのツールから開始します：

• tool_search: 適切なMakoツールを見つける必要がある場合

• context_packet: コーディングタスクがあり、開始コンテキストが必要な場合

• reef_scout: ランク付けされたプロジェクトの事実/調査結果/履歴が必要な場合

• ask: 自然言語でリポジトリに関する質問がある場合

4. オプション: Claude Codeプラグインを使用する

通常のMCPはClaude Codeで動作しますが、バンドルされているプラグインを追加すると、Mako固有のClaudeスキルが追加され、mako-ai-claude-plugin/.mcp.json に同じ agentmako mcp の配線が含まれます。

前提条件:

• Claude Codeがインストールされていること

• PATH に Node.js 20+ があること（プラグインは npx -y agentmako mcp を実行し、公開されている agentmako パッケージを自動的に取得します。個別のグローバルインストールは不要です）

• 対象プロジェクトがすでに agentmako connect でアタッチされていること

agentmakoリポジトリのルートから：

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

Claude Code内で /mcp を実行し、mako-ai が接続されていることを確認します。

プラグインは以下のスキルを公開します：

• /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はデータベースなしでも動作します。コードインテリジェンスが機能した後にのみこれを追加してください。

1回限りの対話型セットアップ：

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 を参照してください。