agentmako

agentmako — это локально-ориентированный движок анализа кодовой базы для инструментов AI-программирования.

Он предоставляет таким агентам, как Codex, Claude Code, Cursor и локальным инструментам, типизированный набор инструментов MCP для понимания проекта перед внесением изменений. Mako индексирует ваш репозиторий, создает локальные факты на базе SQLite, отслеживает диагностику и заметки по ревью, а также возвращает структурированные пакеты контекста вместо того, чтобы заставлять агента заново искать всё с помощью обычного grep.

Mako создан для начального этапа работы AI-агента:

Какие файлы важны? Какие маршруты, символы, таблицы, диагностика и предыдущие находки актуальны? Что агенту следует прочитать дальше?

Что вы получаете

• MCP-сервер для AI-агентов: 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 и проверка БД в режиме только для чтения

• Локальные комментарии к ревью БД для заметок по таблицам, RLS, триггерам, публикациям, подпискам и репликации

• Вспоминание, подтверждения и обратная связь от агента для повторной работы по ревью

Всё важное работает локально. Хостинг-сервис не требуется.

Related MCP server: Graft

Установка

Требуется 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 и включает ту же связку agentmako mcp в mako-ai-claude-plugin/.mcp.json.

Предварительные требования:

• Установленный Claude Code

• Node.js 20+ в PATH (плагин запускает 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, сервис harness и веб-панель управления.

6. Опционально: добавьте поддержку Supabase/Postgres

Mako работает без базы данных. Добавляйте это только после того, как заработает анализ кода.

Для однократной интерактивной настройки:

agentmako connect .

Для CI или скриптовой настройки с использованием переменной окружения:

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

Затем обновите и проверьте локальный снимок схемы:

agentmako refresh .
agentmako verify .

Интерактивный режим по умолчанию хранит секреты базы данных в связке ключей вашей ОС. Конфигурация проекта хранит ссылки, а не 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, собранный из исходников, доступным как agentmako в вашем PATH, заменяя любую глобальную установку 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.