Session Management

Manage coding sessions with git-native workflows, intelligent context preservation, and seamless agent onboarding.

Core Concept

Sessions = Branches + Context

Session management enhances git workflows by:

• Mapping branches to work sessions with objectives

• Creating enhanced commits with decision metadata

• Tracking progress, blockers, and architectural decisions

• Generating comprehensive handoffs between sessions

• Providing instant context loading for AI agents

Quick Start

Initialize in Project

python scripts/init_session.py

Creates .sessions/ directory with:

• config.yaml

• Session configuration (optional)

• checkpoints/

• Checkpoint storage

• state.json

• Current session state

Core Workflows

Important: All slash commands use the AskUserQuestion tool to gather inputs interactively. The Python scripts accept CLI arguments, so commands collect user choices via multiple-choice prompts, then execute scripts with those arguments.

Session Start (/session-start )

Rapid re-immersion for both human and AI

/session-start

What happens:

• Project status report generated - Health, git status, recent work, open items

• Interactive prompts via AskUserQuestion - User selects what to work on, which branch, and session objectives through multiple-choice questions

• Branch selection - Choose from active branches or create new (hotfix/feature/bugfix)

• Context loaded - Architecture, decisions, patterns from last session

• Session ready - Both human and AI fully contextualized

Use when:

• Starting work on a project

• Returning after days away

• Context switching between projects

Create Checkpoint (/checkpoint )

Quick save points during work

/checkpoint

What happens:

• Automatic capture - Git diff, metrics, TDD cycles analyzed

• Interactive prompts via AskUserQuestion - User chooses whether to add notes, create git commit, or both

• Checkpoint saved - Comprehensive snapshot generated

• Git commit - Optionally create commit with auto-generated or custom message

Use when:

• At logical milestones

• Completing sub-tasks

• Before switching contexts

Examples:

Simple checkpoint

python scripts/session.py checkpoint --label "oauth-complete"

Checkpoint with notes and git commit

python scripts/session.py checkpoint --label "feature-complete" --notes "OAuth flow tested" --commit

With custom commit message

python scripts/session.py checkpoint --label "bugfix" --commit --message "fix: resolve auth token expiry"

End Session (/session-end )

Comprehensive knowledge capture and handoff

/session-end

What happens:

• Final checkpoint created - Captures current state

• Interactive prompts via AskUserQuestion - User provides session accomplishments, decisions made, and context for next session

• Handoff generated - Full session summary with metrics and next steps

• Git push - User chooses whether to push commits to remote

• State saved - Ready for next session

Use when:

• Finishing work session

• End of day

• Before extended break

Session Lifecycle

START → Load full project context with status report WORK → Track changes automatically in background CHECKPOINT → Save progress with automatic git analysis END → Generate handoff with comprehensive session summary

Key Features

1. Objectives Management

Track what you're trying to accomplish:

Add objective

python scripts/session.py objectives add "Implement OAuth2 integration"

Mark complete

python scripts/session.py objectives complete obj-1

List all

python scripts/session.py objectives list

2. Blocker Tracking

Record impediments:

Add blocker

python scripts/session.py blockers add "Waiting on API keys"

Resolve

python scripts/session.py blockers resolve blk-1

3. Decision Logging

Capture architectural decisions with context:

Record decision

python scripts/session.py decisions add "Using repository pattern for data access"
--rationale "Separates domain logic from persistence"
--alternatives "Active Record: Too coupled to database"

4. Context Queries

Check current state:

Full status

python scripts/session.py status

Just objectives

python scripts/session.py status --objectives

History

python scripts/session.py history --count 10

Agent Onboarding

When AI agents (like Claude Code) start, session management provides instant context:

Automatically loads on agent start:

- Project architecture pattern

- Code conventions

- Recent decisions

- Current objectives

- Active blockers

- Git history analysis

- File changes summary

Agent receives structured brief including:

• What we're building (objectives)

• How to build it (architecture, patterns, conventions)

• What's done (progress)

• What's next (next actions)

• What to watch for (blockers, TODOs)

Storage Structure

project/ ├── .session/ # Git-tracked, shared across team │ ├── config.yaml # Configuration │ ├── architecture.md # Architecture documentation │ ├── conventions.md # Code conventions │ └── decision-log.md # All decisions (auto-generated) │ └── .git/ └── sessions/ # Local, developer-specific └── <branch>/ ├── objectives.md ├── blockers.md └── context.json

Design principle: Shared context (architecture, conventions) is git-tracked. Personal workflow data (objectives, notes) stays local.

Configuration

Edit .session/config.yaml :

session: auto_track: true # Track file changes automatically handoff_on_end: true # Generate handoff when ending

