SessionStart hook for Claude Code web sessions to install tools (helm, terraform, gitleaks, just). Use when CI tools fail in remote sessions due to missing binaries.
SessionStart hook for Claude Code web sessions to install tools (helm, terraform, gitleaks, just). Use when CI tools fail in remote sessions due to missing binaries.
Has terraform: !find . -maxdepth 3 \( -name '*.tf' -o -type d -name 'terraform' \) -print -quit
Parameters
Parse from $ARGUMENTS:
--check-only: Report current state without creating or modifying files
--fix: Apply all changes automatically without prompting
--tools <list>: Comma-separated list of tool names to install (overrides auto-detection)
Supported: helm, , , , , , ,
terraform
tflint
actionlint
helm-docs
gitleaks
just
pre-commit
Execution
Execute this web-session dependency setup:
Step 1: Detect required tools
Auto-detect which tools are needed from project signals:
Signal
Tools needed
.pre-commit-config.yaml contains gitleaks
gitleaks, pre-commit
.pre-commit-config.yaml contains actionlint
actionlint, pre-commit
.pre-commit-config.yaml contains tflint
tflint, pre-commit
.pre-commit-config.yaml contains helm
helm, helm-docs, pre-commit
Chart.yaml exists anywhere
helm, helm-docs
*.tf or terraform/ directory exists
terraform, tflint
Justfile or justfile exists
just
--tools flag provided
Use that list exactly
Any pre-commit hook present
pre-commit
Step 2: Check existing configuration
Read .claude/settings.json if it exists
Look for a SessionStart hook that references install_pkgs.sh
Check scripts/install_pkgs.sh for completeness — verify each detected tool has an install block
Report current status:
Item
Status
scripts/install_pkgs.sh exists
EXISTS / MISSING
SessionStart hook configured
CONFIGURED / MISSING
Tools covered in install script
List each: PRESENT / ABSENT
Step 2b: Detect spec drift in an already-onboarded repo
An install_pkgs.sh that merely exists reads as compliant even when the
canonical spec has moved on — the gap is invisible until a manual audit (see
issue #1670). When the repo is already onboarded, compare the existing files
against the current spec and report each item as PRESENT / DRIFT / ABSENT.
Treat any DRIFT or ABSENT as a re-apply trigger, not a no-op:
Spec item
Drift signal to check
Renovate-managed pins
Each <TOOL>_VERSION="x.y.z" line carries a # renovate: datasource=... depName=... annotation (Step 3). A bare pin is DRIFT.
Pinned versions current
Each pinned version matches the Step 3 reference. A pin behind reference (e.g. gitleaks 8.30.0 vs 8.30.1, just 1.40.0 vs 1.52.0) is DRIFT.
scripts/path-bootstrap.sh wired first
path-bootstrap.sh exists and runs as the first SessionStart hook before install_pkgs.sh (Step 5). Missing or out-of-order is DRIFT.
Allowlist-safe downloads
No runtime api.github.com/.../releases/latest lookups — api.github.com is outside the web "Limited" allowlist and breaks the install. A latest lookup is DRIFT; replace with a pinned github.com/.../releases/download/<tag> URL.
Remote + idempotency guards
The CLAUDE_CODE_REMOTE guard and per-tool command -v guards are present (Step 4).
Report drift as a positive signal:
Spec item
Status
Renovate pin annotations
PRESENT / DRIFT / ABSENT
Pinned versions vs reference
CURRENT / STALE (list each stale tool)
path-bootstrap.sh wired first
PRESENT / DRIFT / ABSENT
Allowlist-safe downloads
OK / USES api.github.com
If --check-only is set, stop here and print the status + drift report. Otherwise,
re-apply the drifted items in Steps 3-5 (update pins, add Renovate annotations,
wire path-bootstrap.sh first, replace latest lookups with pinned URLs) so the
repo returns to spec.
Step 3: Build tool inventory
For each tool that needs to be installed, pin versions to match .pre-commit-config.yaml rev values where applicable. For tools not in pre-commit, use latest stable. Use this reference:
Tool
Install method
Version source
pre-commit
pip install pre-commit
latest
helm
Official get-helm-3 script from raw.githubusercontent.com
latest stable
terraform
Binary from releases.hashicorp.com (.zip)
Pin to .pre-commit-config.yaml rev or latest
tflint
GitHub release binary (.zip)
Pin to .pre-commit-config.yaml rev
actionlint
GitHub release binary (.tar.gz)
Pin to .pre-commit-config.yaml rev
helm-docs
GitHub release binary (.tar.gz)
Pin to .pre-commit-config.yaml rev
gitleaks
GitHub release binary (.tar.gz)
Pin to .pre-commit-config.yaml rev
just
GitHub release binary (.tar.gz)
latest stable
All download sources are compatible with the "Limited" network allowlist (github.com, releases.hashicorp.com, raw.githubusercontent.com, pypi.org).
Keep the pins fresh, not hand-maintained. Annotate each <TOOL>_VERSION="x.y.z" line with a # renovate: datasource=... depName=... comment and add a matching customManager to renovate.json so the pins are auto-updated rather than rotting (see .claude/rules/version-pinning.md). Where a tool's version is also pinned in .pre-commit-config.yaml (e.g. gitleaks), enable Renovate's pre-commit manager and group the dep so both bump in lockstep.
Step 4: Create or update scripts/install_pkgs.sh
Create scripts/install_pkgs.sh with:
Remote guard — exit immediately if not in a remote session:
if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; thenexit 0
fi
Idempotency guard per tool — use command -v <tool> before downloading:
if ! command -v helm >/dev/null 2>&1; then# install helmfi
Install to ~/.local/bin — writable without sudo regardless of whether the session runs as root. Ensure this directory is on the PATH that agent subshells inherit: add it to a path-bootstrap.sh SessionStart hook (see this repo's scripts/path-bootstrap.sh) or append it to $CLAUDE_ENV_FILE. A bare export PATH=... inside the install script does not persist to later tool calls (see .claude/rules/sandbox-guidance.md).
Temp directory cleanup — use a temp dir per download, remove it after:
tmp_dir=$(mktemp -d)
# ... download and extract ...rm -rf "$tmp_dir"
unzip bootstrap — terraform and tflint ship as .zip; install unzip via apt if absent.
One install block per tool in this order: pre-commit, helm, terraform, tflint, actionlint, helm-docs, gitleaks, just.
Make the script executable: chmod +x scripts/install_pkgs.sh
Step 5: Update .claude/settings.json
Read existing .claude/settings.json (or start from {} if absent)
Preserve all existing permissions and other keys — do not overwrite them.
Step 6: Verify and summarise
Print a final summary:
Web session configuration complete
===================================
scripts/install_pkgs.sh [CREATED/UPDATED]
.claude/settings.json [CREATED/UPDATED]
Tools configured: helm, terraform, tflint, actionlint, gitleaks, just, pre-commit
Next steps:
1. Commit both files: git add scripts/install_pkgs.sh .claude/settings.json
2. Smoke-test locally: CLAUDE_CODE_REMOTE=true bash scripts/install_pkgs.sh
3. Run again to verify idempotency: CLAUDE_CODE_REMOTE=true bash scripts/install_pkgs.sh
4. Start a remote session on claude.ai/code and confirm tools are available
Step 7: Re-audit onboarded repos after a spec change (portfolio sweep)
When the canonical spec itself changes (new pinned tool, a wired-first
path-bootstrap.sh, a download-source fix), every previously-onboarded repo
silently falls out of spec — install_pkgs.sh still "exists", so nothing flags
the drift (issue #1670). Make drift a positive signal: re-audit the whole
portfolio rather than waiting for a manual cross-repo check.
Run /configure:web-session --check-only in each repo that already has
scripts/install_pkgs.sh and collect the Step 2b drift reports. A thin sweep
helper over the onboarded repos turns the silent non-event into an explicit
PRESENT/DRIFT/ABSENT list — find the onboarded repos, then re-audit each:
For each repo that reports DRIFT/ABSENT, run the full /configure:web-session
(no --check-only) so Steps 3-5 re-apply the current spec, then open one PR per
repo. Surface the deltas as a table so the sweep result is reviewable at a glance.
