mindful

Mindful Claude is a three-layer cognitive-awareness plugin by quangtran88. It does not add agents, orchestration, or task routing. It ships a reasoning layer and a pair of shell hooks whose job is to re-anchor Claude’s attention around a named set of cognitive failure modes — scope creep, false confidence, pattern-matching, dismissiveness, analysis paralysis. In this benchmark it ranks 5 of 9 by aggregate z-score (z̄ = −0.016), but the aggregate hides a sharply bimodal profile: refactor rank 1, bugfix rank 4, feature rank 9 (last).

Source. Public repository at quangtran88/mindful-claude (MIT). The benchmark installs it as a marketplace plugin named mindful-claude@mindful-claude-marketplace at pinned version 1.0.1. This tool is author-adjacent to the benchmark author; it is included alongside otherwise-external setups and the flag is worth surfacing.

Benchmark invocation. Like omc, mindful runs under a two-message protocol (MINDFUL_TWO_MSG=1): the first turn executes /mindful-claude:setup, which installs the PreToolUse hooks into settings.json; only then does the actual task prompt arrive. The setup skill is infrastructure, not problem-solving — it copies two shell scripts into ~/.claude/hooks/ and registers two matchers. The comparable plan-mode guard is against pure and mindful, both of which enter the task turn with no planner, no subagents, and no search layer.

What the plugin actually installs

The plugin is small and its mechanism is literal:

1. Layer 1 — Reasoning framework. A CLAUDE.md at repo root declared HIGHEST PRIORITY. It contains six ground-truth principles (Root-Cause Tracing, Provisional Thinking, Ego-Free Reasoning, Context-Dependence, Fresh Eyes, Surface vs Deeper Need), a six-step pre-response checklist, three named anti-patterns (Scope Creep, Defensiveness, False Confidence), and five cognitive traps with antidotes. The framework is explicitly drawn from Buddhist cognitive taxonomy and cited to primary sources in Layer 2.
2. Layer 2 — Knowledge base. A docs/knowledge-base.md referenced from CLAUDE.md; about 20 concepts mapped to source tradition, AI application, and self-check question.
3. Layer 3 — Enforcement hooks. Two bash scripts registered via PreToolUse:
   • mindful-claude-baseline.sh — fires on Edit|Write|Agent|Bash, unconditionally emits ~150 tokens of silent reminder text (fresh eyes, say less, learn-think-verify, trap scan, adapt).
   • mindful-claude-checkpoint.sh — fires on Bash|Agent, parses stdin with jq, pattern-matches git commit, git push, gh pr create, or Agent descriptions containing review|complete|final|deliver, and returns a visible “Awareness check” prompt requiring a one-line declaration before proceeding. Non-matches pass through with {"continue":true}.

Self-reported token budget is ~2,850/session. The checkpoint fails loudly if jq is missing.

The mindful plugin itself ships no subagents, no planner, no MCP servers, and no skills beyond setup and self-check. The second skill, self-check, is the same checkpoint checklist invocable on demand. Note that the base executor still dispatches Claude Code’s built-in Explore subagent during trials — mean 5.5 on feature, 3.5 on bugfix, 5.0 on refactor (see docs/analysis/trial-timelines/aggregate.md). Those dispatches are model-driven, not plugin-driven: mindful adds no orchestration layer, only a reminder layer.

What the benchmark measured

Setup overhead. One full turn is burned on /mindful-claude:setup before the task. In feature work (single-shot prompt), this halves the effective working budget versus tools that enter directly on the task.

Feature — rank 9 (last). z = −0.388, 199 lines added across 3 files, all tests passing but 10 ESLint errors. The worst feature result in the field. A plausible read: a cognition-framing-only layer, preceded by a setup ceremony, provides nothing that helps a mid-sized green-field feature. The hooks re-state general reasoning principles; they do not add search, structure, or subagents. On a single-turn build task, the setup pays cost without offsetting benefit.

Bugfix — rank 4. z ≈ +0.180. Decent but unremarkable. 136 lines added, 15 of 104 tests failing in the fixed file’s own suite. The checkpoint’s visible Awareness check on Bash commands containing git commit gives the model exactly one forced pause to ask “what do I actually know vs. assume?” — the failure mode the setup is most precisely built for. The gain is real but modest.

Refactor — rank 1. z ≈ +0.162. 130 added, 62 deleted across 11 files, all 61 tests passing, only 6 ESLint errors. Refactor is the task where “Say Less Mean More” and “can I remove anything without losing meaning?” translate directly into code-level decisions. The same checklist that wastes tokens on green-field build work aligns tightly with the operational grammar of refactoring. The tool’s best-in-class refactor ranking is consistent with this alignment, not an artifact of outliers.

Honest positioning

Mindful is the narrowest tool in the field: two shell scripts and some instruction text. It adds no capability the base model does not already have — it re-weights existing capacity. Against cognition-light green-field tasks it underperforms because the setup turn is pure overhead. Against tasks whose success criterion is restraint (remove dead code, tighten seams, leave tests green), the re-weighting is load-bearing and the tool leads the field. The middle rank is an average of these two extremes and obscures them; anyone evaluating mindful should read the per-task z, not the aggregate.

The author-adjacent status does not change the measurements — inputs, harness, and judging are the same across tools — but it is disclosed here so readers can weigh the selection bias themselves.

Observed in trial timelines

Mindful runs the highest test volume in the cohort on feature (mean 29 test commands, vs cohort average ~14) and the highest subagent dispatch on feature (mean 5.5, range 3–9) — driven entirely by the base model’s Explore agent, not by anything mindful ships. Feature t1 introduces a payment-schedule service abstraction (4 new files: model + port + service + spec) that no other tool produced — a structurally larger interpretation of the brief.

Detail: see the per-trial timeline files linked below.

Trial timelines

Per-trial event timelines auto-extracted from session-logs/*.jsonl — skill activations, plugin/skill file reads, subagents dispatched, code mutations, Bash usage:

• feature
• bugfix
• refactor