SessionStart Hook Configuration

Configure your repository for Claude Code on the web using SessionStart hooks. This skill helps you create hooks that automatically run when Claude Code starts a session in the cloud environment.

Overview

SessionStart hooks execute when Claude Code begins a session, allowing you to:

• Install project dependencies (npm, pip, etc.)
• Set up environment variables
• Configure databases or services
• Run initialization scripts
• Validate the environment

Quick Setup

1. Create the settings file

Create .claude/settings.json in your repository root:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/claude-setup.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

2. Create the setup script

Create scripts/claude-setup.sh:

#!/bin/bash
set -e

# Detect package manager and install dependencies
if [ -f "package.json" ]; then
    if [ -f "pnpm-lock.yaml" ]; then
        pnpm install
    elif [ -f "yarn.lock" ]; then
        yarn install
    elif [ -f "bun.lockb" ]; then
        bun install
    else
        npm install
    fi
fi

if [ -f "requirements.txt" ]; then
    pip install -r requirements.txt
fi

if [ -f "pyproject.toml" ]; then
    if command -v uv &> /dev/null; then
        uv sync
    elif command -v poetry &> /dev/null; then
        poetry install
    else
        pip install -e .
    fi
fi

exit 0

3. Make the script executable

chmod +x scripts/claude-setup.sh

Hook Configuration Reference

Basic Structure

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "<pattern>",
        "hooks": [
          {
            "type": "command",
            "command": "<script-or-command>",
            "timeout": <seconds>,
            "statusMessage": "<optional-message>"
          }
        ]
      }
    ]
  }
}

Fields

| Field | Required | Description | |-------|----------|-------------| | matcher | Optional | Pattern to match (use "startup" for all sessions) | | type | Yes | Must be "command" | | command | Yes | Shell command or script path | | timeout | Optional | Max execution time in seconds (default: 60) | | statusMessage | Optional | Message shown during execution |

Environment Detection

Detect Web vs Local Execution

The CLAUDE_CODE_REMOTE environment variable indicates cloud execution:

#!/bin/bash

# Run only in web/cloud environment
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
    echo "Skipping - not running in cloud environment"
    exit 0
fi

# Cloud-specific setup here
npm install

Run Only Locally

#!/bin/bash

# Skip in cloud environment
if [ "$CLAUDE_CODE_REMOTE" = "true" ]; then
    exit 0
fi

# Local-only setup here

Persisting Environment Variables

Write to $CLAUDE_ENV_FILE to set environment variables for the session:

#!/bin/bash

# Set environment variables for Claude Code
echo "DATABASE_URL=postgresql://localhost:5432/mydb" >> "$CLAUDE_ENV_FILE"
echo "NODE_ENV=development" >> "$CLAUDE_ENV_FILE"
echo "API_KEY=test-key" >> "$CLAUDE_ENV_FILE"

Common Setup Patterns

Node.js Project

#!/bin/bash
set -e

# Install dependencies
npm install

# Build if needed
if [ -f "tsconfig.json" ]; then
    npm run build 2>/dev/null || true
fi

# Set up environment
if [ ! -f ".env" ] && [ -f ".env.example" ]; then
    cp .env.example .env
fi

exit 0

Python Project

#!/bin/bash
set -e

# Create virtual environment if needed
if [ ! -d ".venv" ]; then
    python -m venv .venv
fi

# Activate and install
source .venv/bin/activate
pip install -r requirements.txt

# Set environment variables
echo "PYTHONPATH=$(pwd)" >> "$CLAUDE_ENV_FILE"

exit 0

Full-Stack Application

#!/bin/bash
set -e

# Backend setup
cd backend
pip install -r requirements.txt

# Frontend setup
cd ../frontend
npm install

# Database
cd ..
if command -v docker &> /dev/null; then
    docker-compose up -d db redis 2>/dev/null || true
fi

exit 0

Ruby Project

#!/bin/bash
set -e

# Set Ruby version if .ruby-version exists
if [ -f ".ruby-version" ]; then
    rbenv local $(cat .ruby-version) 2>/dev/null || true
fi

# Install gems
bundle install

exit 0

Go Project

#!/bin/bash
set -e

# Download dependencies
go mod download

# Build to verify
go build ./... 2>/dev/null || true

exit 0

Cloud Environment Details

Pre-installed Tools

The Claude Code web environment includes:

• Languages: Python 3.x, Node.js (LTS), Ruby 3.x, Go, Rust, Java, PHP
• Package Managers: npm, yarn, pnpm, bun, pip, poetry, uv, gem, bundler, cargo
• Databases: PostgreSQL 16, Redis 7.0
• Build Tools: gcc, clang, make, cmake

Check available tools with: check-tools

Network Access

Limited network access by default. Allowed domains include:

• Package registries (npm, PyPI, RubyGems, crates.io, etc.)
• GitHub, GitLab, Bitbucket
• Cloud providers (GCP, Azure, AWS)
• Container registries

Troubleshooting

Script Not Executing

1. Verify script is executable: chmod +x scripts/claude-setup.sh
2. Check shebang line: #!/bin/bash
3. Ensure script exits with 0 on success

Dependencies Not Installing

1. Check network access allows required domains
2. Use explicit package managers instead of auto-detection
3. Add set -e to fail fast on errors

Environment Variables Not Set

1. Write to $CLAUDE_ENV_FILE, not export
2. Use append (>>) not overwrite (>)
3. Verify file path: echo "VAR=value" >> "$CLAUDE_ENV_FILE"

Templates

See templates/ directory for ready-to-use setup scripts:

• templates/nodejs-setup.sh - Node.js/TypeScript projects
• templates/python-setup.sh - Python projects
• templates/fullstack-setup.sh - Full-stack applications

Related Resources

• Claude Code on the Web documentation
• Hooks Reference
• Settings Reference