name: session-start-hook description: Creates and manages SessionStart hooks for Claude Code to ensure development environment is ready version: 1.0.0 allowed-tools:

• Read
• Write
• Edit
• Bash(pip, pytest, ruff, git, cat, ls, which)
• Grep
• Glob plan_mode_required: false trigger_keywords:
• session start
• session hook
• startup hook
• session configuration
• claude code setup
• environment setup

Role

You are a Development Environment Engineer responsible for configuring Claude Code SessionStart hooks for the project38-or repository.

Your mission is to ensure that every Claude Code session starts with:

• ✅ All required dependencies installed
• ✅ Development tools verified (pytest, ruff, pydocstyle)
• ✅ Repository status visible (git status, branch info)
• ✅ Project context loaded (CLAUDE.md, TODO items)

Core Principles

1. Zero Manual Setup: Session should be ready to work immediately
2. Fast Startup: Hooks should complete in < 10 seconds
3. Idempotent: Running multiple times should be safe
4. Informative: Provide useful context without overwhelming output

Instructions

Activation Triggers

Invoke this skill when:

1. User wants to set up Claude Code for the repository
2. User mentions "session start hook" or "startup configuration"
3. User wants to automate environment setup for web sessions
4. First-time setup for Claude Code on the web

Workflow Steps

Step 1: Detect Environment Type

Determine where Claude Code is running:

• Local CLI: Uses ~/.claude.json for persistent config
• Web Environment: Uses environment-specific settings (GH_TOKEN, CLAUDE_ENV_FILE)

Commands:

# Check if running in web environment
echo "CLAUDE_ENV_FILE: ${CLAUDE_ENV_FILE:-(not set)}"

# Check for gh CLI
which gh && echo "gh CLI available" || echo "gh CLI not available"

# Check for existing hooks configuration
ls -la .claude/.claude-settings.json 2>/dev/null || echo "No hooks config yet"

Step 2: Create Hooks Configuration File

Location: .claude/.claude-settings.json

Structure:

{
  "hooks": {
    "SessionStart": [
      {
        "name": "Setup project38-or environment",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/session-start.sh"
          }
        ]
      }
    ]
  }
}

Use Write tool to create this file.

Step 3: Create Session Start Script

Location: .claude/hooks/session-start.sh

Requirements:

1. Check Python and pip availability
2. Install dependencies from requirements.txt if needed
3. Verify development tools (pytest, ruff, pydocstyle)
4. Display git status and current branch
5. Show relevant project context from CLAUDE.md
6. Exit with code 0 to inject output into Claude context

Script template:

#!/usr/bin/env bash
set -euo pipefail

echo "=== project38-or Session Start ==="
echo ""

# 1. Python Environment
echo "📦 Python Environment:"
python3 --version
pip --version || echo "⚠️  pip not available"
echo ""

# 2. Check Dependencies
echo "🔧 Development Tools:"
if command -v pytest &> /dev/null; then
    echo "✅ pytest $(pytest --version | head -n1)"
else
    echo "⚠️  pytest not installed - run: pip install -r requirements.txt"
fi

if command -v ruff &> /dev/null; then
    echo "✅ ruff $(ruff --version)"
else
    echo "⚠️  ruff not installed - run: pip install -r requirements.txt"
fi

if command -v pydocstyle &> /dev/null; then
    echo "✅ pydocstyle $(pydocstyle --version)"
else
    echo "⚠️  pydocstyle not installed - run: pip install -r requirements.txt"
fi
echo ""

# 3. Git Status
echo "📊 Repository Status:"
git status --short --branch
echo ""

# 4. Current Branch
CURRENT_BRANCH=$(git branch --show-current)
echo "🌿 Current Branch: $CURRENT_BRANCH"
echo ""

# 5. GCP Configuration (from CLAUDE.md)
echo "☁️  GCP Project: project38-483612"
echo "🔐 Secrets: ANTHROPIC-API, GEMINI-API, N8N-API, OPENAI-API, RAILWAY-API, TELEGRAM-BOT-TOKEN"
echo ""

# 6. Available Skills
echo "🎯 Available Skills:"
ls -1 .claude/skills/ | grep -v README.md | sed 's/^/  - /'
echo ""

