Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/affaan-m/ECC/llms.txt

Use this file to discover all available pages before exploring further.

ECC hooks are event-driven automations attached to specific harness lifecycle events. Each event represents a precise moment in an AI session — before a tool runs, after it completes, at session start, or before context compaction — giving you fine-grained control over agent behavior without modifying your harness configuration.

​
Hook Execution Flow

The core execution pipeline for tool-use events: 
User request → Claude picks a tool → PreToolUse hook runs → Tool executes → PostToolUse hook runs
                                             ↓ (exit 2 = block)
                                        Tool blocked
  • PreToolUse hooks run before the tool executes. They can block (exit code 2) or warn (stderr without blocking).
  • PostToolUse hooks run after the tool completes. They can analyze output but cannot block.
  • Stop hooks run after each Claude response.
  • SessionStart / SessionEnd hooks run at session lifecycle boundaries.
  • PreCompact hooks run before context compaction.

​
All 18 Lifecycle Events

All event names are case-sensitive. Use them exactly as shown when defining hooks in your hooks.json.
EventWhen It FiresCommon Uses
SessionStartWhen a harness session beginsLoad prior context, detect project state
UserPromptSubmitWhen the user sends a messageSanitize input, log request
PreToolUseBefore any tool executesValidation, blocking, reminders
PermissionRequestWhen a tool requires explicit permissionAudit permission grants
PostToolUseAfter a tool completes successfullyFormat code, analyze output, log
PostToolUseFailureAfter a tool failsLog failure, trigger recovery
NotificationFor system notificationsAlert routing
SubagentStartWhen a sub-agent session beginsTrack delegation
SubagentStopWhen a sub-agent session endsAggregate sub-agent results
StopWhen Claude finishes each responseQuality gates, session summaries
PreCompactBefore context compactionSave state, export snapshot
InstructionsLoadedAfter system instructions are loadedValidate instruction integrity
TeammateIdleWhen a teammate agent is idleCoordination signals
TaskCompletedWhen a task is marked completeMetrics, notifications
ConfigChangeWhen ECC config changesSync config, audit
WorktreeCreateWhen a git worktree is createdRegister in state store
WorktreeRemoveWhen a git worktree is removedCleanup, deregister
SessionEndWhen a session endsPersist final state, cleanup

​
Event Groups by Phase

These events bracket the session. ECC uses SessionStart to load bounded prior context from the SQLite state store, keeping the context window lean. PreCompact saves a snapshot before the harness truncates history. SessionEnd persists final summaries.
Session begins  →  SessionStart (load context)
     ↓
...work happens...
     ↓
Context nearing limit  →  PreCompact (save state)
     ↓
Session ends  →  SessionEnd (final persist)
The tightest feedback loop. PreToolUse can inspect the tool name and input before execution — and block it (exit 2) for policy violations. PostToolUse sees the output and is ideal for formatting, linting, and logging. PostToolUseFailure fires only when the tool itself errors.Key tool matchers: Bash, Edit, Write, Read, MultiEdit.
Stop fires after Claude completes each response — useful for console.log audits, session summaries, and cost tracking. UserPromptSubmit fires when the user submits a message, before any tool is called.
PermissionRequest fires when a tool requires explicit user permission (e.g., running a destructive shell command). Use these hooks to audit or log permission grants.
Multi-agent events fire for sub-agent delegation. SubagentStart and SubagentStop bracket a delegated session. TeammateIdle signals when a coordinated agent is available for work.
Infrastructure-level events. Worktree hooks integrate with ECC’s orchestration layer. ConfigChange fires when ECC config is modified at runtime. InstructionsLoaded validates the system prompt after load. TaskCompleted is emitted by the epic/task tracking system.

​
Installing Hooks

Hooks are installed as part of the hooks-runtime module, included in the core profile and above: 
npx ecc install --modules hooks-runtime --target claude
For Windows: 
.\install.ps1 --modules hooks-runtime --target claude
Do not paste the raw hooks/hooks.json from the repo directly into ~/.claude/settings.json. The checked-in file uses repo-relative paths. Always install via the ECC installer so hook commands are rewritten against your actual Claude root.

​
Runtime Hook Controls

Adjust hook behavior without editing hooks.json: 
# Hook profile: minimal | standard | strict (default: standard)
export ECC_HOOK_PROFILE=standard

# Disable specific hook IDs (comma-separated)
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# Disable GateGuard during setup or recovery
export ECC_GATEGUARD=off

# Cap SessionStart context (default: 8000 chars)
export ECC_SESSION_START_MAX_CHARS=4000

# Disable SessionStart context loading entirely
export ECC_SESSION_START_CONTEXT=off

# Suppress cost estimate warnings
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off
Hook profile semantics:
  • minimal — essential lifecycle and safety hooks only
  • standard — default; balanced quality and safety checks
  • strict — additional reminders and stricter guardrails

Build docs developers (and LLMs) love

Get started for freeTalk to us