Reference · Troubleshooting

Troubleshooting agentmako

agentmako is a local-first MCP server for AI coding agents. When something goes wrong, the failure is almost always one of: PATH, attachment, MCP wiring, freshness, or DB connectivity. Diagnose in that order.

"agentmako command not found"

The CLI isn't on PATH. Confirm:

which agentmako    # macOS / Linux
where agentmako    # Windows

If empty:

  • Re-install globally: npm install -g agentmako.
  • Make sure your shell PATH includes the npm global bin (npm config get prefix, then /bin on Unix or root on Windows).
  • Restart any agent that was launched before the install completed — Claude Code, Cursor, and Codex inherit PATH from the parent shell at startup.

MCP server fails to start

Diagnose by running the server directly:

$ agentmako mcp

If it fails standalone, the same error will hit any agent. Common causes:

  • No project attached. See No project attached.
  • Stale install. Re-run npm install -g agentmako and retry.
  • macOS Gatekeeper: the binary needs an explicit "open" the first time. Run agentmako --version from a terminal.

Tools don't appear in Claude Code / Cursor / Codex / Cline

The MCP server is installed but the agent doesn't see the tools.

  • Claude Code: run /mcp in the session. mako-ai should appear connected. If failed, click for the error.
  • Cursor: check Settings → Features → MCP. Green = connected, red = failed, missing = config not read. Verify the path: .cursor/mcp.json (per-project) or ~/.cursor/mcp.json (global).
  • Codex CLI: the TOML block at ~/.codex/config.toml must use [mcp_servers.mako-ai] with command = "agentmako" and args = ["mcp"]. Restart any running codex session.
  • Cline: open the MCP Servers panel; the JSON block is read on save. If you see "disabled: true" anywhere, that's the issue.

Agent isn't calling Mako tools

Tools are registered but the agent ignores them. Three layers:

  1. Confirm registration — see above.
  2. Tell the agent to use them — drop the agentmako CLAUDE.md template into your project root. Without explicit instructions, agents default to grep.
  3. Be explicit in early prompts — for the first few turns, prompt: "Use the mako-ai context_packet tool first." Once the agent sees the tool's value, it tends to keep reaching for it.

Stale results

Reef labels every piece of evidence with a freshness tag. If you're getting stale answers:

  1. Check project_index_status.
  2. For exact post-edit text, use live_text_search (not cross_search).
  3. Refresh: project_index_refresh { "mode": "if_stale" }.
  4. Force only if the index looks actually wrong: { "mode": "force" } (expensive).

Full freshness model: How agentmako tracks freshness.

No project attached

Each project is registered separately so Mako knows which SQLite database to read.

cd /path/to/your/project
agentmako connect . --no-db
agentmako doctor

agentmako doctor reports green/red for config, the local API service, and indexing. If red, the messages tell you what's missing.

Database connection failed

If db_table_schema or db_rls errors out:

  • Run db_ping first — it returns a clear connectivity error.
  • Verify the keychain entry exists. Re-attach: agentmako connect . (interactive) or --db-env DATABASE_URL --yes.
  • For Supabase: confirm the SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (or whichever you used) are still valid.
  • If you're hitting a network egress block, the read-only DB connection still needs network — the rest of agentmako does not.

Index out of date

You added or removed files and the index doesn't know.

  • Quick: working_tree_overlay — snapshots the working tree without re-parsing.
  • Proper: project_index_refresh { "mode": "if_stale" }.
  • Force: project_index_refresh { "mode": "force" } when the index is actually wrong.
  • For DB schema changes: db_reef_refresh.

Permission errors

On macOS, the binary may need explicit "open" the first time. Run agentmako --version from a terminal once. On Windows, ensure your global npm bin is whitelisted by your endpoint protection.

For permission prompts in Cline, add tools to autoApprove in the MCP config — start with safe read-only tools: context_packet, reef_scout, repo_map, cross_search.

How to file a bug

Open an issue at github.com/drhalto/agentmako/issues with:

  • Output of agentmako --version.
  • Output of agentmako doctor.
  • The agent harness and version (Claude Code, Codex, Cursor, Cline).
  • The exact tool call (or MCP config) that fails.
  • The error text or unexpected output.