{
  "markdown": "<p align=\"center\">\n  <img src=\"apps/web/public/agentmako.png\" alt=\"agentmako logo\" width=\"180\" />\n</p>\n\n# agentmako\n\n[![npm version](https://img.shields.io/npm/v/agentmako.svg?logo=npm)](https://www.npmjs.com/package/agentmako)\n[![Smoke Tests](https://github.com/drhalto/agentmako/actions/workflows/smoke.yml/badge.svg)](https://github.com/drhalto/agentmako/actions/workflows/smoke.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\n[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)\n[![agentmako MCP server](https://glama.ai/mcp/servers/drhalto/agentmako/badges/score.svg)](https://glama.ai/mcp/servers/drhalto/agentmako)\n\nagentmako is a local-first codebase intelligence engine for AI coding\ntools.\n\nIt gives agents like Codex, Claude Code, Cursor, and local harnesses a\ncompact Reef-first tool surface for understanding a project before they edit\nit. Mako indexes your repo, builds local SQLite-backed facts, tracks\ndiagnostics and review notes, and answers evidence-backed questions instead of\nmaking the agent orchestrate broad tool chains or rediscover everything with\nraw grep.\n\nMako is built for the first mile of coding-agent work:\n\n> What files matter? What routes, symbols, tables, diagnostics, and prior\n> findings are relevant? What should the agent read next?\n\n## What You Get\n\n- MCP server for coding agents: `agentmako mcp`\n- Local dashboard: `agentmako dashboard`\n- Primary project query: `reef_ask` across code, database, findings,\n  diagnostics, instructions, freshness, and literal checks\n- Queryable workflow orientation: `mako_help`\n- Deterministic context expansion: `context_packet`\n- `_hints` on tool results so agents get result-specific next steps\n- Central MCP annotations so clients can distinguish safe reads, live reads,\n  and local-state mutations\n- Compact loop/fallback tools: `reef_status`, `reef_verify`, `reef_impact`,\n  `live_text_search`, `lint_files`, and `tool_batch`\n- [Reef Engine](./docs/reef-engine.md) facts and findings across indexed,\n  working-tree, and staged state\n- Reef convention extraction for auth guards, runtime boundaries, generated\n  paths, route patterns, and schema usage\n- TypeScript, ESLint, Oxlint, Biome, and staged git diagnostic ingestion\n- Hot-reloaded `.mako/rules` YAML rule packs, including primitive\n  cross-file helper-bypass rules via `canonicalHelper`\n- Optional Postgres/Supabase schema snapshots and read-only DB inspection\n- Local DB review comments for notes on tables, RLS, triggers,\n  publications, subscriptions, and replication\n- Recall, acknowledgements, and agent feedback for repeated review work\n\nEverything important runs locally. No hosted service is required.\n\n## Install\n\nRequires **Node.js 20 or newer**.\n\n```bash\nnpm install -g agentmako\n```\n\nConfirm the CLI is available:\n\n```bash\nagentmako --version\nagentmako doctor\n```\n\nYou should see green checks for configuration and the local API service.\n\n> Prefer to build from source (e.g. to contribute)?  See\n> [Develop From Source](#develop-from-source) at the bottom of this\n> file.\n\n## Happy Path Setup\n\n### 1. Attach your real project\n\nGo to the project you want Mako to understand:\n\n```bash\ncd C:/path/to/your/project\n```\n\nAttach and index it:\n\n```bash\nagentmako connect . --no-db\n```\n\nUse `--no-db` for the first run. It gets the code intelligence path\nworking before adding database scope.\n\n### 2. Confirm Mako sees the project\n\n```bash\nagentmako status .\nagentmako tool list\n```\n\nRun a real Reef query:\n\n```bash\nagentmako --json tool call . reef_ask \"{\\\"question\\\":\\\"where should I inspect auth route state?\\\"}\"\n```\n\nIf that returns an evidence-backed answer, facts, findings, or next queries,\nthe core setup is working.\n\n`reef_ask` plans over code, database, durable findings, diagnostics, and exact\nliteral evidence. App-flow questions favor file, route, and finding evidence;\nRLS/schema questions favor database facts and review comments. To inspect\nproject rules of thumb directly:\n\n```bash\nagentmako --json tool call . project_conventions \"{}\"\n```\n\n### 3. Configure your MCP client\n\nAdd this to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"mako-ai\": {\n      \"command\": \"agentmako\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nRestart the MCP client and confirm the `mako-ai` server starts.\n\nIn the agent, default to `reef_ask`. The compact starting surface is:\n\n- `reef_ask` for project questions across code, database, findings,\n  diagnostics, freshness, and quoted literal checks\n- `reef_status` for maintained issues, changed files, stale diagnostics, and\n  watcher/schema health\n- `reef_verify` for the completion gate over diagnostic freshness and open loops\n- `reef_impact` for changed-file blast radius and convention risks\n- `mako_help` for an ordered workflow recipe with prefilled arguments\n- `live_text_search` for exact current-disk regex/glob inventories\n- `lint_files` for bounded diagnostics and `.mako/rules` findings\n- `tool_batch` for independent read-only follow-ups\n- `tool_search` to discover specialized route, graph, DB, finding, refresh, or\n  context-expansion tools only when the compact surface points at a concrete\n  need\n\n### 4. Optional: use an agent plugin\n\nPlain MCP works anywhere, but the bundled plugins add Mako-specific skills and\ninclude the same `agentmako mcp` wiring.\n\nPrerequisites:\n\n- Claude Code installed\n- Node.js 20+ on `PATH` (the plugin runs `npx -y agentmako mcp`, which fetches\n  the published `agentmako` package automatically — no separate global install\n  required)\n- Your target project already attached with `agentmako connect`\n\nClaude Code stable path:\n\n```powershell\nclaude plugin validate .\\mako-ai-claude-plugin\nclaude --plugin-dir .\\mako-ai-claude-plugin\n```\n\nNew generated plugin layouts:\n\n```bash\nclaude plugin validate ./plugins/claude-code\ncodex marketplace add ./plugins\nln -s \"$(pwd)/plugins/cursor\" ~/.cursor/plugins/local/mako-ai\ngemini extensions install ./plugins/gemini\n```\n\nInside the agent, confirm the `mako-ai` MCP server is connected.\n\nThe plugin exposes these skills:\n\n- `/mako-ai:mako-guide`\n- `/mako-ai:mako-discovery`\n- `/mako-ai:mako-trace`\n- `/mako-ai:mako-neighborhoods`\n- `/mako-ai:mako-graph`\n- `/mako-ai:mako-database`\n- `/mako-ai:mako-code-intel`\n- `/mako-ai:mako-workflow`\n\nUse the plugin when you want Claude Code to load Mako-specific guidance for\nwhich tools to call and how to interpret their results.\n\n### 5. Optional: launch the dashboard\n\nFrom your target project:\n\n```bash\nagentmako dashboard .\n```\n\nThis starts the local API, harness service, and web dashboard.\n\n### 6. Optional: add Supabase/Postgres awareness\n\nMako works without a database. Add this only after code intelligence is\nworking.\n\nFor a one-time interactive setup:\n\n```bash\nagentmako connect .\n```\n\nFor CI or scripted setup using an environment variable:\n\n```bash\nset DATABASE_URL=postgres://...\nagentmako connect . --db-env DATABASE_URL --yes\n```\n\nThen refresh and verify the local schema snapshot:\n\n```bash\nagentmako refresh .\nagentmako verify .\n```\n\nInteractive mode stores database secrets in your OS keychain by default.\nProject config stores references, not plaintext DB URLs.\n\n## Normal Daily Loop\n\nFrom the target project:\n\n```bash\nagentmako status .\nagentmako dashboard .\nagentmako --json tool call . context_packet \"{\\\"query\\\":\\\"fix the broken auth callback route\\\"}\"\n```\n\nFor staged review checks:\n\n```bash\nagentmako git precommit . --json\n```\n\nFor database review notes:\n\n```bash\nagentmako --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\\\"]}\"\n```\n\n## Develop From Source\n\nIf you want to hack on Mako itself, clone and build instead of installing\nfrom npm.\n\nPrerequisites:\n\n- Node.js 20 or newer\n- Git\n- Corepack (`corepack enable`, included with modern Node.js)\n\n```bash\ngit clone https://github.com/drhalto/agentmako.git\ncd agentmako\ncorepack pnpm install\ncorepack pnpm run build\nnpm link ./apps/cli\n```\n\n`npm link ./apps/cli` makes the source-built CLI available as\n`agentmako` on your `PATH`, replacing any global npm install. Re-run\n`corepack pnpm run build` after pulling changes.\n\nTo go back to the published version: `npm install -g agentmako`.\n\n### Development Checks\n\n```bash\ncorepack pnpm run typecheck\ncorepack pnpm run build\ncorepack pnpm run test:smoke:reef-tooling\ncorepack pnpm run test:smoke:reef-model-facing-views\n```\n\nFull verification:\n\n```bash\ncorepack pnpm test\n```\n\n## Repository Layout\n\n```text\napps/\n  cli/              agentmako CLI and MCP entrypoint (the published package)\n  web/              local dashboard\npackages/\n  contracts/        public TypeScript contracts and tool schemas\n  config/           shared config helpers\n  logger/           shared logger\n  sdk/              programmatic SDK\n  store/            SQLite stores, migrations, and query helpers\n  tools/            shared tool implementations\n  harness-core/     local agent harness runtime\n  harness-tools/    action tools available to the harness\n  harness-contracts/ harness contracts and provider catalog\nservices/\n  api/              local API and MCP transports\n  engine/           Reef Engine fact/finding pipeline\n  harness/          local harness HTTP service\n  indexer/          repo and schema indexing logic\n  worker/           background worker\nextensions/         provider and integration packages\nstorage/            schema migrations, models, queries\ntest/smoke/         smoke coverage\nmako-ai-claude-plugin/ Claude Code plugin with Mako skills\n```\n\n## More Docs\n\n- [Tool overview](./TOOLS.md)\n- [CLI docs](./apps/cli/README.md)\n- [Reef Engine](./docs/reef-engine.md)\n- [Tool annotations](./docs/tool-annotations.md)\n- [Write tool convention](./docs/write-tool-convention.md)\n- [Claude Code plugin](./mako-ai-claude-plugin/README.md)\n- [Agent guidance to paste into CLAUDE.md / AGENTS.md](./AGENTS.md)\n- [Contributing](./CONTRIBUTING.md)\n- [Security policy](./SECURITY.md)\n- [Changelog](./CHANGELOG.md)\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n",
  "bytes": 10208,
  "sha": "ecd53cae6fff894adfc513f1d95213334b37142c2f921455f6050c0d65e3ce77",
  "repo_slug": "drhalto/agentmako",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_drhalto_agentmako_4544f052/readme"
}