Feature Request: Auto-execute startup routines defined in CLAUDE.md on session start
Problem
CLAUDE.md supports defining custom session startup routines (e.g. reading
memory files, checking worktrees, scanning for stale artifacts). However,
these routines are only executed after the user sends the first message.
This leads to a confusing experience: the user opens a new session, sees
the initial prompt, and has to manually type something like "new session"
or "init" to trigger the startup routine. The defined instructions are
loaded but not acted upon until prompted.
Proposed Solution
Support a dedicated section in CLAUDE.md (e.g. ## On Session Start or
a similar convention) that is automatically executed when a new session
begins, without requiring user input first.
This would allow users to define startup checks such as:
- Reading project memory / context files
- Checking for stale worktrees or session artifacts
- Verifying tool versions (e.g. Node version vs .node-version)
- Reporting the current project state
Current Workaround
The user must send an initial message to trigger the startup routine.
This defeats the purpose of having automated session initialization
and creates a misleading "empty prompt" experience on session start.
Expected Behavior
- User opens a new Claude Code session in a project
- CLAUDE.md is loaded (as it already is today)
- If a startup section is defined, it runs automatically
- The user sees the results (e.g. "all clean" or findings) before
they need to type anything
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