🌳 trigger-tree

See which project docs your AI actually discovers.

• Local and dependency-free: no cloud, analytics, or model tokens.
• Separate heat, lifetime reads, searches, and untouched paths instead of guessing intent.
• Reduce the evidence to an A–F documentation health grade when detail is unnecessary.

Documentation steers an AI coding assistant toward your team’s patterns and guardrails. But a rule that is never read protects nothing. trigger-tree records discovery evidence so you can improve the routes without pretending a read proves understanding.

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?

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 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.

Gate your CI on discoverability

The gate scores repository structure only — router coverage, orphaned docs, folder entry points, watch scope — so it is deterministic, needs no telemetry, and uploads nothing. Discoverable never means discovered; read telemetry stays local.

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

Commit a baseline once with tt gate --update-baseline and every PR that makes your docs harder to discover fails with the exact file and fix. Findings export as SARIF for GitHub code-scanning annotations and as a CodeClimate report (--code-quality) for GitLab's merge-request Code Quality widget — copy-paste workflows for both live in examples/. The gate checks the wiring, not the words: whether your CLAUDE.md actually instructs agents to follow the routers is proven by local telemetry, not by the gate. Boundaries and details: CI gate.

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	Which local project docs did the coding assistant actually discover?

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

Learn more

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

MIT © Hedde van der Heide