Skip to content
Skills Library
AI & agents · Automation

hooks-session-start-hook

/hooks-session-start-hook

Create a SessionStart hook for Claude Code on the web. Use when setting up a repo so dependencies install and tests/linters run automatically on remote session start.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create a SessionStart hook for Claude Code on the web. Use when setting up a repo so dependencies install and tests/linters run automatically on remote session start.

Arguments

/hooks-session-start-hook --remote-only to only run in web sessions, --no-verify to skip test verification
Original author description

Create a SessionStart hook for Claude Code on the web. Use when setting up a repo so dependencies install and tests/linters run automatically on remote session start.

How it works

  1. When to Use This Skill
  2. Context
  3. Parameters
  4. Execution
  5. Post-Actions
  6. SessionStart Matcher Reference
  7. Agentic Optimizations
  8. Quick Reference
Original SKILL.md headings · 169 lines, 955 words
SKILL.md preview
---
name: hooks-session-start-hook
description: Create a SessionStart hook for Claude Code on the web. Use when setting up a repo so dependencies install and tests/linters run automatically on remote session start.
args: "[--remote-only] [--no-verify]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, TodoWrite
argument-hint: "--remote-only to only run in web sessions, --no-verify to skip test verification"
disable-model-invocation: true
created: 2026-02-07
modified: 2026-06-18
compatibility: claude-code
reviewed: 2026-03-30
---

# /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

| Use this skill when... | Use `/hooks:hooks-configuration` instead when... |
|---|---|
| Setting up a repo for Claude Code on the web | Configuring other hook types (PreToolUse, Stop, etc.) |
| Need automatic dependency install in web sessions | Need general hooks knowledge or debugging |
| Want tests/linters verified on session start | Writing custom hook logic from scratch |
| Onboarding a project to remote Claude Code | Understanding hook lifecycle events |

## 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

| Flag | Default | Description |
|---|---|---|
| `--remote-only` | off | Wrap script in `CLAUDE_CODE_REMOTE` guard — hook exits immediately in local sessions |
| `--no-verify` | off | Skip test/linter verification step in the generated script |

## Execution

### Step 1: Detect project stack

Identify all languages and tooling from the values in [Context](#context).

**Language detection:**

| File Present | Language | Package Manager (from lockfile) |
|---|---|---|
| `package.json` | Node.js | npm (`package-lock.json`), yarn (`yarn.lock`), pnpm (`pnpm-lock.yaml`), bun (`bun.lockb`) |
| `pyproject.toml` | Python | poetry (`poetry.lock`), uv (`uv.lock`), pip (fallback) |
| `requirements.txt` | Python | pip |
| `Cargo.toml` | Rust | cargo |
| `go.mod` | Go | go modules |
| `Gemfile` | Ruby | bundler |
| `pom.xml` | Java | maven |
| `build.gradle*` | Java/Kotlin | gradle |

**Test runner detection:**

| Language | How to Detect | Test Command |
|---|---|---|
| Node.js | `scripts.test` in package.json | `npm test` / `bun test` / etc. |
| Python | `[tool.pytest]` in pyproject.toml, or `pytest` in deps | `pytest` |
| Rust | always available | `cargo test` |
| Go | always available | `go test ./...` |
| Ruby | Gemfile contains `rspec` or `minitest` | `bundle exec rspec` / `bundle exec rake test` |
| Java | pom.xml / build.gradle | `mvn test` / `gradle test` |

**Linter detection:**

| Config File | Linter | Command |
|---|---|---|
| `biome.json` / `biome.jsonc` | Biome | `npx biome check .` |
| `.eslintrc*` / `eslint.config.*` | ESLint | `npx eslint .` |
| `[tool.ruff]` in pyproject.toml | Ruff | `ruff check .` |
| `Cargo.toml` | Clippy | `cargo clippy` |

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](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:

```json
{
  "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

| Matcher | Fires When |
|---|---|
| `"startup"` | New session starts |
| `"resume"` | Session is resumed |
| `"clear"` | After `/clear` command |
| `"compact"` | After context compaction |
| `""` (empty) | All SessionStart events |

## Agentic Optimizations

| Context | Approach |
|---|---|
| Quick setup, skip verification | `/hooks:session-start-hook --remote-only --no-verify` |
| Full setup with verification | `/hooks:session-start-hook` |
| Web-only with tests | `/hooks:session-start-hook --remote-only` |
| Dependency install commands | Use `--frozen-lockfile` / `ci` variants for reproducibility |
| Test verification | Use `--bail=1` / `-x` for fast failure |
| Linter verification | Use `--max-diagnostics=0` / `--quiet` for pass/fail only |

## Quick Reference

| Item | Value |
|---|---|
| Script location | `scripts/claude-session-start.sh` or `.claude/hooks/session-start.sh` |
| Settings location | `.claude/settings.json` |
| Timeout | 120 seconds (adjustable) |
| Output format | JSON with `hookSpecificOutput.additionalContext` |
| Environment persistence | Via `CLAUDE_ENV_FILE` |
| Remote detection | `CLAUDE_CODE_REMOTE=true` |
Files in this package (2)
  • REFERENCE.md 3 KB
  • SKILL.md 7 KB

Versions

The database has no other skills named hooks-session-start-hook.

Database snapshot: 13.11.2026 · package version 17ac28661afb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90startup-hook-skill
    Creating and developing startup hooks for Claude Code on the web. Use when the user wants to set up a repository for Claude Code on the web, create a SessionStart hook to ensure their project can run tests and linters during web sessions.
  • 100write-hook
    Use when Claude Code should do something by itself - at session start (`SessionStart`), on every prompt (`UserPromptSubmit`), or after each response (`Stop`) - or when that automation misbehaves. Symptoms: a hook script that runs but whose output never reaches the model, a…
  • 100configure-repo
    Repo onboarding driver: .claude/ directory, SessionStart hook, install_pkgs.sh. Use when onboarding any repo to Claude Code with the claude-plugins marketplace.
  • 100claude-code-hook-development
    This skill should be used when the user asks to "create a hook", "add a hook", "write a hook", or mentions Claude Code hooks. Also suggest this skill when the user asks to "automatically do X" or "run X before/after Y" as these are good candidates for hooks.
  • 100create-hooks
    Expert guidance for creating, configuring, and using Claude Code hooks. Use when working with hooks, setting up event listeners, validating commands, automating workflows, adding notifications, or understanding hook types (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit, etc).
  • 100plugin-hooks
    Authoritative guide to Claude Code hooks — event-driven scripts that execute before or after tool calls, session events, file changes, and more. Use when writing a PreToolUse hook to block dangerous commands, a PostToolUse hook to auto-format after edits, a SessionStart hook to…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.