Continue Here

Write a structured continuation file so the next session starts with full context.

When to Use

• Ending a session with work still in progress
• Handing off a complex task between sessions
• Preserving intent, failed approaches, and next steps that git cannot capture
• Before closing Claude Code when mid-task

Inputs

• Required: An active session with recent work to summarize
• Optional: Specific instructions about what to emphasize in the handoff

Procedure

Step 1: Assess Session State

Gather facts about recent work:

git log --oneline -5
git status
git diff --stat

Review the conversation context: what was the objective, what was completed, what is partially done, what was tried and failed, what decisions were made.

Expected: Clear understanding of current task state — completed items, in-progress items, and planned next steps.

On failure: If not in a git repository, skip git commands. The continuation file can still capture conversational context and task state.

Step 2: Write CONTINUE_HERE.md

Write the file to the project root using the structure below. Every section must contain actionable content, not placeholders.

# Continue Here

> Last updated: YYYY-MM-DDTHH:MM:SSZ | Branch: current-branch-name

## Objective
One-paragraph description of what we are trying to accomplish and why.

## Completed
- [x] Finished item with key file paths (e.g., `src/feature.R`)
- [x] Decisions made and their rationale

## In Progress
- [ ] Partially complete work — describe current state (branch, file:line)
- [ ] Known issues with partial work

## Next Steps
1. Immediate next action (most important)
2. Subsequent actions in priority order
3. **[USER]** Items needing user input or decision

## Context
- Failed approaches and why they did not work
- Key constraints or trade-offs discovered
- Relevant issue/PR links

Guidelines:

• Objective: Capture the WHY — git log shows what changed, not why
• Completed: Mark items clearly done to prevent re-work
• In Progress: This is the highest-value section — partial state is hardest to reconstruct
• Next Steps: Number by priority. Prefix user-dependent items with **[USER]**
• Context: Record negative space — what was tried and rejected, and why

Expected: A CONTINUE_HERE.md file at the project root with all 5 sections populated with real content from the current session. The timestamp and branch are accurate.

On failure: If Write fails, check file permissions. The file should be created in the project root (same directory as .git/). Verify .gitignore contains CONTINUE_HERE.md — if not, add it.

Step 3: Verify the File

Read back CONTINUE_HERE.md and confirm:

• Timestamp is current (within the last few minutes)
• Branch name matches git branch --show-current
• All 5 sections contain real content (no template placeholders)
• Next Steps are numbered and actionable
• In Progress items describe current state specifically enough to resume

Expected: The file reads as a clear, actionable handoff that a fresh session could use to immediately resume work.

On failure: Edit sections that contain placeholder text or are too vague. Each section should pass the test: "Could a fresh session act on this without asking clarifying questions?"

Step 4: Configure SessionStart Hook (Optional)

If not already configured, set up automatic reading of CONTINUE_HERE.md on session start.

Create the hook script:

mkdir -p ~/.claude/hooks/continue-here

cat > ~/.claude/hooks/continue-here/read-continuation.sh << 'SCRIPT'
#!/bin/bash
# SessionStart hook: inject CONTINUE_HERE.md into session context
# OS-aware: works on native Linux, WSL, macOS, and Windows (Git Bash/MSYS)
set -uo pipefail

# --- Platform detection ---
detect_platform() {
  case "$(uname -s)" in
    Darwin) echo "mac" ;;
    Linux)
      if grep -qi microsoft /proc/version 2>/dev/null; then
        echo "wsl"
      else
        echo "linux"
      fi ;;
    MINGW*|MSYS*|CYGWIN*) echo "windows" ;;
    *) echo "unknown" ;;
  esac
}
PLATFORM=${PLATFORM:-$(detect_platform)}

CONTINUE_FILE="$PWD/CONTINUE_HERE.md"

if [ ! -f "$CONTINUE_FILE" ]; then
  exit 0
fi

# Strip CRLF (files on NTFS often have Windows line endings)
CONTENT=$(sed 's/\r$//' "$CONTINUE_FILE")

# JSON-escape: prefer jq, fall back to portable awk
if command -v jq >/dev/null 2>&1; then
  ESCAPED=$(printf '%s' "$CONTENT" | jq -Rsa .)
else
  ESCAPED=$(printf '%s' "$CONTENT" | awk '
    BEGIN { ORS=""; print "\"" }
    {
      gsub(/\\/, "\\\\")
      gsub(/"/, "\\\"")
      gsub(/\t/, "\\t")
      if (NR > 1) print "\\n"
      print
    }
    END { print "\"" }
  ')
fi

cat << EOF
{"hookSpecificOutput":{"sessionStartContext":{"additionalContext":$ESCAPED}}}
EOF
SCRIPT

chmod +x ~/.claude/hooks/continue-here/read-continuation.sh

Add to ~/.claude/settings.json in the SessionStart hooks array:

{
  "type": "command",
  "command": "~/.claude/hooks/continue-here/read-continuation.sh",
  "timeout": 5
}

Expected: The hook script exists, is executable, and is registered in settings.json. On next session start, if CONTINUE_HERE.md exists, its content is injected into the session context.

On failure: Check that settings.json is valid JSON after editing. Test the hook manually: cd /your/project && ~/.claude/hooks/continue-here/read-continuation.sh. The script falls back to awk if jq is not installed, so jq is recommended but not required.

Step 5: Add CLAUDE.md Instruction (Optional)

Add a brief instruction to the project's CLAUDE.md so Claude understands the file's purpose:

## Session Continuity

If `CONTINUE_HERE.md` exists in the project root, read it at session start. It contains a structured handoff from a prior session: objective, completed work, in-progress state, next steps, and context. Act on it — acknowledge the continuation, summarize prior state, and propose resuming from the Next Steps section. If the file is older than 24 hours, flag this to the user before proceeding. After the handoff is consumed, the file can be deleted.

Expected: CLAUDE.md contains the instruction. Future sessions will read and act on CONTINUE_HERE.md even if the SessionStart hook is not configured.

On failure: If CLAUDE.md does not exist, create it with just this section. If the file is too long, add the instruction near the top where it will not be truncated.

Validation

• CONTINUE_HERE.md exists at the project root
• File contains all 5 sections with real content (not placeholders)
• Timestamp and branch are accurate
• .gitignore includes CONTINUE_HERE.md
• Next Steps are numbered and actionable
• In Progress items specify enough detail to resume without questions
• (Optional) SessionStart hook script exists and is executable
• (Optional) CLAUDE.md contains the session continuity instruction

Common Pitfalls

• Writing placeholders instead of content: "TODO: fill in later" defeats the purpose. Every section must contain real information from the current session.
• Duplicating git state: Do not list every file changed — git already tracks that. Focus on intent, partial state, and next steps.
• Forgetting the Context section: Failed approaches are the most valuable thing to record. Without them, the next session will retry the same dead ends.
• Overwriting without reading: If CONTINUE_HERE.md already exists from a prior session, read it first — it may contain unfinished work from an earlier handoff.
• Leaving stale files: CONTINUE_HERE.md is ephemeral. After the next session consumes it, delete it. Stale files cause confusion.

Related Skills

• bootstrap-agent-identity — cold-start identity reconstruction that consumes the continuation file this skill produces
• manage-memory — durable cross-session knowledge (complements this ephemeral handoff)
• commit-changes — save work to git before writing the continuation file
• write-claude-md — project instructions where the optional continuity guidance lives