trigger-tree

🌳 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?

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

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?

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