Hooks | Coding Friend

Overview

Hooks are lifecycle functions that execute automatically at specific points in your Coding Friend session. They handle security, formatting, reminders, and context management without requiring manual invocation.

CLI Requirement

Most hooks are NONE-tier — they work without coding-friend-cli. Three hooks are OPTIONAL-tier and degrade silently when the CLI is missing:

memory-capture — fires on PreCompact and attempts memory_store; if the MCP is unavailable, the step is skipped silently and the episode is simply not captured.
session-init — sources cf-paths.sh which reads ~/.coding-friend/config.json; falls back to defaults when the config file is absent.
statusline — reads ~/.coding-friend/config.json for visibility settings; renders all components with defaults when the config is absent.

See the full CLI requirements matrix.

Hook Reference

Hook	Trigger	Purpose
`session-init`	SessionStart	Initialize session state and load configuration
`rules-reminder`	UserPromptSubmit	Remind developers of project rules (every 4th prompt)
`privacy-block`	PreToolUse	Block access to sensitive files (.env, .pem, SSH keys)
`scout-block`	PreToolUse	Block access to files matching `.coding-friend/ignore` patterns
`auto-approve`	PreToolUse	Auto-approve safe tool calls, block destructive ones (opt-in)
`statusline`	SessionStart	Configure editor statusline with project info, account, rate limits, task/agent progress
`session-log`	Stop	Append turn log (JSONL) for richer memory capture
`task-tracker`	TaskCreated/TaskCompleted	Track task progress for statusline display
`agent-tracker`	SubagentStart/SubagentStop	Track active agent for statusline display
`memory-capture`	PreCompact	Auto-capture session memory before context compaction

How Hooks Work

Hooks are executed automatically by the Coding Friend plugin at specific lifecycle events. You don't invoke them manually — they run in the background to support your workflow.

Controlling Hooks

Enable or disable hooks in .coding-friend/config.json:

{
  "hooks": {
    "privacyBlock": true,
    "scoutBlock": true,
    "rulesReminder": true
  }
}

All hooks default to enabled. Set to false to disable specific hooks for your project.

Statusline Hook

The statusline hook configures your editor's status bar with live project information. It supports the following components:

Component	Description
`version`	Plugin version from `plugin.json`
`folder`	Current working directory name
`model`	Active Claude model
`branch`	Current git branch
`account`	Account email and display name from `~/.claude.json`
`context`	Context window usage percentage
`rate_limit`	API rate limit usage for 5-hour and 7-day windows

Component Configuration

Toggle individual components in .coding-friend/config.json:

{
  "statusline": {
    "components": {
      "version": true,
      "folder": true,
      "model": true,
      "branch": true,
      "account": true,
      "context": true,
      "rate_limit": true
    }
  }
}

All components default to enabled. The rate_limit component caches API responses for 5 minutes to avoid excessive requests.

Security Hooks

privacy-block and scout-block form Coding Friend's first line of defense against accidental credential exposure and inappropriate file access. See the security reference for the full defense-in-depth model.

Auto-Approve Hook

The auto-approve hook reduces permission prompts by automatically approving safe tool calls and blocking destructive ones. See the dedicated auto-approve reference for details on classification tiers, rules, and configuration.