# Session Management Slash Command Shortcuts

## Overview

The session-buddy MCP server automatically creates Claude Code slash command shortcuts the first time `session-buddy:start` is executed. These shortcuts provide convenient aliases for session management operations.

## Auto-Created Shortcuts

When you run `session-buddy:start` for the first time, the following shortcuts are automatically created in `~/.claude/commands/`:

### `/start` → `session-buddy:start`

**File**: `~/.claude/commands/start.md`

- Initializes session management for the current project
- Sets up session tracking for git repositories
- Initializes conversation memory and context
- Prepares project for enhanced Claude Code workflows
- Installs UV dependencies and automation tools

### `/checkpoint [name]` → `session-buddy:checkpoint`

**File**: `~/.claude/commands/checkpoint.md`

- Creates a checkpoint of the current development session
- Summarizes progress made so far
- Documents pending tasks or context
- Prepares for seamless session resumption
- Accepts optional checkpoint name argument

### `/end` → `session-buddy:end`

**File**: `~/.claude/commands/end.md`

- Gracefully ends the current session
- Creates final checkpoint of all work completed
- Generates session summary and insights
- Cleans up temporary resources
- Prepares handoff documentation for next session

## How It Works

1. **First-Time Setup**: When `session-buddy:start` runs, it calls `_create_session_shortcuts()`
1. **Directory Creation**: Creates `~/.claude/commands/` if it doesn't exist
1. **Shortcut Detection**: Checks if shortcuts already exist to avoid overwriting
1. **File Creation**: Creates Markdown files with proper Claude Code slash command format
1. **User Feedback**: Reports which shortcuts were created or already existed

## Architecture

### Function: `_create_session_shortcuts()`

**Location**: `session_buddy/tools/session_tools.py`

**Returns**:

```python
{
    "created": bool,  # True if new shortcuts were created
    "existed": bool,  # True if shortcuts already existed
    "shortcuts": list[str],  # List of shortcut names
}
```

**Features**:

- Creates `~/.claude/commands/` directory automatically
- Checks for existing shortcuts to prevent overwriting
- Uses proper Claude Code slash command YAML frontmatter format
- Includes argument hints for commands that accept parameters
- Provides comprehensive descriptions for each command
- Handles errors gracefully with logging

### Integration Points

1. **Called from**: `_start_impl()` in session_tools.py
1. **Triggered by**: First `session-buddy:start` execution
1. **File format**: Markdown with YAML frontmatter (Claude Code standard)
1. **Location**: Global `~/.claude/commands/` (available in all projects)

## Claude Code Integration

The shortcuts use Claude Code's standard slash command format:

```markdown
---
description: Command description
argument-hint: [optional-args]
---

Command execution instructions using session-buddy MCP tools.
```

### Key Features:

- **Global Availability**: Shortcuts work in any project with session-buddy configured
- **Argument Support**: `/checkpoint` accepts optional checkpoint names
- **Descriptive**: Clear descriptions show in Claude Code slash command menu
- **Future-Proof**: Uses stable session-buddy MCP tool names

## User Experience

### Before Auto-Creation:

```bash
# User had to manually create shortcuts or use full MCP tool names
session-buddy:start
session-buddy:checkpoint
session-buddy:end
```

### After Auto-Creation:

```bash
# Convenient shortcuts available immediately after first start
/start
/checkpoint daily-standup
/end
```

## Benefits

1. **Convenience**: Short, memorable commands for frequent operations
1. **Consistency**: Standardized shortcuts across all projects
1. **Self-Maintaining**: Automatically created during initialization
1. **Non-Intrusive**: Only creates shortcuts if they don't already exist
1. **Discoverable**: Shows up in Claude Code's slash command menu
1. **Documented**: Each shortcut includes usage descriptions

## Technical Implementation

### Error Handling:

- Gracefully handles permission errors
- Logs shortcut creation attempts
- Continues initialization even if shortcut creation fails
- Returns status information for user feedback

### File Management:

- Uses `pathlib.Path` for cross-platform compatibility
- Creates parent directories as needed
- Checks existing files before writing
- Uses proper file encoding (UTF-8)

### Integration:

- Minimal impact on initialization performance
- No external dependencies beyond standard library
- Compatible with existing Claude Code configurations
- Works with all operating systems

This feature significantly improves the developer experience by providing intuitive shortcuts for session management while maintaining the full power of the underlying MCP tools.
