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