Bootstrap Prompt Generator
Generate a detailed context prompt that enables seamless continuation of work in a fresh Claude Code session.
Purpose
Sessions accumulate valuable context: task understanding, decisions made, patterns discovered, gotchas encountered, and progress achieved. When starting fresh, this knowledge is lost. A bootstrap prompt preserves the essential context needed to continue effectively.
Core Principle: Intelligent Context Selection
Do NOT mechanically dump everything. Analyze what actually matters for continuation:
- What would confuse a fresh Claude? Include it.
- What decisions took deliberation? Document the reasoning.
- What gotchas caused wasted time? Warn about them.
- What's the critical path forward? Clarify it.
Omit: routine operations, obvious context, resolved dead-ends, standard patterns.
Analysis Process
1. Assess Session Significance
Determine what kind of work occurred:
- Exploration: Learning codebase, investigating options
- Implementation: Building features, fixing bugs
- Debugging: Tracking down issues, testing hypotheses
- Planning: Designing architecture, making decisions
Each type has different handoff needs.
2. Identify Essential Context
Project State
- Working directory and project identity
- Tech stack if non-obvious
- Branch and git state (use
scripts/gather-git-state.sh)
Task Context
- Original objective (what the user asked for)
- Current interpretation (what we understood it to mean)
- Scope decisions (what's in/out)
Progress Assessment
- What's completed and working
- What's in progress and current state
- What's remaining (check todo list)
- What's blocked and why
Critical Knowledge
- Architectural decisions and their rationale
- Patterns established in this session
- Gotchas and workarounds discovered
- Files that are central to the work
Next Actions
- Immediate next step
- Remaining work outline
- Known unknowns to investigate
3. Determine Depth
Scale detail to session complexity:
Light session (quick task, simple fix): Brief summary, next step Medium session (feature work, debugging): Key decisions, progress, gotchas Deep session (architecture, complex debug): Full context with reasoning
Output Format
Generate a markdown document structured as a prompt for a fresh session:
# Bootstrap: [Brief Task Description]
> Generated: [timestamp]
> Project: [project path]
> Branch: [branch name]
## Context
[2-4 sentences on what this project/task is about]
## Session Summary
[What happened in the session - decisions, progress, discoveries]
## Current State
[Where things stand right now - what works, what's in progress]
## Key Files
[List of files central to the work with brief descriptions]
## Decisions Made
[Important choices with brief rationale - only if non-obvious]
## Gotchas & Warnings
[Things that caused problems or need careful handling]
## Next Steps
[Prioritized list of what to do next]
## Resume Instructions
[Specific guidance on how to continue - commands to run, files to open, etc.]Omit sections that aren't relevant. A simple task might only need Context, Current State, and Next Steps.
Execution Steps
- Analyze the session - Review conversation, understand what happened
- Run git state script - Execute
scripts/gather-git-state.shto capture repository state - Check todo list - Review current todos for progress context
- Identify key files - Determine which files are central to the work
- Draft bootstrap prompt - Write the document following the format above
- Determine output path - Use
.claude/handoffs/{project-name}-{YYYYMMDD-HHMMSS}.md - Save the file - Write the bootstrap prompt to the handoffs directory
- Copy to clipboard - Execute
scripts/copy-to-clipboard.sh {filepath}to copy contents
File Locations
- Output directory:
.claude/handoffs/(create if doesn't exist) - Filename pattern:
{project-name}-{YYYYMMDD-HHMMSS}.md - Project name: Derive from git remote, directory name, or package.json
Scripts
scripts/gather-git-state.sh
Collects repository state: branch, recent commits, uncommitted changes, modified files. Run this first to include accurate git context in the bootstrap prompt.
scripts/copy-to-clipboard.sh
Copies file contents to system clipboard (macOS pbcopy). Run after saving the bootstrap prompt file.
Quality Checklist
Before finalizing, verify:
- Fresh Claude could understand the task without prior context
- Decisions include enough rationale to avoid re-litigating
- Gotchas are specific enough to be actionable
- Next steps are concrete and prioritized
- No unnecessary detail that obscures the important parts
Example Bootstrap Prompts
Light Session Example
# Bootstrap: Fix API rate limiting bug
> Generated: 2025-01-15 14:30
> Project: /Users/dev/acme-api
> Branch: fix/rate-limiter
## Context
Fixing a bug where rate limiting wasn't being applied to the `/search` endpoint.
## Current State
Found the issue - the rate limiter middleware was added after the route registration.
Fix is ready but untested.
## Next Steps
1. Run test suite: `npm test`
2. If passing, commit with message "Fix rate limiter middleware order for /search"Deep Session Example
See references/deep-session-example.md for a complex multi-day project handoff.