Proactive agent hooks

The MCP tools wait to be called. Hooks don't. They fire from editor lifecycle and tool-use events and push context to your agent with zero effort on its part — and keep your index fresh on every commit.

Every agent hook shares the same guarantees: no LLM calls, no network, only local SQLite (wiki.db) and git reads. They are import-isolated (cold start under ~500ms) and any failure exits 0 silently, so a broken environment never crashes or blocks the agent.

The hooks at a glance

The git hook is documented under the hook CLI command; the rest are covered below.

SessionStart — live freshness and relevant decisions

The generated CLAUDE.md is static between reindexes, so it can't say whether the index is current right now. This hook adds a short per-session block so the agent starts with calibrated trust instead of discovering staleness mid-task:

• Index current → one line saying so, plus the core-tool pointer.
• Update running → a positive "catching up" notice, never a stale scare.
• Index behind → indexed vs HEAD with a changed-file count, and the target-scoped trust rule (a stale warning fires only when a file a response actually served has changed).

It also carries the relevance-ranked standing decisions for this session. repowise scores the repo's active decisions against the session's likely working set — dirty and staged files, files changed on the branch vs main, the previous session's edited files, and branch-name tokens — expanded one hop through import edges and co-change partners. The top few land under a hard token cap. Relevance or silence: nothing clears the floor, nothing is injected, and decisions are never shown just for being high-confidence.

PostToolUse — enrichment on every tool call

One hook covers several jobs, matched on the agent's search, read, edit, shell, and repowise MCP calls:

Grep/Glob enrichment. When the agent runs a broad or zero-result search, repowise appends focused context pulled straight from wiki.db: the symbols defined in each related file, what imports it, what it depends on, and its git signals (hotspot, bus factor, owner). An agent that greps for PageGenerator immediately knows what depends on it and that it's a hotspot, without a separate MCP call:

[repowise] 2 related file(s) found:

  packages/core/.../page_generator.py
    Symbols: function:_now_iso, class:PageGenerator, method:__init__
    Imported by: init_cmd.py, update_cmd.py, generation/__init__.py
    Depends on: context_assembler.py, base.py, models.py
    Git: HOTSPOT, bus-factor=1

Git/edit freshness. After a successful git commit, merge, rebase, cherry-pick, or pull, repowise compares HEAD against the last indexed commit and, if the wiki is behind, reminds the agent to run repowise update so it never silently works from outdated docs.

Read-intelligence. On a read of an indexed file, repowise can nudge the agent toward the cheaper get_context(..., include=["skeleton"]) for structure-level questions, and emit a per-file stale-read notice when the file changed after indexing.

Edit-time "governed by" decisions. When the agent edits a file governed by an architectural decision, it gets a one-line notice with the rationale — at most once per session per decision — so the decision reaches the agent right when it's about to honor or violate it.

Command-rewrite (distill), opt-in

The rewrite hook intercepts noisy shell commands and rewrites them to repowise distill <cmd>, which compresses the output errors-first before the agent reads it, exit code preserved and every omission reversible. It defaults to ask, so you approve every rewritten command, and never touches pipes, compound commands, or watch modes. Install and manage it via repowise hook rewrite.

Codex hooks

repowise init --codex writes project-local Codex hooks: a SessionStart / UserPromptSubmit note reminding Codex to use the repowise MCP tools, and a PostToolUse staleness check after edits and git operations. See Connecting Codex for setup.

Learns from how you actually use it

The hooks aren't just delivery — they close a loop. Injected decision ids are recorded locally, and on the next repowise update the session miner checks whether each piece of guidance was followed or contradicted by your corrections, relaxing or bumping the decision's staleness so guidance that stops being true stops being injected.

That feedback is one half of a flywheel that makes repowise adapt to your repo, all local and deterministic:

• Decisions mined from your own sessions — the corrections and conventions you actually enforce become tracked decisions, delivered back at session start and edit time.
• Docs that follow your questions — the wiki generation budget tilts toward the modules you and your agent ask about most, so depth lands where you actually work.