agentmako

agentmako

agentmako 是一款本地优先的代码库智能引擎，面向 AI 编码工具。

它为 Codex、Claude Code、Cursor 等 Agent 和本地运行环境提供精简的 Reef 优先工具界面，帮助它们在修改项目前先了解项目。Mako 会为代码库建立索引，构建由本地 SQLite 支撑的事实库，跟踪诊断信息和审查备注，并基于证据回答问题，而不必让 Agent 编排繁杂的工具链，或通过原始 grep 重新发现所有内容。

Mako 专为编码 Agent 工作的起步阶段打造：

哪些文件最重要？哪些路由、符号、表、诊断信息和过往发现与当前任务相关？Agent 接下来应该阅读什么？

你将获得

• 面向编码 Agent 的 MCP 服务：agentmako mcp
• 本地仪表板：agentmako dashboard
• 主要项目查询：reef_ask，覆盖代码、数据库、发现项、诊断信息、指令、新鲜度和字面量检查
• 可查询的工作流指引：mako_help
• 确定性的上下文扩展：context_packet
• 工具结果中包含 _hints，为 Agent 提供针对结果的后续步骤
• 集中的 MCP 注解，让客户端能够区分安全读取、实时读取和本地状态变更
• 精简的循环／回退工具：reef_status、reef_verify、reef_impact、live_text_search、lint_files 和 tool_batch
• Reef Engine 提供横跨已索引、工作树和暂存状态的事实与发现项
• 提取 Reef 约定，涵盖身份验证防护、运行时边界、生成路径、路由模式和架构用法
• 导入 TypeScript、ESLint、Oxlint、Biome 和已暂存 git 诊断信息
• 热重载 .mako/rules YAML 规则包，包括通过 canonicalHelper 实现的基础跨文件辅助函数绕过规则
• 可选的 Postgres/Supabase 架构快照和只读数据库检查
• 本地数据库审查评论，可记录有关表、RLS、触发器、发布、订阅和复制的备注
• 支持重复审查工作的回忆、确认和 Agent 反馈

所有重要功能都在本地运行，无需托管服务。

安装

需要 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 服务已启动。

在 Agent 中，默认使用 reef_ask。精简的起步工具集如下：

• reef_ask：解答有关代码、数据库、发现项、诊断、时效性和带引号字面值检查的问题
• reef_status：检查已维护的问题、变更文件、过时诊断以及监视器／架构健康状况
• reef_verify：根据诊断时效性和未解决事项执行完成门槛检查
• reef_impact：分析变更文件的影响范围和约定风险
• mako_help：提供预填参数的有序工作流方案
• live_text_search：针对当前磁盘执行精确的正则表达式／glob 清单搜索
• lint_files：检查限定范围内的诊断和 .mako/rules 发现项
• tool_batch：执行相互独立的只读后续操作
• tool_search：仅当精简工具集指出具体需求时，才用于发现专用的路由、图、数据库、发现项、刷新或上下文扩展工具

4. 可选：使用 Agent 插件

普通 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

在 Agent 中，确认 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、harness 服务和 Web 仪表板。

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 在 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 的 Agent 指南
• 贡献指南
• 安全策略
• 更新日志

许可证

Apache-2.0。请参阅 LICENSE。