SessionStart: Validate on Every Launch

What to Validate

• SessionStart fires once when a session begins — validate everything upfront so environment issues don't surface as mysterious failures deep in a workflow.
• What to check in a SessionStart hook
  • › **Node version** — our project needs v10, not v18
  • › **MCP server connectivity** — can we reach AEM? Figma? ADO?
  • › **Config files** — does `.ai/config.yaml` exist and have required fields?
  • › **Git state** — are you on a feature branch? Any uncommitted changes?
  • › **Dependencies** — is `node_modules/` present?
• The output appears as a banner with status indicators — you see the state of your world before typing the first command.

Setup & Best Practices

1. 1 **Matcher is empty** — `"matcher": ""` means 'always fire.' SessionStart doesn't match tools, it matches session creation.
2. 2 Create a SessionStart hook that checks your Node version — just that one check. You'll be surprised how often you're on the wrong version.
3. 3 Add MCP connectivity checks next — a lightweight call to each server catches 'connection refused' before you burn tokens
4. 4 Keep SessionStart hooks fast (under 3 seconds) — they run on every session start and slow hooks delay your first prompt