Session manager

Session Manager Skill

Context is loaded at SessionStart by hooks/session-start-context.sh. This skill only handles end-of-session logging (/end) and explicit resume requests (/resume).

Manage development session lifecycle for multi-project work. Eliminates Claude Code "amnesia" by maintaining session logs and project context in an Obsidian vault.

Vault Location

Default: ~/vault/ Override with env var: VAULT_PATH

Commands

/resume

Explicit re-load of project context. The SessionStart hook (hooks/session-start-context.sh) already loads context at session start — use this command only to force a re-read mid-session (e.g., after manually editing context.md or after switching projects).

VAULT="${VAULT_PATH:-$HOME/vault}"
PROJECT_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
PROJECT_DIR="$VAULT/projects/$PROJECT_NAME"
CURRENT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

# SSR-01: if the SessionStart hook already loaded context <60 min ago,
# skip redundant cat — context is already in the model's prompt.
MARKER="$CURRENT_DIR/.claude/.session-loaded"
if [ -f "$MARKER" ]; then
  NOW=$(date +%s)
  MTIME=$(stat -f %m "$MARKER" 2>/dev/null || stat -c %Y "$MARKER" 2>/dev/null || echo 0)
  AGE=$(( NOW - MTIME ))
  if [ "$AGE" -lt 3600 ] && [ "$AGE" -ge 0 ]; then
    echo "📋 Context pre-loaded at $(cat "$MARKER" 2>/dev/null) by SessionStart hook — skipping redundant cat."
    return 0 2>/dev/null || exit 0
  fi
fi

cat "$PROJECT_DIR/context.md" 2>/dev/null || echo "No context.md found for $PROJECT_NAME"

# Last 3 session logs
for f in $(ls -t "$PROJECT_DIR/sessions/"*.md 2>/dev/null | head -3); do
  echo "=== $(basename "$f") ==="
  cat "$f"
  echo ""
done

/end or /done

Create session log and update context.

PROJECT_NAME=$(basename $(git rev-parse --show-toplevel 2>/dev/null || pwd))
VAULT=${VAULT_PATH:-~/vault}
PROJECT_DIR="$VAULT/projects/$PROJECT_NAME"
SESSION_FILE="$PROJECT_DIR/sessions/$(date +%Y-%m-%d)-SESSION_SLUG.md"

# Create session log
cat > "$SESSION_FILE" << 'EOF'
# Session: DATE — DESCRIPTION

## Что сделано
- (list concrete changes: files modified, features added, bugs fixed)

## Решения
- (architectural decisions made, if any)

## TODO на следующую сессию
- [ ] (specific actionable items)

## Проблемы
- (bugs encountered, workarounds used, tech debt noted)

## Изменённые файлы
- (list key files that were modified)

## Зависимости
- (new packages added, version changes)
EOF

# Update context.md "Session History" section (D-01, D-02)
# Invokes the same Node wrapper the Stop hook uses — idempotent by filename.
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && pwd)"
UPDATER="$REPO_ROOT/hooks/update-context.mjs"
if [ -f "$UPDATER" ]; then
  VAULT_PATH="$VAULT" CDS_PROJECT_NAME="$PROJECT_NAME" \
    node "$UPDATER" "$(basename "$SESSION_FILE")" 2>/dev/null || true
fi

# ── Auto-ADR Capture (Phase 26, ADR-02) ────────────────────────
# Scans the session transcript and writes architectural decisions to vault.
# Fail-open: never blocks /end if the bridge errors.
ADR_BRIDGE="$REPO_ROOT/lib/adr-bridge-session.mjs"
if [ -f "$ADR_BRIDGE" ]; then
  # SESSION_ID may be substituted by Claude from its runtime context.
  # If unset, the bridge falls back to most-recent-mtime JSONL detection.
  ADR_RESULT=$(VAULT_PATH="$VAULT" CDS_PROJECT_NAME="$PROJECT_NAME" \
    node "$ADR_BRIDGE" \
    --session-log "$(basename "$SESSION_FILE")" \
    --cwd "$REPO_ROOT" \
    ${SESSION_ID:+--session-id "$SESSION_ID"} \
    2>/dev/null) || ADR_RESULT='{"newAdrs":[],"superseded":[],"error":"bridge failed"}'
  # ADR_RESULT is valid JSON: {"newAdrs":[...],"superseded":[...],"error":null|string}
  # Claude reads this variable and formats a one-line summary for the user.
  echo "$ADR_RESULT"