context: architecture: hexagonal # Your architecture pattern patterns: # Patterns to enforce - repository-pattern - dependency-injection

tracking: watch_patterns: # Files to monitor - "src//*.py" - "tests//*.py"

Workflows

Daily Development

Morning: Resume work

python scripts/session.py resume

During work: Checkpoint at milestones

python scripts/session.py checkpoint --label "api-complete"

Evening: End with handoff

python scripts/session.py end

Context Switching

Urgent bug comes in

python scripts/session.py switch hotfix/critical-bug

Fix bug

python scripts/session.py checkpoint --message "Fix security issue" python scripts/session.py end --merge-to main

Back to feature

python scripts/session.py resume feature/main-work

Team Handoffs

Generate comprehensive handoff

python scripts/session.py end --handoff --summary

Next developer loads context

python scripts/session.py resume <branch>

Enhanced Commits

Session checkpoints create git commits with rich metadata:

feat(auth): Implement OAuth2 provider

Completed Google OAuth flow with PKCE support.

Session-Objectives:

• OAuth provider interface
• [▶] Google OAuth (this commit)
• GitHub OAuth (next)

Decisions:

• Using PKCE flow for enhanced security Rationale: Protection against code interception

Impact:

• Added: src/auth/oauth_provider.py
• Tests: +12 unit tests
• Coverage: 79% → 84%

Session-Time: 2h 15m

Advanced Features

Session Analysis

Analyze session health

python scripts/session.py analyze

Calculate velocity

python scripts/session.py analyze --velocity

Pattern detection

python scripts/session.py analyze --patterns

Session History

Recent sessions with metrics

python scripts/session.py history --count 5 --metrics

Compare sessions

python scripts/session.py compare <session-id>

Reports

Weekly summary

python scripts/session.py report --weekly

Project summary

python scripts/session.py report --project --format markdown

Bundled Resources

Scripts

• init_session.py

• Initialize session management in project

• session.py

• Main CLI for all session operations

• analyze_git.py

• Git history analysis utilities

References

• commands.md

• Complete command reference

• handoff-template.md

• Template for session handoffs

• config-reference.md

• All configuration options

Assets

• config-template.yaml

• Default configuration

• architecture-template.md

• Architecture documentation template

• conventions-template.md

• Conventions template

Best Practices

For Solo Development:

• Start every session with objectives

• Checkpoint at logical milestones

• Record decisions when making them

• End sessions with handoffs (helps future you)

For Teams:

• Commit .session/ directory (shared context)

• Keep personal workflow local

• Link blockers to issue tracker

• Generate handoffs for transitions

For AI-Assisted Development:

• Session management provides instant agent context

• No need to re-explain project structure

• Architectural patterns automatically enforced

• Decisions preserved across sessions

Troubleshooting

Session not loading?

python scripts/session.py status --verbose python scripts/session.py start --resume

Need to reinitialize?

python scripts/init_session.py --force

View current configuration:

cat .session/config.yaml

CCMP Plugin Integration

Session management automatically integrates with other CCMP plugins:

With claude-context-manager 📚

Auto-loads relevant context on session start:

python scripts/session.py start feature/auth

→ Automatically loads src/auth/claude.md

→ Shows context health warnings

→ Includes patterns and gotchas in brief

Checkpoints trigger context health checks:

python scripts/session.py checkpoint --label "api-complete"

→ Detects src/api/ changed

→ Warns if context is stale

→ Offers: "Update context? [y/N]"

Handoffs include context health:

python scripts/session.py end --handoff

→ Includes context health score

→ Lists files needing updates

→ Recommends maintenance for next session

With tdd-workflow 🧪

TDD mode automatically enhances sessions:

python scripts/session.py start feature/auth --tdd

→ TDD workflow detects and activates

→ Automatic RED-GREEN-REFACTOR checkpoints

→ TDD metrics in session status

→ Test coverage tracking

Session analysis detects TDD:

python scripts/session.py analyze

→ Shows TDD cycles completed

→ Detects commits without tests

→ Reports discipline violations

Integration API

Uses .ccmp/state.json for plugin coordination. See lib/ccmp_integration.py for details.

Developers: Import the integration library:

from lib.ccmp_integration import CCMPIntegration

integration = CCMPIntegration() if integration.is_active("session-management"): session = integration.get_state("session-management")

Integration Notes

Session management is designed to work with:

• Git (required) - Source of truth for history

• Issue Trackers (optional) - Link blockers to tickets

• CI/CD (optional) - Include build status in briefings

• Coverage Tools (optional) - Track quality metrics

For integration guides, see references/integrations.md .

See Also

• Full command reference: See references/commands.md

• Configuration options: See references/config-reference.md

• Handoff format: See references/handoff-template.md

• Integration guides: See references/integrations.md