Feature Request: Session Handoff / Continuity Support

[patrickhardiman]

Feature Request: Session Handoff / Continuity Support

For: Claude Code CLI (https://github.com/anthropics/claude-code)
Proposed By: Patrick Hardiman (systems integrator, MeritWorks platform development)
Date: 2025-11-11

---

Problem Statement

Current Limitation: Claude CLI sessions are stateless. When a session ends, context and pending tasks are lost unless manually documented by the user.

Real-World Impact:

• Multi-day workflows require users to manually brief Claude at session start ("we were working on X, next step is Y")
• Complex projects lose momentum between sessions
• Users must maintain external task lists or rely on memory
• No built-in way to track project progression over time
• Onboarding new team members requires explaining full project history

Example Scenario:

Day 1 Session: Set up infrastructure, configure integrations (80% complete)
           End: User exits session with pending tasks
Day 2 Session: User starts fresh, must re-explain context
           Problem: Wasted time, potential missed tasks

---

Proposed Solution

Add built-in session handoff support to Claude Code CLI via a standardized continuity file.

Core Mechanism

.claude/handoff.md - Standardized file for passing context between sessions

Automatic Behavior:

1. SessionEnd: Prompt Claude to write .claude/handoff.md with pending tasks
2. SessionStart: Auto-read .claude/handoff.md and incorporate into session context
3. Auto-Archive: Move previous handoffs to .claude/session-history/YYYY-MM-DD.md

File Format (Suggested)

# Session Handoff - [Date]

## Completed This Session
- ✅ Task 1
- ✅ Task 2

## Pending for Next Session
- [ ] Priority 1 task
- [ ] Priority 2 task

## Context Notes
- Key decision made: ...
- Blocker discovered: ...
- Reference files: ...

## Next Steps
1. First thing to do
2. Second thing to do

---

Implementation Options

Option A: Automatic (Recommended)

SessionEnd Hook:

{
  "hooks": {
    "SessionEnd": {
      "type": "prompt",
      "prompt": "Review current session state. Write .claude/handoff.md with completed tasks, pending tasks, context notes, and next steps."
    }
  }
}

SessionStart Hook:

{
  "hooks": {
    "SessionStart": {
      "type": "prompt",
      "prompt": "Check for .claude/handoff.md. If exists: (1) Read and incorporate into session context, (2) Archive to .claude/session-history/YYYY-MM-DD.md, (3) Present summary to user"
    }
  }
}

User Experience:

$ claude

Claude Code CLI starting...
📋 Previous session handoff found (2025-11-10)

Completed last session:
✅ Jira MCP integration configured
✅ Credentials secured

Pending tasks:
• Test Jira MCP connection
• Create MW-* projects
• Build jira-orchestrator agent

Ready to continue where we left off!

User: Let's do it

Option B: Manual (Opt-In)

Add CLI flag for users who want control:

$ claude --save-session     # Prompt for handoff at end
$ claude --load-session     # Read handoff at start

Option C: Configuration Setting

{
  "sessionHandoff": {
    "enabled": true,
    "autoSave": true,
    "autoLoad": true,
    "archiveHistory": true
  }
}

---

Benefits

For Individual Developers

• ✅ Zero context loss between sessions
• ✅ Explicit task tracking (no guessing "where were we?")
• ✅ Multi-day workflow support (setup → build → test → deploy)
• ✅ Built-in project history (session-history/ shows progression)
• ✅ Reduced cognitive load (Claude reminds you what's pending)

For Teams

• ✅ Knowledge transfer (developer A leaves handoff for developer B)
• ✅ Onboarding (new team members read project handoff)
• ✅ Collaboration (team shares Claude sessions via git)
• ✅ Accountability (handoff shows what was actually completed)

For Claude

• ✅ Better context continuity (Claude knows project state)
• ✅ More effective assistance (understands what's pending)
• ✅ Reduced redundant explanations (user doesn't re-explain every session)

---

Proof of Concept

We've implemented this pattern manually for the MeritWorks platform and it works exceptionally well:

Our Implementation:

• .claude/next-session.md - Active handoff file
• .claude/session-history/ - Archive of previous handoffs
• Manual workflow: User asks Claude to write/read handoff files

Results:

• Seamless multi-session workflows (setup → test → deploy)
• Clear task progression across days
• Zero missed tasks or context loss
• Historical reference (what did we build last week?)

Files Created (can share examples):

• SESSION_HANDOFF_PATTERN.md - Documentation of our manual pattern
• next-session.md - Example handoff file with tasks/context

Validation: This feature request comes from real-world usage where we identified the need and prototyped a solution.

---

Use Cases

1. Complex Infrastructure Setup

Session 1: Install dependencies, configure services (70% done)
Handoff: "Next: Test MCP connection, create projects"
Session 2: Picks up exactly where left off

2. Multi-Step Workflows

Session 1: Design API schema
Handoff: "Next: Implement endpoints, write tests"
Session 2: Build endpoints
Handoff: "Next: Deploy to staging, run integration tests"
Session 3: Complete deployment

3. Team Collaboration

Developer A Session: "Investigated bug, found root cause in auth module"
Handoff: "Root cause: JWT validation timing issue. Fix: Update middleware."
Developer B Session: Reads handoff, implements fix

4. Long-Running Projects

Week 1: Foundation setup
Week 2: Core features
Week 3: Integration work
Each session reads previous week's handoff for continuity

---

Alternative Considered

Why not just use git commit messages or project management tools?

• Commit messages are code-focused (what changed), not session-focused (what's next)
• Project management tools (Jira, etc.) are external to Claude context
• Handoff files are Claude-specific context (what Claude needs to know)
• Lives in .claude/ directory (gitignored by default, optional to commit)
• Tighter integration: Claude reads/writes directly without external tools

Complementary, not replacement: Handoff files complement commits/PM tools, don't replace them.

---

Security & Privacy Considerations

File Location: .claude/handoff.md (local, not cloud-synced)

Gitignore by Default:

# .claude/.gitignore (auto-generated)
handoff.md
session-history/

Opt-In Sharing: Users can choose to commit handoffs to git for team sharing

No Sensitive Data: Guidelines to avoid credentials/secrets in handoff files

---

Configuration Options (Suggested)

{
  "sessionHandoff": {
    // Enable/disable feature
    "enabled": true,

    // Automatically save handoff at session end
    "autoSave": true,

    // Automatically load handoff at session start
    "autoLoad": true,

    // Archive previous handoffs to session-history/
    "archiveHistory": true,

    // Handoff file location (relative to .claude/)
    "handoffFile": "handoff.md",

    // Archive directory (relative to .claude/)
    "archiveDir": "session-history",

    // Archive filename format
    "archiveFormat": "YYYY-MM-DD-HHmm.md",

    // Prompt user before saving/loading
    "promptUser": false,

    // Maximum archive files to keep (0 = unlimited)
    "maxArchiveFiles": 100
  }
}

---

User Interface Suggestions

SessionEnd Prompt (if not automated)

Your session is ending. Would you like to save a handoff for the next session?

[Y/n]:

Claude will create .claude/handoff.md with:
• Completed tasks
• Pending tasks
• Context notes
• Next steps

SessionStart Message (if handoff found)

📋 Session handoff from 2025-11-10 17:34

Last session completed:
✅ Jira MCP integration
✅ Nomenclature updates

Pending for this session:
• Test MCP connection
• Create MW-* projects
• Build jira-orchestrator agent

Type 'show handoff' to see full details
Type 'clear handoff' to start fresh

CLI Commands (optional)

claude handoff save          # Manually save handoff
claude handoff load          # Manually load handoff
claude handoff show          # Display current handoff
claude handoff clear         # Clear handoff (start fresh)
claude handoff history       # List archived handoffs

---

Migration Path

Phase 1: Add basic handoff support (write/read files)
Phase 2: Add SessionStart/SessionEnd hooks
Phase 3: Add archive/history management
Phase 4: Add UI polish (prompts, commands)

Backward Compatibility:

• Disabled by default (opt-in via config)
• No breaking changes to existing workflows

---

Success Metrics

Adoption:

• % of users who enable sessionHandoff
• Number of handoff files created/read
• Session continuity rate (users who read previous handoff)

Impact:

• Reduced time to resume work (measure session start productivity)
• User satisfaction (survey: "Does handoff improve workflow?")
• Feature requests for enhancements (validates usefulness)

---

References

Similar Features in Other Tools:

• tmux: Session persistence (terminal state)
• Jupyter Notebooks: Cell state preservation
• Git: Commit messages (what changed, for code)
• Project Management: Kanban boards (task state)

What's Different:

• Handoff is Claude-specific context (not code, not tasks, but session state)
• Lightweight (markdown file, not database)
• Human-readable (can be edited manually)
• Version-controllable (optional git commit)

---

Example Handoff File (From MeritWorks)

# Session Handoff - Next Session Tasks

**Date Created**: 2025-11-11
**Previous Session**: Jira MCP Setup Complete
**Next Session**: Test Jira MCP & Create Projects

---

## ✅ What's Ready

- Jira MCP server installed and configured at `/meritworks/mcp-servers/jira/`
- Credentials in `.env` file (tested & working)
- Claude Code CLI configured with `.mcp.json` and `settings.local.json`
- MCP tools available: 22 Jira tools (create, update, search, sprint management)
- Nomenclature updated: MW-DEV, MW-BIZ, MW-EDU (MERITWORKS-*)

---

## 🎯 Tasks for Next Session

### Priority 1: Test Jira MCP Integration
- [ ] Verify MCP server loads (check available tools)
- [ ] List all Jira projects (should see CC, HSP, TPM)
- [ ] Test basic connectivity to hardimantech.atlassian.net

### Priority 2: Create MeritWorks Projects
- [ ] Create MW-DEV (MERITWORKS-DEV) - Development work
- [ ] Create MW-BIZ (MERITWORKS-BIZ) - Business tasks
- [ ] Create MW-EDU (MERITWORKS-EDU) - Curriculum development

### Priority 3: Create First Ticket
- [ ] Create MW-DEV-1: "Jira MCP Integration Complete"

---

## 📋 Next Steps After Testing

Once Jira MCP is verified:
1. Build jira-orchestrator agent
2. Document Socrates NAS architecture
3. Set up Moodle Dev environment

---

## 🔧 Troubleshooting Reference

If MCP server not available:
- Check `.mcp.json` exists in `/meritworks/`
- Verify `enableAllProjectMcpServers: true` in settings

---

## 💡 Notes from Previous Session

- Patrick loves the MERITWORKS-* naming - wants to see the brand everywhere
- Systems integrator mindset: making disparate systems work together
- Architecture split: Dev tools on WSL (when working), Socrates on NAS (always-on)

---

Conclusion

Session handoff support would significantly improve multi-session workflow continuity in Claude Code CLI.

Key Value:

• Solves real pain point (context loss between sessions)
• Simple implementation (markdown files + hooks)
• Proven useful (we're using manual version successfully)
• Broad applicability (individuals, teams, long-running projects)

Request: Consider adding this feature to Claude Code CLI. Happy to collaborate on implementation, provide feedback, or test beta versions.

---

Contact

Reporter: Patrick Hardiman
Email: patrick@hardimantech.com
Use Case: MeritWorks platform development (integration-heavy, multi-session workflows)
Prototype: Available in meritworks/.claude/ directory

Willing to:

• Provide detailed use case examples
• Test beta implementations
• Contribute to documentation
• Share feedback from real-world usage

---

This feature request comes from actual development work where we identified the need, prototyped a solution, and validated its usefulness. We believe it would benefit the broader Claude Code community.

[Derjyn]

That's a pretty clean implementation, but this domain is quite active right now. I've worked out a similar solution. So has the next person who might comment here, and thousands and thousands of others. There are numerous YouTube videos on the topic, papers, conversations about it at the local bar.

So this surfaces the question: what makes your solution better than mine, better than the guy sitting next to me on the bus, better than what Anthropic employees scaffold out on occasion?

It's definitely something that should be a native feature in Claude Code, but I wonder if it isn't because there are so many ways to tackle this - and many would rather take a day to establish their own framework for cross-session continuity, than adopt an opinionated external framework.

[towry]

https://ampcode.com/news/handoff

[patrickhardiman]

Thanks for the update, @towry. Awesome feature.

[sudoxreboot]

Strong support for this. Session handoff is table stakes for any serious development workflow.

Real scenario:

Day 1: Start complex refactoring task, build up context about codebase architecture, decisions made, approach chosen.

Day 2: Session is gone. Re-explain everything. Lose the nuance of why certain decisions were made.

Day 3: Same thing. Eventually give up on complex multi-day tasks in Claude Code.

What's needed:

1. Explicit session save - /save-session my-refactoring-project
2. Session resume - claude --resume my-refactoring-project
3. Session export - Portable format for backup/sharing
4. Auto-checkpoint - Periodic saves during long sessions

Integration with claude.ai:

Ideally, saved sessions could be accessible from claude.ai too. One context, multiple interfaces.

The ask:

Either implement session continuity, or permit users to build their own continuity tools by allowing programmatic access to our own sessions. We're paying $200/mo - we should be able to preserve our own work.