fi
# ────────────────────────────────────────────────────────────

Replace SESSION_SLUG with a kebab-case summary (e.g., "fix-auth-flow", "add-telegram-pipeline"). Replace placeholders with actual session data.

After session log and context.md are updated, auto-ADR capture runs (Phase 26 — D-04).

/handoff

Generate a comprehensive handoff document for continuing work in a new session or by another developer.

PROJECT_NAME=$(basename $(git rev-parse --show-toplevel 2>/dev/null || pwd))
VAULT=${VAULT_PATH:-~/vault}

# Generate handoff
echo "# Handoff: $PROJECT_NAME — $(date +%Y-%m-%d)"
echo ""
echo "## Current State"
cat "$VAULT/projects/$PROJECT_NAME/context.md"
echo ""
echo "## Recent Changes (git)"
git log --oneline -10 2>/dev/null
echo ""
echo "## Uncommitted Changes"
git diff --stat 2>/dev/null
echo ""
echo "## Active TODO"
grep -r "TODO" "$VAULT/projects/$PROJECT_NAME/sessions/" 2>/dev/null | tail -20

/status

Quick overview of all projects.

VAULT=${VAULT_PATH:-~/vault}
echo "# Project Status Overview"
echo ""
for dir in "$VAULT/projects"/*/; do
  [ "$(basename $dir)" = "_template" ] && continue
  project=$(basename "$dir")
  last_session=$(ls -t "$dir/sessions/"*.md 2>/dev/null | head -1)
  if [ -n "$last_session" ]; then
    last_date=$(basename "$last_session" | cut -d'-' -f1-3)
    echo "## $project (last: $last_date)"
    grep "^- \[ \]" "$last_session" 2>/dev/null | head -5
  else
    echo "## $project (no sessions yet)"
  fi
  echo ""
done

Auto-ADR Capture (Phase 26 — D-04, D-05)

After the /end bash block runs, $ADR_RESULT contains a JSON summary of ADRs created or superseded during the session. Claude reads this and reports a one-line summary to the user:

• If newAdrs or superseded is non-empty: Session logged. {N} new ADRs (#NNNN topic, ...). {M} superseded (#NNNN topic, ...).
• If both empty: Session logged. (stay silent about ADRs)
• If error is non-null: Session logged. (ADR capture unavailable: {reason})

Never block /end on ADR capture. If the bridge errors, complete the flow silently.

The bridge is lib/adr-bridge-session.mjs in the project repo. It uses Claude Haiku 4.5 via claude -p subprocess to extract decisions from the session transcript and writes them to vault/projects/{project}/decisions/ following the template in D-10.

ADR Creation

When an architectural decision is made during the session:

VAULT=${VAULT_PATH:-~/vault}
PROJECT_NAME=$(basename $(git rev-parse --show-toplevel 2>/dev/null || pwd))
ADR_DIR="$VAULT/projects/$PROJECT_NAME/decisions"
NEXT_NUM=$(printf "%04d" $(($(ls "$ADR_DIR"/*.md 2>/dev/null | wc -l) + 1)))

cat > "$ADR_DIR/${NEXT_NUM}-DECISION_SLUG.md" << 'EOF'
# ADR-NNNN: Title

**Дата**: YYYY-MM-DD
**Статус**: accepted

## Контекст
Why the question arose

## Решение
What we chose

## Альтернативы
What we considered and why we rejected it

## Последствия
What this changes in the project
EOF

Best Practices

1. Context loads automatically at SessionStart — use /resume only to force a re-read mid-session
2. Always use /end at session end — future you will thank you
3. ADRs are cheap to write and expensive to not have
4. Session logs should be specific: file names, function names, not vague descriptions
5. TODOs should be actionable: "implement X in file Y" not "finish feature"