agentmako

agentmako es un motor de inteligencia de base de código local para herramientas de codificación IA.

Proporciona a agentes como Codex, Claude Code, Cursor y arneses locales un conjunto de herramientas MCP tipadas para comprender un proyecto antes de editarlo. Mako indexa tu repositorio, construye hechos respaldados por SQLite localmente, rastrea diagnósticos y notas de revisión, y devuelve paquetes de contexto estructurados en lugar de hacer que el agente redescubra todo con grep sin procesar.

Mako está diseñado para la primera etapa del trabajo de los agentes de codificación:

¿Qué archivos importan? ¿Qué rutas, símbolos, tablas, diagnósticos y hallazgos previos son relevantes? ¿Qué debería leer el agente a continuación?

Qué obtienes

• Servidor MCP para agentes de codificación: agentmako mcp

• Panel de control local: agentmako dashboard

• Paquetes de contexto deterministas: context_packet, reef_scout

• Herramientas de búsqueda y estructura de código: cross_search, live_text_search, ast_find_pattern, repo_map

• Hechos y hallazgos del Reef Engine a través del estado indexado, del árbol de trabajo y preparado (staged)

• Ingesta de diagnósticos de TypeScript, ESLint, Oxlint, Biome y git staged

• Instantáneas opcionales de esquemas de Postgres/Supabase e inspección de base de datos de solo lectura

• Comentarios de revisión de base de datos local para notas sobre tablas, RLS, disparadores (triggers), publicaciones, suscripciones y replicación

• Recuperación, reconocimientos y retroalimentación del agente para trabajos de revisión repetidos

Todo lo importante se ejecuta localmente. No se requiere ningún servicio alojado.

Related MCP server: Context Zero Engine

Instalación

Requiere Node.js 20 o superior.

npm install -g agentmako

Confirma que la CLI está disponible:

agentmako doctor

Deberías ver marcas de verificación verdes para la configuración y el servicio de API local.

¿Prefieres compilar desde el código fuente (por ejemplo, para contribuir)? Consulta Desarrollar desde el código fuente al final de este archivo.

Configuración recomendada

1. Adjunta tu proyecto real

Ve al proyecto que quieres que Mako comprenda:

cd C:/path/to/your/project

Adjúntalo e indexalo:

agentmako connect . --no-db

Usa --no-db para la primera ejecución. Esto hace que la ruta de inteligencia de código funcione antes de añadir el alcance de la base de datos.

2. Confirma que Mako ve el proyecto

agentmako status .
agentmako tool list

Ejecuta una consulta de exploración real:

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

Si eso devuelve candidatos clasificados, hechos o hallazgos, la configuración principal está funcionando.

3. Configura tu cliente MCP

Añade esto a la configuración de tu cliente MCP:

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

Reinicia el cliente MCP y confirma que el servidor mako-ai se inicia.

En el agente, comienza con una de estas herramientas:

• tool_search cuando necesites encontrar la herramienta Mako adecuada

• context_packet cuando tengas una tarea de codificación y quieras contexto inicial

• reef_scout cuando quieras hechos/hallazgos/historial del proyecto clasificados

• ask cuando tengas una pregunta sobre el repositorio en lenguaje natural

4. Opcional: usa el plugin de Claude Code

MCP simple funciona con Claude Code, pero el plugin incluido añade habilidades de Claude específicas de Mako e incluye la misma conexión agentmako mcp en mako-ai-claude-plugin/.mcp.json.

Requisitos previos:

• Claude Code instalado

• Node.js 20+ en PATH (el plugin ejecuta npx -y agentmako mcp, que obtiene el paquete agentmako publicado automáticamente; no se requiere una instalación global separada)

• Tu proyecto objetivo ya adjuntado con agentmako connect

Desde la raíz del repositorio de agentmako:

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

Dentro de Claude Code, ejecuta /mcp y confirma que mako-ai está conectado.

El plugin expone estas habilidades:

• /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

Usa el plugin cuando quieras que Claude Code cargue la guía específica de Mako sobre qué herramientas llamar y cómo interpretar sus resultados.

5. Opcional: inicia el panel de control

Desde tu proyecto objetivo:

agentmako dashboard .

Esto inicia la API local, el servicio de arnés y el panel de control web.

6. Opcional: añade conocimiento de Supabase/Postgres

Mako funciona sin base de datos. Añade esto solo después de que la inteligencia de código esté funcionando.

Para una configuración interactiva única:

agentmako connect .

Para CI o configuración mediante scripts usando una variable de entorno:

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

Luego actualiza y verifica la instantánea del esquema local:

agentmako refresh .
agentmako verify .

El modo interactivo almacena los secretos de la base de datos en el llavero de tu sistema operativo por defecto. La configuración del proyecto almacena referencias, no URLs de base de datos en texto plano.

Ciclo diario normal

Desde el proyecto objetivo:

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

Para comprobaciones de revisión preparadas (staged):

agentmako git precommit . --json

Para notas de revisión de base de datos:

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\"]}"

Desarrollar desde el código fuente

Si quieres modificar Mako, clona y compila en lugar de instalar desde npm.

Requisitos previos:

• Node.js 20 o superior

• Git

• Corepack (corepack enable, incluido con Node.js moderno)

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 hace que la CLI compilada desde el código fuente esté disponible como agentmako en tu PATH, reemplazando cualquier instalación global de npm. Vuelve a ejecutar corepack pnpm run build después de extraer cambios.

Para volver a la versión publicada: npm install -g agentmako.

Comprobaciones de desarrollo

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

Verificación completa:

corepack pnpm test

Diseño del repositorio

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

Más documentación

• Descripción general de herramientas

• Documentación de la CLI

• Reef Engine

• Plugin de Claude Code

• Guía para agentes para pegar en CLAUDE.md / AGENTS.md

• Contribución

• Política de seguridad

• Registro de cambios

Licencia

Apache-2.0. Consulta LICENSE.