# agentmako

> Local-first Model Context Protocol (MCP) server that gives AI coding agents
> typed, deterministic context about your codebase — instead of letting them
> grep blind. Compatible with Claude Code, Codex CLI, Cursor, and Cline.

agentmako is an open-source MCP server (Apache-2.0) that indexes your repo
into local SQLite, tracks ESLint/TypeScript diagnostics, snapshots your
Postgres or Supabase schema, and returns deterministic "context packets"
via the stdio Model Context Protocol. The Reef Engine layer adds durable
findings, freshness tracking, and cross-session memory.

Compatible with: Claude Code, Codex CLI, Cursor, Cline, Continue.dev, and
any other MCP-compliant client. Requires Node.js 20 or newer. No hosted
service — everything runs locally.

Install: `npm install -g agentmako`

## Quickstart

- [Install and attach a project](https://agentmako.drhalto.com/#install): four commands, ~60 seconds
- [CLAUDE.md / AGENTS.md template](https://agentmako.drhalto.com/CLAUDE.md): drop-in playbook telling agents when to use Mako tools
- [GitHub repository](https://github.com/drhalto/agentmako): source code, issues, contributions
- [npm package](https://www.npmjs.com/package/agentmako): published releases

## Setup guides per coding agent

- [Claude Code setup](https://agentmako.drhalto.com/docs/claude-code.html): plain MCP wiring or bundled `mako-ai` plugin with `/mako-ai` skills
- [Codex CLI setup](https://agentmako.drhalto.com/docs/codex.html): TOML config in `~/.codex/config.toml`
- [Cursor setup](https://agentmako.drhalto.com/docs/cursor.html): per-project `.cursor/mcp.json` or global config
- [Cline (VS Code) setup](https://agentmako.drhalto.com/docs/cline.html): paste into Cline MCP Servers settings

## Concepts

- [What is MCP (Model Context Protocol)?](https://agentmako.drhalto.com/docs/concepts/mcp.html): how MCP works, why it exists, what makes it different from a regular API
- [What is a context packet?](https://agentmako.drhalto.com/docs/concepts/context-packets.html): ranked, source-labeled context returned by `context_packet`
- [What is the Reef Engine?](https://agentmako.drhalto.com/docs/concepts/reef-engine.html): durable facts and findings layer with freshness tracking
- [Freshness model](https://agentmako.drhalto.com/docs/concepts/freshness.html): how Mako labels evidence as live, fresh_indexed, stale, contradicted, or unknown

## Tool catalog

agentmako exposes dozens of typed MCP tools across six categories. Use the generated tool catalog for the exact current count:

- **Context**: `context_packet`, `reef_scout`, `reef_inspect`, `evidence_confidence`, `tool_batch`
- **Code intel**: `repo_map`, `cross_search`, `ast_find_pattern`, `live_text_search`, `symbols_of`, `imports_impact`
- **Reef Engine**: `project_findings`, `file_findings`, `project_open_loops`, `verification_state`, `project_conventions`, `project_index_refresh`
- **Database**: `db_table_schema`, `db_rls`, `db_rpc`, `tenant_leak_audit`, `schema_usage`, `db_reef_refresh`
- **Trace & flow**: `route_trace`, `trace_file`, `trace_table`, `flow_map`, `graph_path`, `auth_path`
- **Diagnostics**: `typescript_diagnostics`, `eslint_diagnostics`, `lint_files`, `git_precommit_check`, `finding_ack`

Full catalog: https://agentmako.drhalto.com/#tools

## Common questions

- [How do I add an MCP server to Claude Code?](https://agentmako.drhalto.com/docs/faq.html#how-do-i-add-mcp-to-claude-code)
- [How do I add an MCP server to Cursor?](https://agentmako.drhalto.com/docs/faq.html#how-do-i-add-mcp-to-cursor)
- [How do I add an MCP server to Codex CLI?](https://agentmako.drhalto.com/docs/faq.html#how-do-i-add-mcp-to-codex)
- [Why does my AI coding agent rediscover the codebase every prompt?](https://agentmako.drhalto.com/docs/faq.html#why-rediscover)
- [How do I make Claude Code aware of my Postgres schema?](https://agentmako.drhalto.com/docs/faq.html#postgres-aware)
- [What's the best way to give an AI coding agent codebase context?](https://agentmako.drhalto.com/docs/faq.html#best-context)
- [Is agentmako free?](https://agentmako.drhalto.com/docs/faq.html#is-it-free)
- [Does agentmako work offline?](https://agentmako.drhalto.com/docs/faq.html#offline)

## Recipes

- [Trace an auth flow with agentmako](https://agentmako.drhalto.com/docs/recipes/auth-flow-tracing.html)
- [Refactor safely with AI coding agents](https://agentmako.drhalto.com/docs/recipes/safe-refactoring.html)
- [Make AI agents schema-aware (Postgres / Supabase)](https://agentmako.drhalto.com/docs/recipes/database-aware-edits.html)
- [Debug tricky bugs with `context_packet`](https://agentmako.drhalto.com/docs/recipes/debugging-with-context.html)

## Optional

- [Changelog](https://github.com/drhalto/agentmako/blob/main/CHANGELOG.md)
- [Contributing](https://github.com/drhalto/agentmako/blob/main/CONTRIBUTING.md)
- [Security policy](https://github.com/drhalto/agentmako/blob/main/SECURITY.md)
- [License — Apache-2.0](https://github.com/drhalto/agentmako/blob/main/LICENSE)