#!/usr/bin/env bash # =============================================================== # claude-state-setup.sh # # Session continuity for Claude Code. Supersedes: # setup-claude-state.sh, crash-safety-addon.sh, # fix-source-aware-load.sh, doctor.sh, fix-headless-permissions.sh # # bash claude-state-setup.sh install / upgrade # bash claude-state-setup.sh --doctor diagnose only # # Fixed vs v1: # - every hook path uses $CLAUDE_PROJECT_DIR (monorepo safe) # - every script resolves the project root itself, never trusts cwd # - claude binary resolved to an absolute path (hooks lack your PATH) # - BSD/macOS safe: no `xargs -r`, stat handled both ways # - git gate only applies when actually inside a work tree # - source-aware SessionStart: no double-inject on --resume # - every hook logs why it did nothing # - headless run gets acceptEdits + scoped allowedTools (else Write # is auto-denied and the handoff silently never writes) # - recursion guard: the headless run cannot spawn another one # # Run from the REPO ROOT. Requires jq. # =============================================================== set -euo pipefail # --------------------------------------------------------------- # resolve the project root: git top-level, else cwd # --------------------------------------------------------------- ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" cd "$ROOT" echo "Project root: $ROOT" command -v jq >/dev/null 2>&1 || { echo "ERROR: jq required. brew install jq | sudo apt install jq" >&2; exit 1; } # --------------------------------------------------------------- # find claude, checking the places version managers hide it # --------------------------------------------------------------- find_claude() { local c c="$(command -v claude 2>/dev/null || true)" [ -n "$c" ] && { echo "$c"; return; } for p in "$HOME"/.nvm/versions/node/*/bin/claude \ "$HOME"/.local/bin/claude \ "$HOME"/.claude/local/claude \ "$HOME"/Library/pnpm/claude \ /opt/homebrew/bin/claude /usr/local/bin/claude; do [ -x "$p" ] && { echo "$p"; return; } done echo "" } CLAUDE_BIN="$(find_claude)" if [ -z "$CLAUDE_BIN" ]; then echo "WARN: could not locate the claude binary." echo " The SessionEnd fallback will be disabled until you set it." CLAUDE_BIN="claude" else echo "Claude binary: $CLAUDE_BIN" fi # =============================================================== # DOCTOR MODE # =============================================================== if [ "${1:-}" = "--doctor" ]; then ok(){ printf ' OK %s\n' "$1"; }; bad(){ printf ' FAIL %s\n' "$1"; } wrn(){ printf ' WARN %s\n' "$1"; } echo; echo "=== claude reachable from a bare (hook-like) env? ===" if env -i HOME="$HOME" PATH=/usr/local/bin:/usr/bin:/bin sh -c 'command -v claude' >/dev/null 2>&1 then ok "yes"; else wrn "no — that is why hooks need the absolute path"; fi [ -x "$CLAUDE_BIN" ] && ok "absolute path works: $CLAUDE_BIN" || bad "no usable claude binary" echo; echo "=== settings ===" if [ -f .claude/settings.json ]; then jq -e . .claude/settings.json >/dev/null 2>&1 && ok "valid JSON" || bad "malformed JSON" for e in SessionStart SessionEnd PreCompact Stop; do jq -e ".hooks.$e" .claude/settings.json >/dev/null 2>&1 && ok "$e registered" || bad "$e missing" done grep -q 'CLAUDE_PROJECT_DIR' .claude/settings.json \ && ok "uses \$CLAUDE_PROJECT_DIR" || bad "relative paths — breaks outside repo root" else bad ".claude/settings.json missing"; fi echo; echo "=== state ===" for f in handoff breadcrumb decisions; do [ -f ".claude/state/$f.md" ] && ok "$f.md ($(wc -c < ".claude/state/$f.md" | tr -d ' ') bytes)" \ || wrn "$f.md absent" done echo; echo "=== hook log (last 20) ===" tail -n 20 .claude/state/hooks.log 2>/dev/null | sed 's/^/ /' || echo " (no log yet)" echo; echo "=== live fire: SessionEnd ===" printf '{"hook_event_name":"SessionEnd","session_id":"DOCTOR","cwd":"%s","reason":"prompt_input_exit"}' "$ROOT" \ | bash .claude/hooks/save-state.sh tail -n 5 .claude/state/hooks.log 2>/dev/null | sed 's/^/ /' echo; echo "=== live fire: SessionStart source=resume ===" printf '{"hook_event_name":"SessionStart","source":"resume","cwd":"%s"}' "$ROOT" \ | bash .claude/hooks/load-state.sh | head -5 | sed 's/^/ /' exit 0 fi # =============================================================== # INSTALL # =============================================================== mkdir -p .claude/state .claude/hooks .claude/commands .claude/snapshots # --------------------------------------------------------------- # shared preamble sourced by every hook # --------------------------------------------------------------- cat > .claude/hooks/_common.sh <<'SH' # Sourced by every hook. Never trusts cwd. set -uo pipefail # CLAUDE_PROJECT_DIR is set by Claude Code. Fall back to git, then cwd. PROJ="${CLAUDE_PROJECT_DIR:-}" [ -z "$PROJ" ] && PROJ="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" cd "$PROJ" 2>/dev/null || exit 0 STATE="$PROJ/.claude/state" SNAPS="$PROJ/.claude/snapshots" LOG="$STATE/hooks.log" mkdir -p "$STATE" "$SNAPS" 2>/dev/null log() { printf '[%s] %s: %s\n' "$(date '+%F %T')" "${HOOK_NAME:-hook}" "$*" >> "$LOG"; } # mtime, GNU and BSD mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0; } age() { echo $(( $(date +%s) - $(mtime "$1") )); } in_git() { git rev-parse --is-inside-work-tree >/dev/null 2>&1; } jqf() { printf '%s' "$HOOK_INPUT" | jq -r "$1" 2>/dev/null || echo ""; } SH # --------------------------------------------------------------- # SessionStart — source aware # --------------------------------------------------------------- cat > .claude/hooks/load-state.sh <<'SH' #!/usr/bin/env bash HOOK_NAME=SessionStart HOOK_INPUT="$(cat 2>/dev/null || true)" DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" . "$DIR/_common.sh" SRC="$(jqf '.source // "startup"')"; [ -z "$SRC" ] && SRC=startup H="$STATE/handoff.md"; B="$STATE/breadcrumb.md"; D="$STATE/decisions.md" newer() { [ -f "$1" ] && { [ ! -f "$2" ] || [ "$1" -nt "$2" ]; }; } full_state() { echo "## Session handoff" [ -f "$H" ] && head -c 4000 "$H" || echo "(none)" if newer "$B" "$H"; then echo; echo "## WARNING: previous session ended without a handoff" echo "Breadcrumb is newer than the handoff, so the handoff is stale." echo "Trust git state over it."; echo head -c 2500 "$B" fi echo; echo "## Recent decisions"; tail -n 15 "$D" 2>/dev/null echo; echo "## Git" git status --short 2>/dev/null | head -n 20 git log --oneline -5 2>/dev/null } pointer() { echo "## State files (on disk, not loaded)" echo "- .claude/state/handoff.md (older than this conversation — prefer the thread above)" echo "- .claude/state/decisions.md (append-only, still authoritative)" } case "$SRC" in startup|fork|clear) full_state ;; resume) pointer ;; compact) echo "## Post-compaction anchor" echo "Detail was summarised away. Durable state on disk:" tail -n 15 "$D" 2>/dev/null git status --short 2>/dev/null | head -n 20 ;; *) pointer ;; esac log "source=$SRC" exit 0 SH # --------------------------------------------------------------- # Stop — zero-token breadcrumb # --------------------------------------------------------------- cat > .claude/hooks/breadcrumb.sh <<'SH' #!/usr/bin/env bash HOOK_NAME=Stop HOOK_INPUT="$(cat 2>/dev/null || true)" DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" . "$DIR/_common.sh" SID="$(jqf '.session_id // empty')" F="$STATE/breadcrumb.md"; T="$F.$$.tmp" { echo "# Breadcrumb — $(date '+%F %T') session ${SID:0:8}" echo "Auto-written every turn. No model call." echo; echo "## Uncommitted" git diff --stat 2>/dev/null | tail -n 25 git status --short 2>/dev/null | head -n 25 echo; echo "## Recent commits"; git log --oneline -5 2>/dev/null echo; echo "## Touched in last 60 min" find . -type f -mmin -60 \ -not -path './.git/*' -not -path './node_modules/*' \ -not -path './.claude/*' -not -path './dist/*' \ -not -path './.turbo/*' -not -path './.next/*' 2>/dev/null | head -n 25 echo; echo "## Exact-thread handle (only if git state is not enough)" echo "claude --resume $SID" } > "$T" 2>/dev/null && mv -f "$T" "$F" rm -f "$T" 2>/dev/null exit 0 SH # --------------------------------------------------------------- # SessionEnd — gated, logged, absolute binary # --------------------------------------------------------------- cat > .claude/hooks/save-state.sh <<'SH' #!/usr/bin/env bash HOOK_NAME=SessionEnd HOOK_INPUT="$(cat 2>/dev/null || true)" DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" . "$DIR/_common.sh" CLAUDE_BIN="__CLAUDE_BIN__" # --- recursion guard ------------------------------------------- # The headless run below is itself a Claude Code session, so it fires # SessionEnd too and would spawn another one. Stop that here. if [ "${CC_HANDOFF_CHILD:-0}" = "1" ]; then log "SKIP recursion guard (this IS the handoff run)"; exit 0 fi SID="$(jqf '.session_id // empty')" REASON="$(jqf '.reason // empty')" log "fired reason=$REASON sid=${SID:0:8} root=$PROJ" [ -x "$CLAUDE_BIN" ] || { log "ABORT no claude binary at $CLAUDE_BIN"; exit 0; } [ -n "$SID" ] || { log "ABORT no session_id (jq missing?)"; exit 0; } [ "$REASON" = "clear" ] && { log "SKIP /clear is not end of work"; exit 0; } if [ -f "$STATE/handoff.md" ]; then A="$(age "$STATE/handoff.md")" [ "$A" -lt 600 ] && { log "SKIP /wrap ran ${A}s ago"; exit 0; } fi # only gate on git when this really is a work tree if in_git && [ -z "$(git status --porcelain 2>/dev/null)" ]; then log "SKIP clean tree, nothing to summarise"; exit 0 fi PROMPT='Overwrite .claude/state/handoff.md with sections STATE, DECISIONS, FILES TOUCHED, NEXT 3 STEPS, OPEN QUESTIONS. Explicit file paths. Terse. Append any architectural decision as one line to .claude/state/decisions.md. Do not modify source files.' # -p is headless: it CANNOT show a permission prompt, so without these # two flags every Write is auto-denied and the file never changes. # Writes are scoped to .claude/state so this can never touch source. log "LAUNCH headless handoff (acceptEdits, writes scoped to .claude/state)" CC_HANDOFF_CHILD=1 nohup "$CLAUDE_BIN" -p --resume "$SID" \ --output-format json \ --permission-mode acceptEdits \ --allowedTools "Read" "Write(.claude/state/**)" "Edit(.claude/state/**)" \ "$PROMPT" >> "$LOG" 2>&1 & exit 0 SH # --------------------------------------------------------------- # PreCompact — snapshot, BSD-safe cleanup # --------------------------------------------------------------- cat > .claude/hooks/snapshot.sh <<'SH' #!/usr/bin/env bash HOOK_NAME=PreCompact HOOK_INPUT="$(cat 2>/dev/null || true)" DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" . "$DIR/_common.sh" TP="$(jqf '.transcript_path // empty')" TS="$(date +%Y%m%d-%H%M%S)" if [ -n "$TP" ] && [ -f "$TP" ]; then cp "$TP" "$SNAPS/pre-compact-$TS.jsonl" 2>/dev/null && log "saved transcript $TS" else log "transcript_path empty or missing — git state only" fi { git status --short; git log --oneline -10; } > "$SNAPS/pre-compact-$TS.git" 2>/dev/null # keep 10 most recent (no xargs -r: not portable to BSD) ls -1t "$SNAPS"/pre-compact-*.jsonl 2>/dev/null | tail -n +11 | while read -r f; do [ -n "$f" ] && rm -f "$f" done exit 0 SH sed -i.bak "s|__CLAUDE_BIN__|$CLAUDE_BIN|" .claude/hooks/save-state.sh rm -f .claude/hooks/save-state.sh.bak chmod +x .claude/hooks/*.sh # --------------------------------------------------------------- # state files # --------------------------------------------------------------- [ -f .claude/state/handoff.md ] || printf '# Handoff\n\n## STATE\n(nothing yet)\n\n## NEXT 3 STEPS\n1.\n2.\n3.\n\n## OPEN QUESTIONS\n-\n' > .claude/state/handoff.md [ -f .claude/state/decisions.md ] || printf '# Decisions (append-only)\n\nFormat: `YYYY-MM-DD | what | why | rejected alternative`\n' > .claude/state/decisions.md # --------------------------------------------------------------- # slash commands # --------------------------------------------------------------- cat > .claude/commands/wrap.md <<'MD' --- description: Write the session handoff before exiting --- Overwrite `.claude/state/handoff.md` with exactly these sections: ## STATE What works now, what is half-done. Two or three lines. ## DECISIONS Choices made this session and why. Omit if none. ## FILES TOUCHED Explicit paths, one per line, few words each. ## NEXT 3 STEPS Concrete. Not "continue work on X". ## OPEN QUESTIONS Genuinely unresolved only. Omit section if empty. Then append any architectural decision as one line to `.claude/state/decisions.md` as `YYYY-MM-DD | what | why | rejected`. Terse. No preamble. Do not touch source files. Then stop. MD cat > .claude/commands/pickup.md <<'MD' --- description: Re-read state files after a compaction --- Read `.claude/state/handoff.md` and the last 20 lines of `.claude/state/decisions.md`. State in three lines where we are and what is next. Do not start working until I confirm. MD # --------------------------------------------------------------- # settings.json — $CLAUDE_PROJECT_DIR everywhere # --------------------------------------------------------------- NEW_HOOKS='{ "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/load-state.sh\"" }] }], "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/save-state.sh\"" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/breadcrumb.sh\"" }] }], "PreCompact": [{ "matcher": "auto", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/snapshot.sh\"" }] }] }, "permissions": { "deny": ["Bash(rm -rf *)", "Bash(git push *)", "Bash(sudo *)"] } }' if [ -f .claude/settings.json ]; then cp .claude/settings.json .claude/settings.json.bak printf '%s' "$NEW_HOOKS" | jq -s '.[0] * .[1]' .claude/settings.json - \ > .claude/settings.json.tmp && mv .claude/settings.json.tmp .claude/settings.json echo "Merged hooks (backup: .claude/settings.json.bak)" else printf '%s\n' "$NEW_HOOKS" | jq . > .claude/settings.json echo "Created .claude/settings.json" fi # --------------------------------------------------------------- # CLAUDE.md pointer (survives compaction) # --------------------------------------------------------------- POINTER='## Session state Durable state lives on disk, not in this conversation: - `.claude/state/handoff.md` where we left off - `.claude/state/decisions.md` append-only decision log After a compaction, or whenever prior context is unclear, re-read both files instead of asking me to re-explain. After any task that modifies files, append one line to `.claude/state/decisions.md`.' if [ -f CLAUDE.md ]; then grep -q "Durable state lives on disk" CLAUDE.md || printf '\n%s\n' "$POINTER" >> CLAUDE.md else printf '%s\n' "$POINTER" > CLAUDE.md fi # --------------------------------------------------------------- # tmux wrapper — closing the window detaches instead of killing # --------------------------------------------------------------- cat > .claude/cc <<'SH' #!/usr/bin/env bash # ./.claude/cc [subdir] # Runs Claude in tmux from the REPO ROOT so hooks always resolve. ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" NAME="${1:-cc-$(basename "$ROOT")}" cd "$ROOT" || exit 1 if command -v tmux >/dev/null 2>&1; then exec tmux new-session -A -s "$NAME" "cd '$ROOT' && claude -n '$NAME'" else exec claude -n "$NAME" fi SH chmod +x .claude/cc touch .gitignore grep -q '.claude/snapshots' .gitignore || printf '\n.claude/snapshots/\n' >> .gitignore grep -q '.claude/state/hooks.log' .gitignore || printf '.claude/state/hooks.log\n' >> .gitignore grep -q '.claude/state/\*.tmp' .gitignore || printf '.claude/state/*.tmp\n' >> .gitignore cat <

All guides

Session State for Claude Code