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 Grep / Glob / Read / Edit / Write 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

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.

The hook never touches pipes it doesn't recognize, compound commands, or watch modes. Install and manage it via repowise hook rewrite.

Codex hooks#

repowise init --codex writes project-local Codex hooks (it does not touch your global ~/.codex/config.toml):

• SessionStart reminds Codex to use the repowise MCP tools for architecture, search, risk, decisions, and dead-code analysis, and carries the same relevance-ranked standing decisions Claude Code receives.
• PostToolUse, on the shell tool and on apply_patch / Edit / Write, compares HEAD against the last indexed commit after a successful git commit, merge, rebase, cherry-pick or pull and flags that indexed context may be stale.

Nothing is registered on UserPromptSubmit. Firing on every prompt only repeats the MCP-usage note SessionStart already delivered, at the cost of a hook run per turn. If an older install of ours is still on that event, repowise agents refresh rewrites this repo's .codex/hooks.json and clears it. A hook you wrote there is left alone.

Codex names its shell tool shell_command on current releases and Bash on older ones, so the matcher covers both. The Claude Code PostToolUse hook deliberately does not watch shell commands: it has Read / Grep / Glob and a SessionStart freshness line, so the shell adds cost without adding reach. Codex has neither. 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.