agentmako

Purpose

agentmako is a local-first codebase intelligence engine for AI coding tools. It lets coding agents such as Codex, Claude Code, Cursor, and local harnesses understand the project before editing code. Mako indexes the repository, builds fact data backed by local SQLite, tracks diagnostics and review notes, and answers questions in an evidence-backed way, rather than making the agent orchestrate a sprawling toolchain or repeatedly rediscover everything with raw grep.

It focuses on the "first mile" of coding-agent work: which files matter? Which routes, symbols, data tables, diagnostics, and existing findings are relevant? What should the agent read next?

Main capabilities

• MCP server for coding agents:agentmako mcp
• Local dashboard:agentmako dashboard
• Main project queries:reef_ask, covering code, database, findings, diagnostics, instructions, freshness, and literal checks
• Queryable workflow localization:mako_help
• Deterministic context expansion:context_packet
• On tool results, _hints, giving agents next-step hints specific to the result
• Central MCP annotations, enabling clients to distinguish safe reads, live reads, and local state changes
• Compact loop/fallback tools:reef_status、reef_verify、reef_impact、live_text_search、lint_files and tool_batch
• Reef Engine generates facts and findings in indexed, working-tree, and staged states
• Reef convention extraction for auth guards, runtime boundaries, generated paths, routing patterns, and schema usage
• Ingestion of TypeScript, ESLint, Oxlint, Biome, and staged git diagnostics
• Hot-reload .mako/rules YAML rule packs, including raw cross-file helper bypass rules implemented via canonicalHelper - Optional Postgres/Supabase schema snapshots and read-only database checks
• Local database review comments for notes on tables, RLS, triggers, publications, subscriptions, and replication
• Recall, confirmation, and agent feedback for repeated review work
• Everything important runs locally, with no hosted service required

Usage

Requires Node.js 20 or later. After confirming the CLI is available, you should see green checks for configuration and the local API service. Build-from-source instructions are at the bottom of the repository.

Quick start

1. Connect a real project: enter the project you want Mako to understand, and run the connect and index commands. On first run, use --no-dbto get the code intelligence path working first, then add database scope.
2. Confirm Mako can see the project: run a real Reef query once. If it returns evidence-backed answers, facts, findings, or follow-up queries, the core setup is working correctly.reef_ask plans code, database, persisted findings, diagnostics, and exact literal evidence. Application-flow questions lean toward files, routes, and finding evidence; RLS/schema questions lean toward database facts and review comments. You can also directly inspect project experience rules.
3. Configure the MCP client: add the configuration to the MCP client configuration, restart the client, and confirm that the mako-ai server starts. In the agent, use reef_askby default. The compact starting tool surface includes:reef_ask(project questions across code, database, findings, diagnostics, freshness, and reference literal checks),reef_status(maintenance questions, changed files, stale diagnostics, and watcher/schema health),reef_verify(completion gates for diagnostic freshness and unclosed items),reef_impact(impact scope and convention risks for changed files),mako_help(ordered workflow recipes with prefilled parameters),live_text_search(exact regex/glob inventory for the current disk),lint_files(bounded diagnostics and .mako/rules discoveries),tool_batch(mutually independent read-only follow-up operations),tool_search(used only when the compact tool surface points to a specific need, for discovering specialized routing, graph, DB, discovery, refresh, or context-expansion tools).
4. Optional: use the agent plugin. Pure MCP works anywhere, but the bundled plugin adds Mako-specific skills and includes the same agentmako mcp wiring. Before use, Claude Code must be installed, Node.js 20+ must be on PATH (the plugin runs npx -y agentmako mcp, automatically fetching the published agentmako package, no separate global install needed), and the target project must already be connected via agentmako connect . The skills exposed by the plugin include:/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. Use the plugin when you want Claude Code to load Mako-specific guidance (which tools to call and how to interpret results).
5. Optional: start the dashboard. After running it in the target project, it starts the local API, harness service, and web dashboard.
6. Optional: add Supabase/Postgres awareness. Mako works without a database; add this only after code intelligence is working. It supports one-time interactive setup, and also supports using environment variables in CI or scripted setup. Then refresh and verify the local schema snapshot. In interactive mode, database secrets are stored in the OS keychain by default, and the project config stores a reference rather than a plaintext DB URL.

Daily usage loop

Run the daily loop in the target project; check against staged review; check against database review notes.

Developing from source

If you want to modify Mako itself, you can clone and build instead of installing from npm. Node.js 20 or higher is required, along with Corepack (enabled via corepack enable , included in modern Node.js).npm link ./apps/cli makes the source-built CLI appear on PATH as agentmako , replacing any global npm install. After pulling changes, rerun corepack pnpm run build. To revert to the published version:npm install -g agentmako.

When to use

• Scenarios where a coding agent needs to quickly understand project structure, key files and related symbols, routes, and data tables before editing
• Scenarios requiring evidence-backed queries across code, database schema, diagnostics, and existing findings
• Scenarios requiring tracking of diagnostics, review notes, and repeated review work
• Scenarios for codebase intelligence analysis that you want to run locally without a hosted service

Limitations

• Requires Node.js 20 or higher
• Requires Node.js 20+ on PATH (when using the plugin)
• Database-related capabilities are optional, and Postgres/Supabase checks are read-only
• In interactive mode, database secrets are stored in the OS keychain by default, and the project config stores a reference rather than plaintext
• Licensed under Apache-2.0, see LICENSE for details
• Other feature details, pricing, and platform support are not yet provided