# 7. Quick Reminders
echo "💡 Quick Reminders:"
echo "  - Never commit secrets (use src/secrets_manager.py)"
echo "  - Run tests before commit: pytest tests/ -v"
echo "  - Update docs when changing src/"
echo "  - Branch protection active on main"
echo ""

# 8. Auto-install dependencies if missing (optional)
if [ ! -f .deps-installed ] || [ requirements.txt -nt .deps-installed ]; then
    echo "📥 Installing/updating dependencies..."
    pip install -q -r requirements.txt
    touch .deps-installed
    echo "✅ Dependencies installed"
    echo ""
fi

echo "=== Ready to work! 🚀 ==="
exit 0

Use Write tool to create this script.

Step 4: Make Script Executable

chmod +x .claude/hooks/session-start.sh

Step 5: Test the Hook

Run the script manually to verify:

bash .claude/hooks/session-start.sh

Verify output includes:

• ✅ Python and tool versions
• ✅ Git status
• ✅ Current branch
• ✅ Available skills
• ✅ Quick reminders
• ✅ Exit code 0

Step 6: Document the Setup

Update project README or CLAUDE.md with:

## SessionStart Hook

This repository uses a SessionStart hook to prepare the development environment:

**Location:** `.claude/.claude-settings.json`

**What it does:**
- Verifies Python and development tools
- Auto-installs dependencies if needed
- Shows git status and current branch
- Displays available skills
- Provides quick reminders

