{"id":49298659,"url":"https://github.com/drhalto/agentmako","last_synced_at":"2026-05-01T10:00:49.041Z","repository":{"id":353884262,"uuid":"1221282235","full_name":"drhalto/agentmako","owner":"drhalto","description":"Local-first MCP server that gives coding agents structured context packets, code/schema facts, and diagnostics - backed by a local SQLite store.","archived":false,"fork":false,"pushed_at":"2026-04-26T15:30:37.000Z","size":5821,"stargazers_count":15,"open_issues_count":1,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T07:03:23.783Z","etag":null,"topics":["ai-coding","claude-code","claude-code-plugin","code-intelligence","codex","cursor","developer-tools","llm-tools","local-first","mcp","mcp-server","model-context-protocol","opencode","sqlite","typescript","vibecoding"],"latest_commit_sha":null,"homepage":"https://agentmako.drhalto.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drhalto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-26T01:47:38.000Z","updated_at":"2026-04-27T18:31:03.000Z","dependencies_parsed_at":"2026-04-28T07:01:25.610Z","dependency_job_id":null,"html_url":"https://github.com/drhalto/agentmako","commit_stats":null,"previous_names":["drhalto/agentmako"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/drhalto/agentmako","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhalto%2Fagentmako","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhalto%2Fagentmako/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhalto%2Fagentmako/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhalto%2Fagentmako/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drhalto","download_url":"https://codeload.github.com/drhalto/agentmako/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drhalto%2Fagentmako/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32416146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","claude-code","claude-code-plugin","code-intelligence","codex","cursor","developer-tools","llm-tools","local-first","mcp","mcp-server","model-context-protocol","opencode","sqlite","typescript","vibecoding"],"created_at":"2026-04-26T05:05:46.619Z","updated_at":"2026-04-30T09:01:13.120Z","avatar_url":"https://github.com/drhalto.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"apps/web/public/agentmako.png\" alt=\"agentmako logo\" width=\"180\" /\u003e\n\u003c/p\u003e\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 \u003e=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)\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\ntyped MCP toolset for understanding a project before they edit it. Mako\nindexes your repo, builds local SQLite-backed facts, tracks diagnostics\nand review notes, and returns structured context packets instead of\nmaking the agent rediscover everything with raw grep.\n\nMako is built for the first mile of coding-agent work:\n\n\u003e What files matter? What routes, symbols, tables, diagnostics, and prior\n\u003e 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- Deterministic context packets: `context_packet`, `reef_scout`\n- Code search and structure tools: `cross_search`, `live_text_search`,\n  `ast_find_pattern`, `repo_map`\n- [Reef Engine](./docs/reef-engine.md) facts and findings across indexed,\n  working-tree, and staged state\n- TypeScript, ESLint, Oxlint, Biome, and staged git diagnostic ingestion\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 doctor\n```\n\nYou should see green checks for configuration and the local API service.\n\n\u003e Prefer to build from source (e.g. to contribute)?  See\n\u003e [Develop From Source](#develop-from-source) at the bottom of this\n\u003e 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 scout query:\n\n```bash\nagentmako --json tool call . reef_scout \"{\\\"query\\\":\\\"where should I inspect auth route state?\\\"}\"\n```\n\nIf that returns ranked candidates, facts, or findings, the core setup is\nworking.\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, start with one of these tools:\n\n- `tool_search` when you need to find the right Mako tool\n- `context_packet` when you have a coding task and want starting context\n- `reef_scout` when you want ranked project facts/findings/history\n- `ask` when you have a natural-language repo question\n\n### 4. Optional: use the Claude Code plugin\n\nPlain MCP works with Claude Code, but the bundled plugin adds Mako-specific\nClaude skills and includes the same `agentmako mcp` wiring in\n`mako-ai-claude-plugin/.mcp.json`.\n\nPrerequisites:\n\n- Claude Code installed\n- `agentmako` available on `PATH`\n- Your target project already attached with `agentmako connect`\n\nFrom the agentmako repo root:\n\n```powershell\nclaude plugin validate .\\mako-ai-claude-plugin\nclaude --plugin-dir .\\mako-ai-claude-plugin\n```\n\nInside Claude Code, run `/mcp` and confirm `mako-ai` 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- [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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrhalto%2Fagentmako","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrhalto%2Fagentmako","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrhalto%2Fagentmako/lists"}