gardener

Example output

This is abridged from a real run of --audit --md --lang en against the always-loaded instruction files on the machine this site was built on. Directory names are generalised and one finding label is translated. Every number is what the script printed. The scan made no network calls.

# gardener — hot context audit

Source note: 6 files · 182 lines · ~2638 estimated tokens, per request · 76 directives · score: 12 (good)

Budgets: 300/600 lines per file, 4000/8000 estimated tokens in total.
Token counts are a bytes/4 estimate, not a real tokenizer.

## What loads

| File                          | scope   | depth | lines | ~tokens |
|-------------------------------|---------|-------|-------|---------|
| `~/.claude/CLAUDE.md`         | global  | 0     |     7 |      60 |
| `~/agent-defs/instructions.md`| global  | 1     |    53 |     749 |
| `~/agent-defs/identity.md`    | global  | 2     |    46 |     553 |
| `~/agent-defs/memory/MEMORY.md`| global | 2     |    30 |     676 |
| `~/.gemini/GEMINI.md`         | global  | 0     |     1 |       0 |
| `<repo>/.claude/CLAUDE.md`   | project | 0     |    45 |     600 |
| **total**                     |         |       | **182** | **2638** |

## Findings

| Sev  | Check               | where              | what        |
|------|---------------------|--------------------|-------------|
| warn | duplicate-directive | instructions.md:52 | 86% overlap |
| warn | duplicate-directive | instructions.md:32 | 69% overlap |
| warn | duplicate-directive | instructions.md:28 | 67% overlap |

Every finding names the check that fired, the file and the line. For duplicates it also shows both overlapping texts, so you can disagree with one specific finding. The checks are documented in one file you can open, and any check you disagree with can be switched off with --ignore.

Install

# once
> /plugin marketplace add halilneed/plugins

# the plugin
> /plugin install gardener@hailneed

# and try it
> /gardener:audit

The marketplace id is hailneed, which is why the install line ends in @hailneed.

• Claude Code and Node.js 18 or newer.
• No dependencies, no build step, no API key, no account.
• It also runs standalone: node scripts/gardener.mjs --audit --repo . --md
• For CI, --audit --out audit.json has a stable output format. Fail the build when totals.tokens or score.raw goes above a threshold you set. --selftest needs no network.

Commands

/gardener:audit

Reports what loads on every request. The import chain is resolved transitively into one inventory and priced in lines and estimated tokens, with broken imports, stale paths and duplicated instructions listed. An import that cannot be resolved is always listed, so you are not left assuming that rules load when they do not.

/gardener:compliance

Checks whether the prohibitions are followed. Forbidden commands are cross-referenced against the commands that were run in local sessions. It produces violation candidates, which are verified line by line before anything is reported, and lists rules whose subject never came up. Rules whose subject never came up are listed separately from rules that were followed.

/gardener:prune

Writes a line-by-line plan that marks each flagged directive as cut, move, fix, rewrite or enforce, with the reason. It also splits what belongs in the always-loaded file from what belongs on demand. It shows the lines, asks for confirmation, and then edits one file at a time.

What it does and does not do

• The script makes no network calls and edits no files. gardener.mjs reads instruction files and session logs already on your disk and produces a plan. The prune skill changes CLAUDE.md only after it has shown you the lines and you have confirmed.
• Token numbers come from a bytes/4 estimate, not a tokenizer. That is enough to compare files and track change over time, and every report says so.
• A compliance match is a candidate. It may miss context the rule cares about, so the skill opens each candidate, verifies it against the transcript and reports how many it discarded.
• A prohibition with zero occurrences is reported as a possible success, and the skill does not propose deleting a safety rule on a zero count.
• There are 10 checks and no model judgement. checks.md documents every one with its severity and triage note, and --selftest runs them against 19 fixtures without touching your data.
• Unreadable sessions are counted in the source note.
• MIT-licensed (LICENSE). No account, no signup, no telemetry.

Planned

A hosted version, gardener Cloud, is planned. The plugin stays free and local.

• Continuous budget tracking: the hot-context cost of your team’s instruction files, watched over time instead of audited once.
• Before and after for rule changes: what a changed rule did to agent behaviour, compared across the change.
• Onboarding summary: the rules that apply in this repo, for new team members.

To hear when it exists, subscribe on the writing page.

Other plugins

The other five are agent-blackbox, skillbench, scar, painradar and devpersona. All six are described on the tools page.