Tools · Reef Engine

Reef Engine tools

Reef is Mako's durable project knowledge layer. It keeps facts, findings, diagnostic runs, freshness labels, operation history, and review acknowledgements in local SQLite. In MCP sessions the local daemon watches edits and runs scoped refresh work so agents can ask what Mako already knows before they start grepping.

Common Reef workflow

  1. Start with mako_help or reef_agent_status to see the right workflow and whether index, diagnostics, and schema evidence are fresh enough.
  2. Use context_packet, reef_scout, or reef_inspect to pull focused evidence before editing.
  3. Before touching one risky file, call file_preflight. Before review, call reef_diff_impact for changed files.
  4. Check project_open_loops and reef_known_issues for unresolved findings that may already cover the problem.
  5. If watcher-backed freshness still reports stale or failed diagnostics, run diagnostic_refresh; if the index is stale, use project_index_refresh with mode: "if_stale".

reef_agent_status read

Top-level project health for an agent turn: index revision, watcher state, schema freshness, diagnostic freshness, stale sources, and suggested next actions.

reef_scout read

Ranked Reef evidence for a vague request. It can mix facts, findings, diagnostic history, schema hints, and confidence labels so the agent has a grounded starting point.

reef_inspect read

Deep evidence for one file or subject: facts, findings, recent diagnostic runs, and freshness metadata. Use before editing files with known risk.

Input

{ "filePath": "lib/auth/dal.ts", "limit": 50 }

file_preflight read

One-call pre-edit packet for a file: durable findings, file-scoped diagnostic freshness, recent diagnostic runs, applicable conventions, changed-file state, and acknowledgement history.

Input

{ "filePath": "lib/auth/dal.ts", "limit": 50 }

reef_diff_impact read

Diff-aware impact query for changed files. It combines working tree overlay facts, import impact, active findings on downstream callers, and conventions the diff may violate.

reef_where_used read

Where-used lookup backed by maintained import and dependency edges, indexed identifier-text references, and related durable findings. The coverage field explains what is direct usage versus related diagnostic signal.

reef_known_issues read

Known current issues with source rollups. Useful at the start of a session, before repeating an investigation that Reef already remembers.

project_open_loops read

Unresolved findings, stale facts, failed or stale diagnostic sources, and other "needs attention" evidence in one view. Newer successful diagnostic runs supersede older stale runs for the same source.

verification_state read

Whether cached diagnostics still cover the current working tree. File-scoped runs count when they cover the requested file, so agents can tell whether the daemon has caught up.

project_findings read

Active durable findings across the project. Use for a broad "what's on fire?" view.

file_findings read

Findings attached to one file. Read this before editing a sensitive file; a prior agent or diagnostic may have already analyzed it.

Input

{ "filePath": "lib/auth/dal.ts", "limit": 50 }

project_facts read

Lower-level facts behind project findings: symbols, imports, routes, schema usage, diagnostic facts, and other structured evidence.

file_facts read

Indexed facts for one file, including symbols, exports, imports, route mappings, and tool-produced evidence.

project_diagnostic_runs read

Diagnostic run history with source, status, input/output revisions, covered files, stale reasons, and timestamps.

rule_memory read

Rule descriptors plus active, acknowledged, and resolved finding counts. Useful when a project has recurring warnings with history.

evidence_confidence read

Confidence labels for evidence such as verified_live, fresh_indexed, stale_indexed, historical, or unknown.

evidence_conflicts read

Find evidence that disagrees across sources or revisions. Use this when two tools appear to give different answers.

project_conventions read

Discovered auth guards, runtime boundaries, generated paths, route patterns, and schema usage conventions without re-reading the whole codebase.

rule_pack_validate read

Validate local YAML rule packs before relying on them. Rule packs are hot-reloaded from .mako/rules/*.yaml.

extract_rule_template read

Mine a fix diff into a draft YAML rule template so a bug shape can become reusable project knowledge.

reef_instructions read

Scoped .mako/instructions.md, AGENTS.md, and related project instructions for requested files.

project_index_status read

Index freshness, file counts, materialized revision, watcher state, and stale/deleted/unknown file counts.

project_index_refresh write

Run the project indexer and materialize a new Reef revision. In normal MCP sessions the daemon handles changed files in the background; use mode: "if_stale" for recovery and force only when indexed answers look wrong.

Input

{ "mode": "if_stale", "reason": "after batch of edits" }

working_tree_overlay write

Snapshot working-tree file facts such as existence, hash, size, line count, and mtime without a full AST/import/route refresh.

reef_overlay_diff read

Compare persisted Reef facts with the current working-tree overlay. Useful when an agent needs to know what changed since the last indexed snapshot.

finding_ack write

Mark one finding as reviewed-safe in the local ledger. Acks require a reason and are treated as real review actions.

Input

{
  "category": "auth/missing-tenant-scope",
  "subjectKind": "diagnostic_issue",
  "filePath": "lib/auth/dal.ts",
  "fingerprint": "auth/missing-tenant-scope:lib/auth/dal.ts:resolveManagerScope",
  "reason": "Reviewed false positive because the RPC enforces tenant scope.",
  "sourceToolName": "lint_files",
  "sourceRuleId": "auth/missing-tenant-scope"
}

finding_ack_batch write

Apply the same ack shape across multiple findings. Use for sweeping reviews only after confirming the pattern is intentional.

finding_acks_report read

Report on acknowledged findings. Run this before assuming a clean diagnostic result means nothing was suppressed.