Hooks

AIDE uses lifecycle hooks to integrate with AI assistants. Hooks fire at specific points during a session, handling state management, skill injection, quality guards, and more.

Hook Reference

Hook	Trigger	Purpose
SessionStart	New conversation begins	Initialize state, inject memories and decisions
SessionEnd	Session closes cleanly	Cleanup session state, record metrics
UserPromptSubmit	User sends a message	Match and inject skills (fuzzy trigger matching)
PreToolUse	Before tool execution	Track tools, enforce agent roles, write guard
PostToolUse	After tool execution	Update HUD, check for AI comment bloat
SubagentStart	Agent spawned	Track active agents, inject memories
SubagentStop	Agent finished	Agent cleanup, update tracking
Stop	Conversation ends	Persist state, capture session summary, agent cleanup
PreCompact	Before context compaction	Preserve state snapshot before summarization

Hook Details

SessionStart

Fires once at the beginning of every conversation. Responsible for:

1. Initializing the aide binary — Downloads if missing, starts MCP server
2. Injecting memories — Global memories (scope:global), project memories (project:<name>), recent session summaries
3. Injecting decisions — All current project decisions
4. Setting initial state — Mode, session ID, agent tracking
5. MCP sync — Synchronize server configurations across assistants

UserPromptSubmit

Fires on every user message. The skill matcher scans the message against all known skill triggers:

1. Exact match check
2. Fuzzy match using Levenshtein distance (typo tolerance)
3. If matched, the skill's markdown content is injected into context

PreToolUse

Fires before every tool execution. Handles:

• Tool tracking — Records which tools are used per session
• Write guard — Blocks the Write tool from overwriting existing files (forces Edit instead)
• Tool enforcement — In swarm mode, restricts read-only agents from using write tools

PostToolUse

Fires after every tool execution. Handles:

• HUD update — Refreshes the Claude Code status line
• Comment checker — Detects excessive AI-generated comments in code output

SubagentStart / SubagentStop

Fire when agents are spawned or finish (swarm mode). These hooks:

• Track active agent count
• Inject memories and decisions into new agents
• Clean up agent state on completion

Stop

Fires when a conversation ends. Captures:

• Session summary — Automatically generated if the session had meaningful activity (files modified, tools used, git commits)
• State persistence — Final state snapshot
• Agent cleanup — Removes per-agent state

PreCompact

Fires before Claude Code's context compaction (summarization). Preserves a state snapshot that includes current mode, active tasks, and key decisions, ensuring this information survives summarization.

Quality Guards

Three quality controls run via hooks:

Write Guard (PreToolUse)

Prevents the Write tool from overwriting existing files. This forces the AI to use Edit instead, reducing accidental file clobbers.

• Only blocks when the target file already exists
• New files are allowed through
• Provides a clear error message directing to use Edit

Comment Checker (PostToolUse)

Detects excessive AI-generated comments in code output. AI assistants tend to add verbose explanatory comments that clutter code. The checker flags this pattern.

Tool Enforcement (PreToolUse)

In swarm mode, agent roles determine tool access:

Role	Tool Access
Architect	Read-only
Explorer	Read-only
Researcher	Read-only
Executor	Full access

This prevents read-only agents from accidentally modifying the codebase.

Platform Implementation

Claude Code

Hooks are implemented as shell scripts generated by the adapter. Claude Code calls these scripts at each lifecycle point, passing JSON payloads via environment variables.

OpenCode

Hooks are implemented through the plugin system. OpenCode's session events are mapped to the same core hook functions, with some differences:

• No native status line support
• Subagent tracking is observational (no spawn control)
• Persistence uses re-prompting instead of stop-blocking