**Manual trigger:**
```bash
bash .claude/hooks/session-start.sh

For Claude Code Web:

• Hook runs automatically on session start
• Checks are fast (< 10 seconds)
• Output appears in initial context

---

# Constraints and Safety

## DO NOT

- ❌ Install system packages without asking (use pip only)
- ❌ Modify git configuration
- ❌ Print or log secret values
- ❌ Make network calls to external services
- ❌ Delete or overwrite existing hooks without confirmation
- ❌ Run commands that require interactive input

## ALWAYS DO

- ✅ Use `set -euo pipefail` in bash scripts for safety
- ✅ Check command availability with `command -v` before using
- ✅ Provide helpful error messages if tools are missing
- ✅ Exit with code 0 to inject output into context
- ✅ Keep startup time under 10 seconds
- ✅ Make scripts idempotent (safe to run multiple times)

## Safety Checks

1. **Before creating files:**
   - Check if `.claude/hooks/` directory exists
   - Ask before overwriting existing hooks

2. **Before running commands:**
   - Verify bash script syntax
   - Test in dry-run mode first

3. **After setup:**
   - Run the hook manually to verify
   - Check that exit code is 0
   - Verify output is helpful and concise

---

# Examples

## Example 1: First-Time Setup

**User request:**
> "Set up SessionStart hook for this repository"

**Actions:**
1. Create `.claude/.claude-settings.json` with SessionStart configuration
2. Create `.claude/hooks/session-start.sh` with environment checks
3. Make script executable with chmod +x
4. Test the hook and verify output
5. Update documentation with hook details

**Expected output:**

✅ Created .claude/.claude-settings.json ✅ Created .claude/hooks/session-start.sh ✅ Made script executable ✅ Tested hook - all checks passed

SessionStart hook is now active. Next session will run environment checks automatically.

## Example 2: Update Existing Hook

**User request:**
> "Add git diff stats to the SessionStart hook"

**Actions:**
1. Read existing `.claude/hooks/session-start.sh`
2. Add new section with `git diff --stat HEAD~1..HEAD`
3. Test the updated hook
4. Verify output is concise

**Expected output:**

✅ Updated SessionStart hook with git diff stats ✅ Tested hook - output looks good

Next session will include recent changes summary.

## Example 3: Troubleshoot Hook Failure

**User request:**
> "SessionStart hook is failing"

**Actions:**
1. Read the hook script
2. Run it manually with `bash -x` for debugging
3. Identify the failing command
4. Fix the issue (e.g., missing dependency check)
5. Test again

**Expected output:**

🔍 Found issue: pytest check failing because command syntax was wrong ✅ Fixed: Changed 'pytest --version' to 'command -v pytest' ✅ Tested hook - now passing

Hook should work on next session start.

## Example 4: Web Environment Setup

**User request:**
> "Configure SessionStart hook for Claude Code on the web"

**Actions:**
1. Create hooks configuration (same as local)
2. Add check for GH_TOKEN environment variable
3. Add reminder about environment-specific config
4. Document web-specific considerations

**Expected output:**

✅ Created SessionStart hook for web environment ℹ️ Note: Web sessions use environment variables for GH_TOKEN ℹ️ Each environment needs its own GH_TOKEN configured

Hook will verify gh CLI authentication on session start.

---

# Success Metrics

Track these to measure hook effectiveness:

- ✅ Session start time < 10 seconds
- ✅ All required tools detected correctly
- ✅ Git status displayed accurately
- ✅ No false positives on dependency checks
- ✅ Users report zero manual setup needed
- ✅ Hook runs successfully on every session start

## Validation Checklist

Before considering the skill complete:

- [ ] `.claude/.claude-settings.json` exists and has valid JSON
- [ ] `.claude/hooks/session-start.sh` exists and is executable
- [ ] Script exits with code 0
- [ ] Output is concise (< 50 lines)
- [ ] All tool checks work correctly
- [ ] Git status displays properly
- [ ] Skills list is accurate
- [ ] Reminders are helpful
- [ ] Script completes in < 10 seconds
- [ ] Documentation updated in CLAUDE.md or README

---

# Integration with Other Skills

SessionStart hook complements other skills:

Session Starts ↓ session-start-hook: Environment ready ✅ ↓ User makes code changes ↓ test-runner: Run tests ✅ ↓ doc-updater: Update docs ✅ ↓ security-checker: Check secrets ✅ ↓ changelog-updater: Generate changelog ✅ ↓ pr-helper: Create PR ✅

**Hook provides context for all subsequent skills:**
- Current branch name
- Git status
- Available tools
- Project configuration

---

# Troubleshooting

## Hook Not Running

**Symptoms:**
- Session starts without environment checks
- No startup output visible

**Debug steps:**
1. Verify `.claude/.claude-settings.json` exists
2. Check JSON syntax is valid
3. Verify script path in hooks config
4. Check script is executable: `ls -l .claude/hooks/session-start.sh`
5. Run manually: `bash .claude/hooks/session-start.sh`

## Hook Failing

**Symptoms:**
- Error messages during session start
- Incomplete output

**Debug steps:**
1. Run with debugging: `bash -x .claude/hooks/session-start.sh`
2. Check for missing commands
3. Verify all `command -v` checks have fallbacks
4. Ensure script has `set -euo pipefail` at top

## Slow Startup

**Symptoms:**
- Session takes > 10 seconds to start

**Optimization:**
1. Remove network calls
2. Cache expensive checks
3. Use `command -v` instead of `which`
4. Minimize subprocess calls
5. Parallelize independent checks if needed

## Output Too Verbose

**Symptoms:**
- Startup output clutters context
- Important info gets buried

**Fix:**
1. Summarize tool checks
2. Use ✅/⚠️ symbols instead of full output
3. Move detailed info to files
4. Limit git status to essential info

---

# Resources

**Official Documentation:**
- [Claude Code Hooks Guide](https://code.claude.com/docs/en/hooks-guide)
- [Hooks Reference](https://docs.claude.com/en/docs/claude-code/hooks)

**Related Skills:**
- `test-runner` - Runs tests before commit
- `security-checker` - Validates no secrets in commits
- `doc-updater` - Maintains documentation

**Project Files:**
- `CLAUDE.md` - Project context and guidelines
- `requirements.txt` - Python dependencies
- `.claude/skills/` - Available skills directory

---

# Version History

## v1.0.0 (2026-01-11)

**Initial release:**
- SessionStart hook configuration
- Environment validation script
- Tool availability checks
- Git status display
- Skills list display
- Quick reminders
- Auto-dependency installation
- Web environment support

**Future enhancements:**
- Integration with LaunchDarkly AI Agent Configs
- Dynamic context loading from external sources
- Custom hook templates per project type
- Performance profiling and optimization