🌳 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/[email protected]   # 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?

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.

Honest time to value

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.

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?

Commands

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

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