ashlr

Automatic hooks

Every hook ashlr registers in Claude Code and Codex, what each one does, and the env toggles for the SubagentStop and Stop lifecycle hooks.

hooks/hooks.json registers ashlr's Claude Code hooks on SessionStart, UserPromptSubmit, PreToolUse (the tool redirects), PostToolUse, SubagentStop, Stop and SessionEnd. Codex reads its own, smaller set from hooks/codex-hooks.json. Installing only the MCP server installs no host hooks. Every command runs through scripts/hook-bootstrap.mjs, which launches the TypeScript hook under Bun.

This page lists every registered hook, then covers the two background lifecycle hooks, SubagentStop and Stop, in detail. None of them needs configuration.

Every Claude Code hook

SessionStart

One entry runs hook-bootstrap.mjs --group, which starts every hook below as its own process, in parallel, and merges their output.

HookWhat it does
hooks/session-start.tsAdds the project baseline scan as context, starts the session stats bucket, pulls the team genome when one is set up, and prints a once-per-day notice.
hooks/sessionstart-brief.tsAdds the active ashlr-brief ruleset.
hooks/sessionstart-search.ts, sessionstart-lean-tools.ts, sessionstart-genome-author.ts, sessionstart-cost-refactor.ts, sessionstart-efficient.tsEach adds its skill's ruleset when that skill is turned on in the user or project ashlr config.

UserPromptSubmit

HookWhat it does
hooks/userpromptsubmit-brief-trigger.tsTurns brief mode on or off when a prompt asks for it, for example "be brief".

PreToolUse

Claude Code fires an entry only for the tools its matcher names. The budget guard has no matcher, so it sees every call.

MatcherHookWhat it does
(every tool)hooks/pretooluse-budget-guard.tsWarns at 80% and 95% of the ASHLR_SESSION_BUDGET_* cap and blocks at 100%.
Edit, Write, Bash, MultiEdit and the ashlr edit toolshooks/policy-enforce.tsApplies a Team policy pack. Does nothing without ASHLR_PRO_TOKEN.
Readhooks/pretooluse-read.tsRedirects to ashlr__read.
Grephooks/pretooluse-grep.tsRedirects to ashlr__grep.
Edit, Write, MultiEdithooks/pretooluse-edit.tsRedirects to ashlr__edit.
Writehooks/pretooluse-write.tsRedirects to ashlr__write.
NotebookEdithooks/pretooluse-notebookedit.tsRedirects to ashlr__notebook_edit.
WebSearchhooks/pretooluse-websearch.tsRedirects to ashlr__websearch.
TaskList, TaskGethooks/pretooluse-task.tsRedirects to ashlr__task_list or ashlr__task_get.
Bashhooks/commit-attribution.tsAdds an Assisted-By: ashlr-plugin trailer to git commit -m when the message has no attribution trailer yet.
Bashhooks/pretooluse-bash.tsSuggests ashlr__bash. Never blocks.
Globhooks/pretooluse-glob.tsSuggests ashlr__glob. Never blocks.
WebFetchhooks/pretooluse-webfetch.tsSuggests ashlr__webfetch. Never blocks.
Taskhooks/pretooluse-eco-router.tsWith ASHLR_ECO=1, sends question-shaped Task calls to the ashlr:ashlr:explore agent.

The redirect hooks deny the native call and name the ashlr tool to use when ASHLR_HOOK_MODE=redirect, the default. Paths outside the working directory and paths inside the plugin folder are never redirected. ASHLR_HOOK_MODE=nudge, or "hookMode": "nudge" in ~/.ashlr/config.json, turns every redirect into a suggestion. See Permissions.

PostToolUse

One --group entry starts these hooks in parallel. Each keeps its own tool filter, covering native tools, the matching ashlr tools, or both.

