What is bead-epic-auditor?

An auditor for Beads epics, which are large tasks made up of smaller child tasks. It checks whether an epic is still open even though all its children are closed.

Use it to inspect the live Dolt database and report epics whose full child task set has been completed.

It finds incomplete status updates that can leave mirrored GitHub or Plane issues open by mistake.

bead-epic-auditor — Agent for Claude Code by jeremylongshore

Install

Getting it into your agent

This one installs as part of its plugin. Adding the marketplace and installing the plugin brings it with everything else the plugin ships.

Claude Code

/plugin marketplace add jeremylongshore/dolt-mcp-vcs-plugin

Claude Code

/plugin install dolt-mcp-vcs

Made for: Claude Code.

Or install dolt-mcp-vcs, the plugin that ships this one along with the rest of its 1 skill, 5 agents, 1 MCP server.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/agents/jeremylongshore/dolt-mcp-vcs-plugin/bead-epic-auditor/github.svg)](https://agentmods.dev/agents/jeremylongshore/dolt-mcp-vcs-plugin/bead-epic-auditor)

Your own site

<a href="https://agentmods.dev/agents/jeremylongshore/dolt-mcp-vcs-plugin/bead-epic-auditor"><img src="https://agentmods.dev/badge/agents/jeremylongshore/dolt-mcp-vcs-plugin/bead-epic-auditor/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/agents/jeremylongshore/dolt-mcp-vcs-plugin/bead-epic-auditor"><img src="https://agentmods.dev/badge/agents/jeremylongshore/dolt-mcp-vcs-plugin/bead-epic-auditor.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 63 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.

When invoked 1,032 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00063	$0.01032
Opus 5	$0.00032	$0.00516
Sonnet 5	$0.00013	$0.00206
Haiku 4.5	$0.00006	$0.00103

Measured 12d ago against content hash bc4adcb4bf69, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-12, from the pricing page.

Security

Grade A, and why

bead-epic-auditor scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 12d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

agents/bead-epic-auditor.md · 50 lines

How it starts

The opening of the file, as written. The whole thing — 50 lines — stays where its author put it; the contents beside it link to each section on GitHub.

You are a bead epic-closure auditor. You find the "stale-open epic" drift: an epic still open even though every one of its parent-child children is closed — which means its mirrored GitHub/Plane cluster issue never received the close fan-out.

Introspect the live schema — don't assume it. You run in your own context against the live database via the Dolt MCP. Before trusting any table/column name or encoding, confirm it against the live DB (SHOW TABLES, SELECT column_name FROM information_schema.columns WHERE table_name=…, SHOW CREATE TABLE …). references/dolt-internals.md is only a directory of authoritative sources, not a schema snapshot — the live schema is the authority.

Your SQL access is read-only (blueprint §3). The mcp__dolt-mcp-vcs__query tool is for SELECT/introspection only — never issue a mutation through it. Any write belongs on an agent-owned branch through the gated client (scripts/dolt-mcp-client.py, which classifies + refuses history-affecting statements); merge/push/reset/branch-delete are recommend-only, surfaced for a human.

Core Responsibilities

Run the closure audit and report open epics whose every child is closed.
Explain the parent-child encoding correctly so the audit is trustworthy.
Recommend (don't run) the exact close command for each drift candidate.
Answer ad-hoc epic/subtree completion questions via SQL.

Process

Find the database. Call mcp__dolt-mcp-vcs__list_databases to confirm the bead database name (e.g., beads); set DOLT_DATABASE/DOLT_PORT accordingly.
Run the canned audit. bash ${CLAUDE_PLUGIN_ROOT:-.}/scripts/epic-closure-audit.sh returns open epics where closed == children over type='parent-child' dependencies.
Ad-hoc questions. For anything the script doesn't cover, call mcp__dolt-mcp-vcs__query directly. The encoding: a parent-child dependency row has issue_id = the CHILD and depends_on_id = the epic PARENT. Epics are issue_type='epic'; closed means status='closed'.
Surface the closure command — recommend, don't run. For each drift candidate, output the exact bd-sync close <epic> --also-close-gh command for the operator to run. This agent must not execute bd-sync itself — not via Bash, not via any tool (its Bash(bash:*) grant is for the read-only audit scripts, never for mutating commands): bd-sync mirror-closes the epic's GitHub/Plane cluster issue, which is a human call. Reserve --also-close-gh for a cluster's last child.

Read the full file on GitHub · 50 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

12d ago First seen · 50 lines · 63 tokens per session scan A bc4adcb4bf69

Subscribe to this mod's changes

bead-epic-auditor is an agent published in the GitHub repository jeremylongshore/dolt-mcp-vcs-plugin (4 stars, last pushed 17d ago), licensed Apache-2.0. It adds 63 tokens to every session and 1,032 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Claude Code Project management audit beads claude-code-plugin closure dolt dolthub epics mcp sql

prd-creator

Creates PRD and structures business requirements. Use when new feature/project starts, or when "PRD/requirements definition/user story/what to build" is mentioned. Defines user value and success metrics.

shinpr/claude-code-workflows · 44 tokens

tasks-agent

Expert development lead that converts technical designs into actionable, incremental coding tasks for implementation.

NikiforovAll/claude-code-rules · 18 tokens

senior-dev

Use to implement tasks from Beads backlog. Claims a task, implements with TDD, closes when done. Can run in parallel.

avelikiy/great_cto · 31 tokens

plan-creation-eng-lead

Engineering and Delivery Lead for implementation planning. Produces work breakdown structures, effort estimates, dependency graphs, milestones, parallel opportunities, and risk registers. Use when you need structured delivery planning for any implementation topic.

QBall-Inc/the-bulwark · 48 tokens

planner

Drafts the execution Plan (plan.md) AND emits task records for a SpecManager feature, grounded in the approved Architecture and the existing codebase. Plans MUST be organised into phases with Fibonacci-scored tasks ≤3.

joanseg/specmanager · 46 tokens

wp-context

Project-docs analyzer — reads a docs/ folder (scope spreadsheets, design PDFs, estimate/scope markdown) and extracts project constraints + an actionable scope manifest.

yojahny55/claude-wp-builder · 34 tokens