Hooks

Hooks (processes) are Node.js scripts attached to Claude Code lifecycle events. They manage context, inject knowledge into agents, block exit when a task is still active, and ensure progress transfer between sessions. Brewcode registers 8 hooks in hooks.json.

Summary table

Execution flow

UserPromptSubmit
  └── forced-eval.mjs          [SKILL?] Check available skills

SessionStart
  ├── session-start.mjs        Session ID, LATEST.md symlink, handoff
  └── grepai-session.mjs       Auto-start grepai watch

PreToolUse:Task
  └── pre-task.mjs             grepai + KNOWLEDGE + phase context -> agent prompt

PreToolUse:Glob|Grep
  └── grepai-reminder.mjs     "USE grepai_search FIRST"

PostToolUse:Task
  └── post-task.mjs            Session bind, coordinator reminder

PreCompact
  └── pre-compact.mjs         Compact KNOWLEDGE, write handoff, status update

Stop
  └── stop.mjs                 Block if active task, cleanup lock

I/O protocol

All hooks follow a unified protocol:

1. Read JSON from stdin (via readStdin())
2. Receive fields: session_id, cwd, source (SessionStart), tool_input (PreToolUse/PostToolUse)
3. Output JSON to stdout (via output())
4. Write logs to stderr and to the file .claude/tasks/logs/brewcode.log

Shared utilities:

• hooks/lib/utils.mjs — I/O, lock files, configuration, logging, task parsing
• hooks/lib/knowledge.mjs — KNOWLEDGE.jsonl read/write, compaction, handoff

Detailed description

1. forced-eval.mjs

Boosts skill activation from ~20-50% to ~84%. Intercepts every user prompt and adds a reminder to check available skills.

What it does:

• Receives the user prompt
• Adds a prefix: [SKILL?] Check available skills. If one matches this request, use Skill tool before responding.
• Returns the modified prompt via updatedInput

When it fires: On every user input, except events with an incorrect hook_event_name.

2. session-start.mjs

Initializes the session, logs the session ID, and manages Plan Mode symlinks.

Logic by session source:

LATEST.md symlink:

1. Checks ~/.claude/plans/ for .md files
2. Picks the newest one (by mtime)
3. If the file is less than 60 seconds old — creates .claude/plans/LATEST.md -> ~/.claude/plans/<newest>.md
4. Used by the /brewcode:plan skill for Plan Mode

3. grepai-session.mjs

Automatically starts grepai watch when entering a project with a configured .grepai/.

Logic:

• If .grepai/ does not exist — skips silently
• If .grepai/ exists — checks ollama, index, watch process, MCP
• If watch is not running — starts it automatically
• Reports status via systemMessage

4. pre-task.mjs

Injects context into the subagent prompt before every Task tool call.

What it injects:

Knowledge compression: KNOWLEDGE.jsonl is compressed to maxTokens (default 500 tokens) via compressKnowledge() — priority ❌ > ✅ > ℹ️.

System agents (Explore, Plan, general-purpose) do not receive the ## K injection.

5. grepai-reminder.mjs

Reminds to use grepai_search instead of direct Glob/Grep.

Throttling: The reminder is shown at most once per 60 seconds (via timestamp file .grepai/.reminder-ts).

Condition: Only fires if .grepai/ and .grepai/index.gob exist.

6. post-task.mjs

Handles the Task tool result: binds the session and reminds about the 2-step protocol.

Logic:

• If bc-coordinator finished — binds session_id to the lock file
• If a worker agent finished (developer, tester, etc.) — reminds: “WRITE report -> CALL bc-coordinator”
• System agents — skipped

7. pre-compact.mjs

Fires before Claude Code’s automatic context compaction. Saves progress and prepares data for continuation after compact.

Actions:

1. Lock file check (brewcode active + belongs to this session)
2. KNOWLEDGE.jsonl compaction (deduplication, trimming)
3. Handoff entry written to KNOWLEDGE.jsonl
4. Task status updated -> handoff

8. stop.mjs

Controls session exit: blocks when a task is active, cleans up the lock when finished.

Terminal statuses: finished, cancelled, failed, error.

Logic:

Recursion protection: If input.stop_hook_active === true, the hook is skipped to prevent an infinite loop.

Configuration

Hooks read settings from .claude/tasks/cfg/brewcode.config.json: