🌳 trigger-tree

Gate documentation discovery in CI. Measure whether your project instructions change what agents do.

Two concrete offers:

1. CI gate — immediate. A deterministic, telemetry-free structural check fails a PR with the affected file and a suggested fix.
2. Instruction adherence — after a few working sessions. See whether an applicable CLAUDE.md directive was followed by observable behavior, and what that always-loaded instruction costs on every request.

Heat maps and the A–F documentation-health grade add longer-term discovery evidence. Everything runs locally with Python’s standard library: no cloud, analytics, network calls, or model tokens while measuring.

Gate your CI on discoverability

The gate scores repository structure only — router coverage, orphaned docs, folder entry points, and watch scope — so it works on day one without telemetry.

- uses: Hedde/trigger_tree@v1.25.1   # or: pip install trigger-tree && tt gate

Commit a baseline once with tt gate --update-baseline. A regression then fails the PR with the exact file and fix. SARIF and GitLab Code Quality exports are available in examples/. The gate checks wiring, not wording; see CI gate.

Does your CLAUDE.md actually work?

Injected instructions are always loaded, so another read counter cannot answer this. trigger-tree asks a narrower, measurable question: when a directive applied, did its declared probe observe the behavior it requested?

Directive	Opportunities	Followed	Rate	Confidence
Route telemetry questions to docs/heat-model.md	8	7	88%	warming
Run checks before committing	6	5	83%	warming
Preserve stdlib-only runtime code	—	—	—	unobservable

Your always-loaded context is ~190 tokens per session. 2 directives (~34 tokens) have not been triggered in 12 sessions over 9.8 days.

The table is representative output. A committed, reviewable manifest defines each probe; the model may propose it once, but you confirm it and deterministic local code does every count thereafter. Unobserved means evidence was not captured; it does not mean violated. Zero opportunities is never-triggered, a review prompt rather than a removal recommendation — and only over sessions where that probe's capture was actually running. Unobservable directives are split by cause: a rule with no objectively testable condition is probably not firing for the model either, which is advice you can act on, while a rule that needs the diff is simply outside what the event stream can see. See instruction adherence.

Subagent personas are measured the same way. Every definition under .claude/agents/ puts its name and description in the system prompt on every request, and its body only when the agent runs, so the two are counted separately. A persona you never invoke is recurring cost in exactly the way an untriggered rule is. /tt insights reports which personas ran, how often, and which have never been invoked. Opt in with /tt setup; only the persona name is recorded, never the task given to it. A persona is only called never-invoked over sessions where that capture was running.

Honest time to value

Capability	When it becomes useful
CI discoverability gate	Immediately; no telemetry required
Instruction adherence	After at least 5 applicable opportunities, usually a few working sessions; earlier rates are provisional
Heat and documentation health	Directional during warm-up; strongest after roughly a month of normal work

Quick start

Claude Code

/plugin marketplace add Hedde/trigger_tree
/plugin install trigger-tree@trigger-tree
/reload-plugins
/tt watch demo
/tt setup
/tt doctor

Work normally, then /tt insights.

Codex

codex plugin marketplace add Hedde/trigger_tree
codex plugin add trigger-tree@trigger-tree

Restart Codex and, when it shows Hooks need review, choose Trust all and continue — Codex silently skips untrusted hooks, and non-interactive codex exec runs never persist trust, so telemetry stays empty until the four hooks are trusted in the TUI. Repeat the review after an upgrade that changes a hook. Then ask Codex to run python3 "$PLUGIN_ROOT/scripts/tt-watch.py" --demo; the bundled trigger-tree skill covers setup, doctor, and insights.

The Claude /tt skill is explicitly user-triggered. Codex installs the equivalent skill and lifecycle hooks through its plugin marketplace, and invokes it as @trigger-tree <command> (for example @trigger-tree watch) or with the same request in plain language; both work.

Prefer a standalone CLI — for CI, git-hook ingestion, or dashboards without a plugin? pipx install trigger-tree (or uvx --from trigger-tree tt), then tt doctor, tt watch --demo, tt stats.

Before a project runs setup, prompt logging stores only a short hash — plugin installs are user-wide, so no repository records prompt text without its own explicit choice. A user-wide default in ~/.trigger-tree/config.sh (for example TT_LOG_PROMPTS='off') tightens that for every repository at once; /tt setup still asks per project — truncate (recommended, recognizable 200-character previews), hash, or off — and the project choice wins.

Who gets what?

You are…	trigger-tree gives you…
Senior developer	File/folder heat, search evidence, router gaps, and prompt-level browsing
Tech lead	Trends, task clusters, protected-context review, and evidence-backed fixes
Product owner	One honest A–F docs-health signal, provisional until measurement matures

Commands

Command	Result
/tt watch demo	Instant synthetic dashboard; no telemetry required
/tt setup [truncate|hash|off]	Wire the repo and choose prompt privacy
/tt doctor	Check hooks, liveness, scope, privacy, and statusline wiring
/tt status	Current heat, lifetime reads, and untouched paths
/tt watch	Live mock-TUI dashboard with prompt browsing and sorting
/tt insights	Deterministic analysis plus a local HTML report
/tt instructions	Per-directive adherence, uncertainty, and always-loaded cost
/tt suggestions	Up to five evidence-backed routing improvements
/tt badge	Write a public-safe docs-health endpoint JSON
/tt note <text>	Add a local timeline annotation
/tt gate	Deterministic discoverability score; gate CI on regressions
/tt uninstall	Remove wiring without deleting telemetry

Search telemetry is a conservative lower bound; see measurement boundaries.

How it works

1. Hooks log shell-side to the gitignored .trigger-tree/history.jsonl; failures never interrupt the coding session.
2. A deterministic aggregator computes every metric with Python’s standard library; the model interprets but never counts.
3. Discovery remains model-driven: trigger-tree measures your routers and reads without injecting context or changing routing.

Where it fits

Category	Question answered
Token/trace observability (Langfuse, Arize, W&B)	What did the model call, spend, and produce?
Documentation linters	Is documentation structurally or stylistically valid?
trigger-tree	Are project docs discoverable, which were discovered, and did declared instruction probes observe the requested behavior?

The categories complement each other. trigger-tree does not evaluate answer quality or claim that a read caused an outcome.

Learn more

Documentation router · Instruction adherence · Dashboard · Heat model · Configuration · Privacy · Glossary · FAQ · Website · Changelog

MIT © Hedde van der Heide