# Session Management Automatic Lifecycle Implementation Plan
## Executive Summary
This document outlines the implementation of automatic session lifecycle management for the session-buddy MCP server. The enhancement eliminates manual intervention for git-based projects while preserving manual control for non-git workflows.
## Core Architecture Changes
### 1. Automatic Session Lifecycle Detection
**Add FastMCP lifespan handlers to auto-detect client connections:**
- On connection: Check if in git repo → auto-run init logic
- On disconnection: Check if in git repo → auto-run end logic
- Non-git projects: No automatic actions, rely on manual commands
### 2. Enhanced Checkpoint with Auto-Compaction
**Modify checkpoint to execute compaction automatically:**
- When `should_suggest_compact()` returns true
- Execute session-buddy's internal compaction instead of recommending `/compact`
- Remove confusing "/compact" recommendations
### 3. Command Alias Strategy
**Keep strategic aliases for flexibility:**
- ✅ Keep `/start` → For manual init in non-git projects
- ✅ Keep `/end` → For manual cleanup in non-git projects
- ✅ Keep `/checkpoint` → Universal manual checkpointing
- ❌ Remove auto-hooks from settings.json (replaced by server-side detection)
## Implementation Details
### Phase 1: Core Server Changes
#### 1.1 Add Lifespan Management (session_buddy/server.py)
```python
@mcp.lifespan
async def session_lifecycle():
"""Automatic session lifecycle for git repositories only"""
from session_buddy.utils.git_operations import is_git_repository, get_git_root
current_dir = Path(os.getcwd())
# Only auto-initialize for git repositories
if is_git_repository(current_dir):
try:
git_root = get_git_root(current_dir)
logger.info(f"Git repository detected at {git_root}")
# Run the same logic as the init tool but silently
await _internal_session_init(auto_mode=True)
logger.info("✅ Auto-initialized session for git repository")
except Exception as e:
logger.warning(f"Auto-init failed (non-critical): {e}")
else:
logger.debug("Non-git directory - skipping auto-initialization")
yield # Server runs normally
# On disconnect - cleanup for git repos only
if is_git_repository(current_dir):
try:
await _internal_session_end(auto_mode=True)
logger.info("✅ Auto-ended session for git repository")
except Exception as e:
logger.warning(f"Auto-cleanup failed (non-critical): {e}")
```
#### 1.2 Enhanced Checkpoint with Auto-Compaction
```text
async def checkpoint(name: str | None = None) -> str:
"""Enhanced checkpoint with automatic compaction"""
# ... existing checkpoint logic ...
# Auto-compact when needed
should_compact, reason = should_suggest_compact()
if should_compact:
# Execute internal compaction instead of recommending
results.append("\n🔄 Automatic Compaction")
results.append(f"📊 Reason: {reason}")
try:
compact_result = await _execute_auto_compact()
results.append("✅ Context automatically optimized")
except Exception as e:
results.append(f"⚠️ Auto-compact skipped: {str(e)}")
# Remove old recommendation text
# DELETE: "🔄 RECOMMENDATION: Run /compact to optimize context"
```
### Phase 2: Documentation Updates
#### 2.1 Session-mgmt-mcp README.md Updates
Add new section after "Features":
```markdown
## 🚀 Automatic Session Management (NEW!)
**For Git Repositories:**
- ✅ **Automatic initialization** when Claude Code connects
- ✅ **Automatic cleanup** when session ends (quit, crash, or network failure)
- ✅ **Intelligent auto-compaction** during checkpoints
- ✅ **Zero manual intervention** required
**For Non-Git Projects:**
- 📝 Use `/start` for manual initialization
- 📝 Use `/end` for manual cleanup
- 📝 Full session management features available on-demand
```
#### 2.2 Session-mgmt-mcp CLAUDE.md Updates
Replace workflow section:
```markdown
## Recommended Session Workflow
### Git Repositories (Automatic)
1. **Start Claude Code** - Session auto-initializes
2. **Work normally** - Automatic quality tracking
3. **Run `/checkpoint`** - Manual checkpoints with auto-compaction
4. **Exit any way** - Session auto-cleanup on disconnect
### Non-Git Projects (Manual)
1. **Start with**: `/start` (if you want session management)
2. **Checkpoint**: `/checkpoint` as needed
3. **End with**: `/end` before quitting
```
#### 2.3 Crackerjack README.md Updates
Update integration section:
````markdown
## 🤝 Session-mgmt Integration (Enhanced)
**Automatic for Git Projects:**
- Session management starts automatically
- No manual `/start` or `/end` needed
- Checkpoints auto-compact when necessary
- Works seamlessly with `python -m crackerjack`
**Example Workflow:**
```bash
# Just start working - session auto-initializes!
python -m crackerjack run --ai-fix --run-tests
# Checkpoint periodically (auto-compacts if needed)
/checkpoint
# Quit any way - session auto-saves
/quit # or Cmd+Q, or network disconnect
````
````
#### 2.4 Crackerjack CLAUDE.md Updates
Add to workflow section:
```markdown
## Session Management Integration
**Automatic Lifecycle (Git repos only):**
- Session starts automatically when Claude Code connects
- Session ends automatically on disconnect/quit
- No manual commands needed for git repositories
**Manual Commands (still available):**
- `/start` - Manual init for non-git projects
- `/checkpoint` - Create checkpoint (auto-compacts)
- `/end` - Manual cleanup for non-git projects
**Best Practice:**
For Crackerjack projects (always git repos), you can focus on development
without worrying about session management - it's fully automatic!
````
### Phase 3: Configuration Cleanup
#### 3.1 Remove Old Hooks from settings.json
Remove from `/Users/les/.claude/settings.json`:
```json
// REMOVE THESE:
"UserPromptSubmit": [
{
"matcher": "/(?:exit|quit)\\b",
"hooks": [
{
"type": "command",
"command": "~/.claude/scripts/session-manager.sh end"
}
]
}
]
```
Keep SessionStart hook for MCP server startup only.
### Phase 4: Testing Plan
1. **Git Repository Tests:**
- Start session in crackerjack → Verify auto-init
- Run checkpoint → Verify auto-compact when needed
- Quit various ways → Verify auto-cleanup
1. **Non-Git Directory Tests:**
- Start session in /tmp → Verify NO auto-init
- Manual `/start` → Verify works
- Manual `/end` → Verify works
1. **Failure Recovery Tests:**
- Force quit Claude Code → Verify cleanup runs
- Network disconnect → Verify cleanup runs
- Server crash → Verify graceful degradation
## Benefits
### For Git Repositories (90% of use cases)
- **Zero manual intervention** - Fully automatic lifecycle
- **Crash resilient** - Cleanup runs even on force quit/crash
- **Network failure safe** - Disconnection triggers cleanup
- **Intelligent compaction** - Automatic during checkpoints
### For Non-Git Projects
- **Manual control preserved** - Use `/start` and `/end` as needed
- **Optional session management** - Only when explicitly desired
- **Full feature access** - All session-buddy features available
## Success Metrics
- ✅ Zero manual commands for git repositories
- ✅ Automatic compaction during checkpoints
- ✅ Cleanup runs on ALL disconnection types
- ✅ Non-git directories unaffected
- ✅ Manual commands still functional
## Migration Path
1. **Update server.py** with lifespan handlers
1. **Test with git repositories** to verify auto-detection
1. **Test with non-git directories** to verify no interference
1. **Update documentation** to reflect new behavior
1. **Clean up old hooks** from settings.json
## Timeline
- Phase 1: Core server changes (1-2 hours)
- Phase 2: Documentation updates (30 mins)
- Phase 3: Configuration cleanup (15 mins)
- Phase 4: Testing (1 hour)
Total: ~3-4 hours implementation time
## Implementation Status
- [ ] Phase 1: Core server changes
- [ ] Phase 2: Documentation updates
- [ ] Phase 3: Configuration cleanup
- [ ] Phase 4: Testing and validation
______________________________________________________________________
*Document created: 2025-09-07*
*Status: Implementation in progress*
