/hooks:session-start-hook

Generate a SessionStart hook that prepares your repository for Claude Code on the web — installing dependencies, configuring environment variables, and verifying that tests and linters work.

When to Use This Skill

Context

Detect project stack:

• Lockfiles: !find . -maxdepth 1 \( -name 'package-lock.json' -o -name 'yarn.lock' -o -name 'pnpm-lock.yaml' -o -name 'bun.lockb' -o -name 'poetry.lock' -o -name 'uv.lock' -o -name 'Cargo.lock' -o -name 'go.sum' -o -name 'Gemfile.lock' \)
• Project files: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'requirements.txt' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'Gemfile' -o -name 'pom.xml' \) -o -maxdepth 1 -name 'build.gradle*'
• Linter configs: !find . -maxdepth 1 \( -name 'biome.json' -o -name 'biome.jsonc' -o -name '.eslintrc*' -o -name 'eslint.config.*' \)
• Existing settings: !find . -path '*/.claude/settings.json' -maxdepth 3 -type f
• Existing hooks dir: !find . -maxdepth 2 -type d -name 'scripts'

Parameters

Execution

Step 1: Detect project stack

Identify all languages and tooling from the context above.

Language detection:

Test runner detection:

Linter detection:

Report detected stack to user before generating.

Step 2: Generate hook script

Create the script at scripts/claude-session-start.sh (or .claude/hooks/session-start.sh if no scripts/ directory exists).

Use the Script Template from REFERENCE.md. Adapt it by:

1. Including only sections for detected languages
2. Using the correct package manager commands with frozen lockfile flags
3. Using the correct test runner and linter commands
4. Setting appropriate environment variables per language

Step 3: Configure .claude/settings.json

Read existing .claude/settings.json if it exists. Merge the SessionStart hook — preserve all existing configuration.

If a SessionStart hook already exists, ask the user whether to:

• Replace the existing SessionStart hook
• Add alongside the existing hook (both will run)
• Abort and keep existing configuration

Configuration to merge:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/claude-session-start.sh\"",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Use timeout: 120 (2 minutes) for dependency installation. Adjust path if script is in .claude/hooks/ instead of scripts/.

Step 4: Finalize

1. Make the script executable: chmod +x <script-path>
2. Create .claude/ directory if needed for settings.json
3. Report summary of what was created

Step 5: Verify (unless --no-verify)

Run the generated script locally to confirm it executes without errors. Report results.

Post-Actions

After generating the hook:

1. Suggest committing the new files:

   scripts/claude-session-start.sh
   .claude/settings.json
   

2. If --remote-only was NOT used, mention the flag for web-only behavior
3. If the project needs network access beyond defaults, remind about Claude Code web network settings
4. Mention matcher options: "startup" (new sessions), "resume" (resumed), "" (all events)

SessionStart Matcher Reference

Agentic Optimizations

Quick Reference