16 KiB
16 KiB
Mandatory Sessions - The New Claude OS Model
Every conversation is a session. Period.
🎯 The Philosophy
Old Model: Sessions are optional, you choose when to track work New Model: You're ALWAYS in a session. The only choice is WHAT session.
Why?
- Zero context loss
- Complete work history
- Automatic tracking
- Better insights over time
🚀 How It Works
Every Conversation Start
═══════════════════════════════════════════════════════════════
🚀 CLAUDE OS - SESSION MANAGER
═══════════════════════════════════════════════════════════════
Project: Pistn
Last Session: Dashboard Redesign (2 days ago, 2h 15m)
Progress: 45% complete (PHASE2-TASK3 in progress)
Options:
1. Resume "Dashboard Redesign" [loads full context]
2. Start new session [what are you working on?]
3. Quick question [auto-session, no setup needed]
Choice: _
═══════════════════════════════════════════════════════════════
You MUST pick one. No "just chatting" option.
📋 Session Types
1. Feature Implementation
Type: feature
Duration: Tracked
Kanban: Linked to spec + tasks
Auto-saves: High-value patterns and decisions
Example: "Dashboard Redesign"
Context: Spec tasks, memories, coding standards
Tracking: Task completion, time per task, blockers
2. Bug Fix
Type: bug
Duration: Tracked
Priority: Detected from description (high/medium/low)
Auto-saves: Root cause, solution, prevention
Example: "API 500 Errors"
Context: Error logs, similar past issues, integration patterns
Tracking: Time to fix, solution approach, related issues
3. Exploration / Learning
Type: exploration
Duration: Tracked
Auto-saves: Key learnings, architecture insights
Example: "Understand authentication flow"
Context: Relevant code, architecture docs
Tracking: Files explored, patterns discovered
4. Refactoring / Maintenance
Type: maintenance
Duration: Tracked
Auto-saves: Refactoring patterns, improvements made
Example: "Clean up controller concerns"
Context: Coding standards, similar refactors
Tracking: Files changed, complexity reduced
5. Code Review
Type: review
Duration: Tracked
Auto-saves: Review comments, patterns identified
Example: "Review PR #234"
Context: Project standards, common issues
Tracking: Issues found, suggestions made
6. Quick Question (Auto-Managed)
Type: question
Duration: Auto-tracked (ends after 5 min inactivity)
Auto-saves: Only if valuable insight
Example: "How does Draper work?"
Context: Minimal (just project standards)
Tracking: Questions asked, answers given
🔄 Session Lifecycle
Phase 1: Session Selection (Every Conversation Start)
Option 1: Resume Existing Session
You: "1" (resume)
Claude:
═══════════════════════════════════════════════════════════════
✓ RESUMING: Dashboard Redesign
═══════════════════════════════════════════════════════════════
[Loads all context automatically:]
✓ Spec: Group Account Rendering (45% complete)
✓ Current Task: PHASE2-TASK3 (Implement concern methods)
✓ 5 relevant memories loaded
✓ Coding standards loaded
✓ Git: 3 files modified on feature/appointment-redesign
Duration this session: 0h 0m
Total duration: 2h 15m
Ready! Let's continue implementing PHASE2-TASK3.
═══════════════════════════════════════════════════════════════
Option 2: Start New Session
You: "2" (new session)
Claude: "What are you working on?
(I'll detect the type and load relevant context)"
You: "Fix the Tekmetric API 500 errors"
Claude:
═══════════════════════════════════════════════════════════════
✓ NEW BUG SESSION STARTED
═══════════════════════════════════════════════════════════════
Session: "Fix Tekmetric API 500 errors"
Type: Bug Fix (detected)
Priority: High (500 errors are critical)
[Auto-loaded context:]
✓ Searched memories: "Tekmetric API integration errors"
✓ Found 3 similar issues from past sessions
✓ Loaded integration patterns
✓ Git status checked
Previous session "Dashboard Redesign" paused.
Let's debug this! What's the error message?
═══════════════════════════════════════════════════════════════
Option 3: Quick Question
You: "3" (quick question)
Claude: "What's your question?"
You: "How do I use Draper decorators?"
Claude:
═══════════════════════════════════════════════════════════════
💬 QUICK QUESTION SESSION
═══════════════════════════════════════════════════════════════
[Gives answer]
This auto-session will end after 5 minutes of inactivity.
Need more help, or ready to resume Dashboard Redesign?
═══════════════════════════════════════════════════════════════
Phase 2: Active Session (During Work)
Live Tracking:
[Active Session: Dashboard Redesign]
Duration: 1h 23m
Files changed: 3
Quick saves: 2
Last activity: 2 minutes ago
/claude-os-session status → Shows current session details
/claude-os-session save "insight" → Quick save to memories
/claude-os-session switch "bug fix" → Switch to different session
Smart Prompts:
[After 2 hours of work]
Claude: "You've been working for 2h. You usually take a break around now.
Want to commit your work and pause the session?"
[When pattern detected]
Claude: "This looks like the service object pattern. Should I save
this as a reusable pattern for future reference?"
[When blocker encountered]
Claude: "Want me to track this as a blocker and search for solutions
from past sessions?"
Phase 3: Session End (Explicit or Auto)
Explicit End:
You: "/claude-os-session end"
Claude:
═══════════════════════════════════════════════════════════════
📊 SESSION SUMMARY: Dashboard Redesign
═══════════════════════════════════════════════════════════════
Duration: 1h 23m
Files changed: 3 files
Quick saves: 2
Commits: 1
Work completed:
✓ Implemented concern methods for PHASE2-TASK3
✓ Fixed N+1 query issue
✓ Added helper methods for PHASE2-TASK4
Progress: 45% → 53% (8% increase!)
Tasks completed: 2 tasks (PHASE2-TASK3, PHASE2-TASK4)
═══════════════════════════════════════════════════════════════
💾 SMART SAVES DETECTED
═══════════════════════════════════════════════════════════════
I found 2 items worth saving:
1. 💎 HIGH VALUE - Concern Method Pattern
"Extracted group account logic to concern with proper
service object integration. Reusable pattern."
Save to project_profile? [Y/n]
2. 📊 MEDIUM VALUE - N+1 Query Fix
"Fixed N+1 in appointments loading by eager loading
with includes(:group_account)"
Save to project_memories? [Y/n]
═══════════════════════════════════════════════════════════════
Auto-End (Inactivity):
[After 15 minutes of inactivity]
Claude: "Session 'Dashboard Redesign' has been inactive for 15 minutes.
Options:
1. Keep session active
2. Pause session (can resume later)
3. End session (save and summarize)
Choice: _"
🎛️ Session Switching
Mid-Session Switch
[Active: Dashboard Redesign, 45m elapsed]
You: "Actually I need to fix a bug first"
Claude: "Want to switch sessions?
1. Pause 'Dashboard Redesign' and start 'Bug Fix' session
2. Continue 'Dashboard Redesign' (handle bug within this session)
Choice: _"
You: "1"
Claude:
═══════════════════════════════════════════════════════════════
✓ SESSION SWITCHED
═══════════════════════════════════════════════════════════════
Paused: Dashboard Redesign (45m, 45% complete)
Started: Bug Fix Session
What's the bug?
═══════════════════════════════════════════════════════════════
Multiple Sessions Same Day
═══════════════════════════════════════════════════════════════
📊 TODAY'S SESSIONS
═══════════════════════════════════════════════════════════════
09:00 - 11:15 Dashboard Redesign 2h 15m ✓ Ended
11:15 - 11:45 API Bug Fix 30m ✓ Ended
12:00 - 13:30 Dashboard Redesign 1h 30m ⏸ Paused
14:00 - 15:30 Code Review 1h 30m 🔄 Active
Total: 5h 45m across 4 sessions
Most time: Dashboard Redesign (3h 45m, 2 sessions)
═══════════════════════════════════════════════════════════════
📊 Session Statistics
Daily Summary
═══════════════════════════════════════════════════════════════
📊 END OF DAY SUMMARY - November 4, 2025
═══════════════════════════════════════════════════════════════
Total sessions: 4
Total time: 5h 45m
Average session: 1h 26m
Session breakdown:
• Feature work: 3h 45m (65%)
• Bug fixes: 30m (9%)
• Code review: 1h 30m (26%)
Productivity:
• Tasks completed: 4 tasks
• Memories saved: 6 insights
• Patterns discovered: 2 patterns
• Blockers resolved: 1
Most productive session: Dashboard Redesign (2h 15m, 3 tasks)
Longest session: Dashboard Redesign (2h 15m)
Great day! 🚀
═══════════════════════════════════════════════════════════════
Weekly Summary
Week of Oct 28 - Nov 3, 2025
Total sessions: 23
Total time: 32h 15m
Average daily: 4h 36m
Session types:
• Feature: 18 sessions (24h, 74%)
• Bug fix: 3 sessions (2h, 6%)
• Exploration: 2 sessions (6h 15m, 20%)
Top projects:
1. Pistn: 28h (Dashboard Redesign: 18h)
2. Claude OS: 4h 15m (Kanban feature: 4h 15m)
Memories saved: 23 insights
Patterns discovered: 5 patterns
Most productive day: Oct 31 (6h 30m, 8 tasks)
Project Summary
Dashboard Redesign - Complete History
Total sessions: 5
Total time: 12h 45m
Status: In Progress (53% complete)
Session history:
• Oct 29: 2h 15m (PHASE1: Sidebar + Cards)
• Oct 31: 3h 00m (PHASE1: Toggles + Forms)
• Nov 1: 2h 30m (PHASE2: Concerns started)
• Nov 3: 3h 00m (PHASE2: Helper methods)
• Nov 4: 2h 00m (PHASE2: Testing)
Progress:
• Tasks completed: 27 of 52 (53%)
• Phases completed: 1 of 3
• Estimated remaining: 10h 30m
Velocity:
• Average: 2.4 tasks per session
• Average: 0.47h per task
• Projected completion: Nov 6
🎯 Commands Reference
Session Management
# At conversation start (automatic prompt)
[Choose 1/2/3]
# During session
/claude-os-session status # Current session details
/claude-os-session save "note" # Quick save
/claude-os-session switch "task" # Switch to different session
/claude-os-session pause # Pause current session
/claude-os-session end # End with summary
# View history
/claude-os-session today # Today's sessions
/claude-os-session week # This week
/claude-os-session history [task] # History for specific task
🔧 Configuration
Session Preferences (.claude-os/config.json)
{
"session_management": {
"mandatory": true,
"auto_prompt_on_start": true,
"auto_save_frequency": "15_minutes",
"inactivity_timeout": 15,
"auto_switch_detection": true,
"daily_summary": true,
"break_reminders": {
"enabled": true,
"interval_minutes": 120
}
}
}
💡 Best Practices
1. Name Sessions Descriptively
✅ Good: "Fix Tekmetric sync 500 errors"
✅ Good: "Implement group account rendering"
❌ Bad: "Work on stuff"
❌ Bad: "Bug fix"
2. Use Session Types Correctly
- Feature: Building new functionality
- Bug: Fixing specific issues
- Exploration: Learning/understanding code
- Maintenance: Refactoring/cleanup
- Review: Code review
- Question: Quick questions (auto-managed)
3. End Sessions Cleanly
Don't just close terminal!
Use: /claude-os-session end
Benefits:
• Captures work summary
• Suggests valuable saves
• Updates statistics
• Prepares next session
4. Switch Sessions When Context Changes
Don't mix unrelated work in one session!
Working on Dashboard → API bug appears → Switch sessions!
Keeps tracking clean and relevant.
🚀 Benefits Recap
For You:
- Never lose work - Everything tracked
- Perfect continuity - Resume exactly where you left off
- Understand productivity - Real metrics
- Learn from history - See what works
For Me (Claude):
- Complete context - Know what we're working on
- Smart suggestions - Based on session type
- Proactive saves - Capture valuable insights
- Better guidance - Relevant to current task
For The Team:
- Shared knowledge - All insights saved
- Velocity tracking - Understand capacity
- Pattern recognition - Learn what works
- Onboarding - New members see work history
🎯 The Goal
Every moment of coding is tracked, categorized, and learned from.
No more:
- ❌ "What was I doing?"
- ❌ "How long did that take?"
- ❌ "Where did we leave off?"
- ❌ "Did we solve this before?"
Only:
- ✅ Instant context on session start
- ✅ Complete work history
- ✅ Automatic learning
- ✅ Zero context loss
This is the complete AI development system working at full power. 🚀
Next Steps:
- Update CLAUDE.md template with mandatory session flow
- Update
/claude-os-sessioncommand to reflect new model - Start using it TODAY in current projects
- Track results and iterate
Let's make sessions mandatory! 💪