Show HN: Trigger-tree; see which project docs your AI coding agent reads

Trigger-tree, a new open-source tool by developer Hedde, measures which project documentation files AI coding assistants like Claude and Codex actually read, providing heat maps, cold maps, and a live dashboard to identify unread or ignored docs. The tool runs 100% locally with zero model tokens and no cloud or analytics vendors, closing a gap in agent observability by tracking doc discovery per task rather than just tokens or traces. Hedde argues that unread guardrails fail silently, and trigger-tree gives teams evidence to review, reroute, or prune documentation based on actual usage data.

See which docs your AI actually discovers. AI coding assistants read your project documentation to decide how to work. trigger-tree shows which docs they discover and use — and which ones they never find. 100% local. Zero model tokens. No cloud, no analytics vendors. ✓ heat & cold maps of your documentation · ✓ live pulse dashboard · ✓ evidence-backed router fixes Website · Privacy policy /Hedde/trigger tree/blob/main/PRIVACY.md · Changelog /Hedde/trigger tree/blob/main/CHANGELOG.md Why measure documentation? why-measure-documentation · Quick start quick-start · Commands commands How it works how-it-works · The improvement loop the-improvement-loop · The dashboard the-dashboard Structuring your docs for discovery structuring-your-docs-for-discovery Configuration configuration · Privacy & data privacy--data Platform support platform-support · FAQ faq · Development development In AI-assisted development, documentation is no longer just for humans — it is the steering wheel . Your CLAUDE.md, conventions, and architecture docs tell the assistant how your team builds software: which patterns to copy, which guardrails to respect, which decisions were already made. When the assistant reads the right doc, it works your way. When it doesn't, it guesses. And here is the uncomfortable part: a rule that is never read protects nothing. Teams invest heavily in writing docs, then assume they work — but an unread guardrail fails silently. You only notice when the AI "ignores" a convention that, in truth, it simply never found. trigger-tree closes that loop. It measures which docs are actually consulted per task, surfaces the ones that never are and why — unrouted? unreferenced? obsolete? , and proves whether your fixes worked. Documentation stops being a hopeful artifact and becomes monitored infrastructure — with a health grade to track sprint over sprint. This measurement doesn't exist anywhere else. Anthropic's own best-practices guide https://code.claude.com/docs/en/best-practices warns that a bloated CLAUDE.md causes instructions to be ignored — so high-performing teams review context ruthlessly. But nothing tells them whether those changes were right . Agent observability platforms Langfuse, Arize, W&B Weave measure tokens and traces; none measure which project docs were read per task. And just as Fallow https://github.com/fallow-rs/fallow made unused-code review evidence-based; trigger-tree gives you evidence to review, protect, reroute, or rescue docs nobody dared judge. | You are | Your question | trigger-tree answers with | |---|---|---| | Senior developer | "Why maintain docs nobody reads?" | Read counts and router gaps per file | | Tech lead | "Was our CLAUDE.md pruning correct?" | Trend: hunting ratio before/after each /tt note | | Product owner | "We track token cost — where's doc utility?" | One A–F documentation health grade | Use this path for /tt slash commands, Claude hooks, and the optional Claude statusline: /plugin marketplace add Hedde/trigger tree /plugin install trigger-tree@trigger-tree /tt setup wires the project; local 200-character prompt previews by default /tt doctor proves this repo is wired and receiving telemetry Work normally for a few sessions — the hooks log silently — then: /tt status snapshot: current heat, lifetime reads, untouched paths /tt insights full heat/cold map report + HTML /tt tips Claude-specific memory and instruction maintenance tips Use this path for Codex lifecycle hooks and natural-language trigger-tree workflows: codex plugin marketplace add Hedde/trigger tree codex plugin add trigger-tree@trigger-tree Start a new Codex thread, review and trust the bundled hooks with /hooks , then ask “Show trigger-tree status” or “Open the trigger-tree live dashboard.” Telemetry is collected automatically from official Codex lifecycle hooks; no wrapper is required. | Claude Code | OpenAI Codex | | |---|---|---| | Install | /plugin marketplace add | codex plugin marketplace add | | Invoke | /tt status , /tt watch , etc. | Ask for the desired trigger-tree workflow | | Hooks | Claude plugin hooks | Codex lifecycle hooks; trust via /hooks | | Statusline | Optional trigger-tree counter | Codex’s built-in /statusline is separate | | Visible after GitHub install | Claude marketplace/plugin list | Configured marketplace and Installed plugins | GitHub install versus OpenAI Curated:the commands above install trigger-tree directly; they do not add it to OpenAI’s public directory. An OpenAI Curated listing requires a separate skills-only submission through the OpenAI plugin portal , followed by review, approval, and an explicit publish step. Claude Code exposes one command with nine subcommands. In Codex, ask for the matching outcome in natural language; the bundled trigger-tree skill runs the same local core. | Command | Does | |---|---| /tt status | Snapshot: current heat, lifetime reads, untouched paths | /tt watch | Live ASCII pulse dashboard tmux split or a new terminal window | /tt watch demo | Dashboard with synthetic events — see it without waiting | /tt insights | Heat/cold map analysis: untouched paths, hunting, trend, task clusters + HTML report | /tt suggestions | Concise scope + max 5 evidence-backed fixes; full stats stay off stdout | /tt tips | Client-aware instruction maintenance: Claude memory/rules or Codex AGENTS.md | /tt note <text | Annotate the timeline "sharpened UX router" — visible in the trend | /tt doctor | Verify hooks, privacy, statusline, and live telemetry with actionable fixes | /tt setup truncate|hash|off | Wire the project and choose recognizable local previews or privacy-first markers | Tips are intentionally client-specific. Claude advice follows Anthropic's guidance to audit auto memory, keep CLAUDE.md concise, and remove conflicting instructions https://code.claude.com/docs/en/memory . Codex advice follows OpenAI's guidance to maintain AGENTS.md and a reproducible development environment https://openai.com/business/guides-and-resources/how-openai-uses-codex/ . trigger-tree registers three lightweight hooks — full transparency: | Hook | Event | Records | |---|---|---| | SessionStart | new session | session marker | | UserPromptSubmit | your prompt | first 200 characters after setup; choose hash or off for stronger privacy | | SessionStart + PostToolUse | Read|Glob|Grep , Skill , and Bash | doc reads, native searches, skill names, explicit rg / grep / find targets, and expanded Bash reader paths | Hooks log shell-side to $PROJECT/.trigger-tree/history.jsonl — zero model tokens, a few milliseconds per tool call, and a logging failure can never break your session loggers always exit 0 . The aggregator is deterministic — all counting happens in tt-stats.py ; the model only interprets, never computes. Discovery stays model-driven — your CLAUDE.md remains the router. trigger-tree measures it; it never injects context or overrides routing. Bash searches count only when rg , grep , or find explicitly targets an existing documentation path; search output is never treated as a read. In Bash sessions, lightweight reader wrappers observe expanded file arguments after variables, substitutions, loops, and globs resolve. They preserve command behavior and record only matching paths—not commands, patterns, output, or contents. Other shells use the conservative literal-path fallback. Subagent reads are attributed Explore , Plan , … . Auto-loaded context—including the recursive CLAUDE.md @import graph—is invisible to Read telemetry by design and classified as always loaded ; invoked skills are measured. Files with zero reads are review candidates , never removal recommendations. Protected context always-loaded files, safety paths, critical tags/globs, and docs with many in-links is called out as likely-keep. Then the loop closes: /tt insights shows the folder heat & cold map and flags router gaps : untouched files that no other doc even links to. /tt suggestions turns that into concrete edits "add X to docs/README.md under Y — untouched and unreferenced, 0 reads in 3 weeks" .- You apply, then /tt note "sharpened UX router" . - The trend hunting ratio per week shows whether the change actually worked — measured, not guessed. /tt watch opens a live view in a second terminal. Every read flashes white and ripples up through its parent folders, then fades back to its heat color: ⠹ trigger-tree myproject · live doc-discovery docs/design/ · 1 unread ├─ principles.md ███·· h 3.2 · 12× ├─ ui-patterns.md █████ h 6.8 · 17× └─ accessibility.md · 0 docs/database/ · 🔍 2 searches · 1 unread └─ migrations.md ██··· h 1.4 · 4× 33 reads · 2 scans hunting · 1 skill uses · 3 sessions ● docs/design/ui-patterns.md · 2s ago 🔍 docs/database Explore · 31s ago Heat and read count are deliberately different signals. Reads are the lifetime evidence and never decrease. Heat is current attention: each timestamped read has weight 0.5^ age days / 30 , so its contribution halves every 30 days 1 today, 0.5 after 30 days, 0.125 after 90 days, and effectively zero after a year . A new read reheats the file immediately. /tt insights also shows exact 7-, 30-, and 90-day read windows, the last-read date, and lifetime reads. Folder heat is the sum of its file heat. Cold therefore means inactive now , never obsolete or safe to remove; untouched and protected-context classifications remain separate safeguards. Folder labels keep two signals separate: 🔍 N searches proves the folder was explicitly searched, while N unread counts files without a Read event. Searching a folder never pretends its files were consulted; reading one lowers only unread . The same counters are scoped to the selected prompt when browsing with ←/→. The live tree refreshes its inventory every five seconds: deleted files and folders disappear from the current overview while their evidence remains available in historical prompt browsing and aggregate trends. Recently active folders temporarily move above quiet folders so live work stays inside a small viewport. They settle back into alphabetical order after eight seconds; files within folders and prompt-history views remain alphabetically stable. The live view shows at most ten folders with proven activity and collapses untouched folders/files into one quiet summary. /tt insights remains the complete cold-path inventory; nothing is removed from the underlying telemetry. The live rows use horizontal five-cell heat bars and place their heat/lifetime column against the available right edge, so wider panes expose more of long filenames instead of leaving unused space. Sorting is explicit: f restores recent-focus, h shows hottest first, c shows coldest first including untouched files , and n toggles A–Z and Z–A. Always-loaded CLAUDE.md , AGENTS.md , rules, and skills are labeled injected instead of being misrepresented as cold. The current mode is always printed in the footer. Press s to change prompt privacy inside the dashboard; changes apply to future prompts and are written atomically to the gitignored project config. The controls occupy their own persistent legend row with a compact form for narrow panes , separate from prompt navigation and the live heartbeat, so the keys remain discoverable instead of disappearing at the right edge. Browse per prompt : press ← to move to older prompts and → to move to newer ones — the tree filters to exactly what was aggregated for that input its reads, scans and skill uses, with its prompt label in the header . The timeline never wraps or changes mode at its ends; a returns to the live overview. /tt setup defaults to TT LOG PROMPTS='truncate' , so history shows a recognizable preview of at most 200 characters. The data remains local and gitignored, but it is still prompt text on disk. Choose /tt setup hash for stable fingerprints without text, or /tt setup off for marker-only history. Only future prompts are affected; previously hashed prompt text cannot and should not be reconstructed. --demo for instant synthetic events, --replay to re-run your real history, q or Ctrl+C to quit. The watcher uses a full-screen terminal buffer with wrapping disabled, so refreshes do not accumulate as scrollback; your normal terminal state is restored when it exits. How should a docs tree look so an assistant actually finds things? Claude Code has native mechanisms, and there is one popular community convention — trigger-tree measures whichever you use. The facts, per the official memory docs https://code.claude.com/docs/en/memory.md : | Mechanism | Loads | Status | |---|---|---| Root CLAUDE.md — keep it under 200 lines, pointers over inlining | at launch | ✅ official | Nested CLAUDE.md per subdirectory | on demand, when files there are read | ✅ official | .claude/rules/ .md with paths: glob frontmatter | on demand, on matching files | ✅ official | @imports @docs/foo.md , max 4 hops deep | at launch — they always cost context | ✅ official | Per-folder index.md / README.md routers + template.md | when the model follows your router instructions | community pattern | Practical guidance, as encoded in /tt suggestions : Root CLAUDE.md is a router, not a manual. Short, with a task→docs map "UI work → docs/design/, start at index.md" . Give every folder one entry point — an index.md or a nested CLAUDE.md that says what lives there and when to read what. trigger-tree flags folders without one "no index file" and /tt suggestions proposes adding it. Know the measurement trade-off. Injected context root and nested CLAUDE.md, rules, imports is invisible to read-telemetry — trigger-tree honestly lists it as always loaded instead of guessing. Router files read via tools index.md are measurable. If you want provable discovery, route through index files and keep injected files thin. Prefix templates with template.md . Claude attaches no special meaning to the underscore — but trigger-tree recognizes the convention and files them as intentional archive instead of nagging you about "dead" templates. Per-project settings live in .trigger-tree/config.sh created by /tt setup : | Variable | Default | Meaning | |---|---|---| TT WATCH REGEX | docs/agents/skills/agent-briefs + CLAUDE/AGENTS.md | which reads count as documentation | TT SCAN REGEX | doc folders | which Glob/Grep and explicit Bash-search targets count as hunting | TT ALWAYS LOADED REGEX | CLAUDE/AGENTS.md, .claude/skills | auto-loaded files, augmented by recursive @imports and excluded from review candidates | TT CRITICAL GLOB | empty | comma-separated globs protected as rare-but-critical review items | TT LOG PROMPTS | truncate after setup; hash without config | truncate 200 local chars · hash sha1 only · off marker only | TT ROTATE BYTES | 5 MB | rotate history.jsonl to a timestamped archive beyond this size | TT EXPERIMENTAL OUTCOMES | off | on enables a local, correlational committed-vs-abandoned session view | The experimental outcome view records whether the repository HEAD changed during a session and the latest locally observed test-command result. It compares documents read in committed versus abandoned sessions. This is correlation only: it does not claim that reading a document caused an outcome. Team auto-install — in your project's .claude/settings.json : { "extraKnownMarketplaces": { "trigger-tree": { "source": { "source": "github", "repo": "Hedde/trigger tree" } } }, "enabledPlugins": { "trigger-tree@trigger-tree": true } } Codex support is native. Its adapter normalizes official lifecycle events, unified terminal cmd payloads, native reads, and filesystem MCP reads into the same history schema used by Claude Code. Starting Codex from a repository subdirectory still writes to the repository-root dataset. Git hooks, editors, and other tools can feed that same telemetry through a stable entry point: python3 <plugin /scripts/tt-log.py ingest '{"t":"read","path":"docs/design/index.md"}' Missing ts / session are stamped automatically; invalid events are dropped silently. - ✅ No network calls of any kind — python3 standard library only; audit every line. - ✅ Nothing leaves your machine — data lives in $PROJECT/.trigger-tree/ gitignored . - ✅ Paths and metadata only — file contents are never read or stored. - ✅ Prompt privacy is explicit — setup explains its local preview default; hash and off remain one-command alternatives. - ✅ You own deletion — remove .trigger-tree/ and all history is gone. Full policy: PRIVACY.md /Hedde/trigger tree/blob/main/PRIVACY.md · Security reports: SECURITY.md /Hedde/trigger tree/blob/main/SECURITY.md | Platform | Telemetry & analysis | /tt watch window | |---|---|---| | macOS | ✅ | iTerm2 split same window , tmux split, or Terminal.app | | Linux | ✅ | tmux split, gnome-terminal, konsole, xterm | | Windows | ✅ Git Bash | Windows Terminal wt.exe or start | CI runs the full test suite on all three platforms. Requirements: python3 or python on PATH — nothing else. Honesty over marketing — know what the measurement can and cannot see: Injected context is invisible. Root/nested CLAUDE.md, .claude/rules and @imports enter the context without a Read call; trigger-tree lists them as always loaded rather than guessing. Only tool-driven reads are measurable. Read ≠ understood. A read count proves discovery, not that the content was good or followed. Pair the telemetry with your own judgment. Signals, not verdicts. Untouched files are review candidates , never removal recommendations. Always-loaded, widely referenced, safety-path, configured-critical, and critical-tagged files are protected; low reads can mean rare-but-critical. Tool hooks have surface boundaries. Claude Code and Codex are supported natively. Hosted tools that bypass local lifecycle hooks remain invisible; other local tools can participate through ingest see Codex adapter and external tools . Where is my data? $PROJECT/.trigger-tree/history.jsonl , per project, on your machine, gitignored. Does this slow the agent down? No tokens are ever spent; the hook adds a few milliseconds of shell time per relevant tool call. Why does the statusline say "0 docs consulted" at session start? CLAUDE.md is injected into the system prompt, not read via tools — the router is loaded, but discovery hasn't happened yet. That's also why always-loaded files are excluded from cold-path analysis. A file shows as untouched but I know it matters. Untouched is a signal, not a verdict — check /tt insights : if it's a router gap no doc links to it , the fix is a link, not deletion. The /tt watch split flashes and disappears instantly. Your session is running a stale cached plugin version from before v0.3.3. Run /reload-plugins in that session or start a fresh one . Since v0.3.7 the confirmation line prints the running version — if it doesn't match the latest release https://github.com/Hedde/trigger tree/releases , reload. A real crash keeps the pane open with the error since v0.3.3. How do I know this repository is wired correctly? Run /tt doctor . It checks the plugin hooks, local-data gitignore, statusline registration, and whether this exact repository has received valid telemetry. /tt watch always binds its split to the repository that invoked it and tails new hook events in real time. Can I change prompt logging? Yes: /tt setup truncate stores recognizable 200-character previews locally, /tt setup hash stores only a short SHA-1 fingerprint, and /tt setup off stores marker-only events. Existing history is not rewritten. Always use a virtual environment never your system python : python3 -m venv .venv .venv/bin/pip install -r requirements-test.txt -r requirements-dev.txt .venv/bin/black --check scripts tests .github/scripts .venv/bin/ruff check scripts tests .github/scripts .venv/bin/python -m coverage run -m pytest tests -q .venv/bin/python -m coverage report --fail-under=100 shellcheck scripts/tt-open.sh scripts/tt-shell-capture.sh claude plugin validate . python3 scripts/tt-watch.py --demo CI: Black + Ruff, pytest with a 100% coverage gate on Ubuntu/macOS/Windows, Python 3.10–3.13 compatibility, shellcheck, actionlint + zizmor workflow auditing, plugin validation, and an isolated marketplace-install smoke test. Release tags must agree with the manifest and changelog. See CONTRIBUTING.md /Hedde/trigger tree/blob/main/CONTRIBUTING.md . MIT /Hedde/trigger tree/blob/main/LICENSE — © Hedde van der Heide