HookWhat it does
hooks/post-tool-use-embedding.tsRe-embeds files changed by the ashlr edit tools.
hooks/audit-upload.tsSends edit and command events to the hosted audit log. Does nothing without ASHLR_PRO_TOKEN.
hooks/edit-batching-nudge.tsSuggests batching repeated edits.
hooks/genome-scribe-hook.tsNudges the agent to call ashlr__genome_propose after a significant edit.
hooks/posttooluse-genome-refresh.tsQueues edited paths for a genome refresh.
hooks/orient-nudge-hook.tsAfter three or more reads or greps without an edit, suggests ashlr__orient.
hooks/posttooluse-native-nudge.tsNotes a missed saving after a native call that an ashlr tool could have served.
hooks/post-tool-use-genome.tsFeeds tool results to scripts/genome-auto-propose.ts.
hooks/session-log-append.tsAppends one record per call to ~/.ashlr/session-log.jsonl. ASHLR_SESSION_LOG=0 turns it off.
hooks/pulse-emit.tsEmits an OTLP span. Does nothing unless ASHLR_PULSE_OTLP_ENDPOINT is set.
hooks/posttooluse-stale-result.tsTracks read and grep results so stale ones can be flagged.
hooks/posttooluse-dedupe-output.tsElides read and grep output the session has already seen.

SubagentStop, Stop and SessionEnd

EventHookWhat it does
SubagentStophooks/subagent-stop-rollup.tsRolls up the sub-agent's savings and starts genome consolidation. Details below.
Stophooks/stop-accounting.tsRecords turn accounting, idempotent with SessionEnd. Details below.
SessionEndhooks/session-end-consolidate.tsConsolidates the genome, then pushes it to the team cloud when the repo has a .cloud-id.
SessionEndhooks/session-end-stats-gc.tsDrops the session's stats bucket and appends a session_end summary to the session log.

Codex hooks

Codex registers a subset of the same scripts in hooks/codex-hooks.json. Its MCP entry sets nudge mode, so the PreToolUse hooks suggest ashlr tools instead of blocking native ones.

EventHooks
SessionStartsessionstart-lean-tools.ts, sessionstart-efficient.ts, sessionstart-genome-author.ts
UserPromptSubmituserpromptsubmit-brief-trigger.ts
PreToolUsepretooluse-bash.ts, pretooluse-edit.ts, pretooluse-read.ts, pretooluse-grep.ts, pretooluse-glob.ts, pretooluse-write.ts, pretooluse-budget-guard.ts
PostToolUsepost-tool-use-genome.ts, session-log-append.ts
PreCompactsession-end-consolidate.ts
PostCompactsessionstart-lean-tools.ts
SubagentStartsessionstart-efficient.ts
SubagentStopsubagent-stop-rollup.ts
Stopstop-accounting.ts

Why no PreCompact hook in Claude Code? Re-orientation after a context compaction is handled by the SessionStart hook, which Claude Code fires with source: compact right after a compaction — and which can inject context. Claude Code's PreCompact event is decision-control only (it cannot emit additionalContext), so ashlr does its post-compaction re-orientation from SessionStart instead.

SubagentStop — savings rollup after a Task finishes

Hook: hooks/subagent-stop-rollup.ts

Fires when a subagent (Task) completes. Does two things:

  1. Appends a rollup line to ~/.ashlr/session-log.jsonl recording the subagent's task ID, session ID, tokens saved, call count, and top tool.
  2. Fires genome consolidation for the current working directory — a background bun run scripts/genome-auto-consolidate.ts that keeps the genome fresh after the subagent's changes.

SubagentStop is a decision-control event in Claude Code, so the hook emits no context of its own — the rollup is recorded to the session log.

Env toggles:

VariableEffect
ASHLR_SESSION_LOG=0Skips appending to session-log.jsonl
ASHLR_GENOME_AUTO=0Skips the background genome consolidation

Stop — session finalization

Hook: hooks/stop-accounting.ts

Fires on the Claude Code Stop event (the end of each assistant turn). Complements the SessionEnd GC path with an idempotency guard: before writing, it reads the last three lines of session-log.jsonl and skips if a session_end or stop entry for this session already exists within the last 60 seconds.

What it does:

  1. Reads final session stats — tokens saved, call count, and top tool.
  2. Appends a stop entry to ~/.ashlr/session-log.jsonl.

Stop is a decision-control event in Claude Code — it cannot emit additionalContext — so the hook surfaces nothing inline. Per-session savings are shown in the status line and via /ashlr-savings.

Env toggles:

VariableEffect
ASHLR_SESSION_LOG=0Skips the log append

Session log location

Both hooks write to ~/.ashlr/session-log.jsonl. Each line is a JSON object with at minimum ts, event, and session fields. See Stats schema for the full shape.

All hooks are fire-and-forget safe

Every hook is written to the contract: never throws, always exits 0. A hook failure writes a note to ~/.ashlr/hook-errors.jsonl via _hook-errors.ts and then exits cleanly — it never blocks the session.

On this page