> ## Documentation Index
> Fetch the complete documentation index at: https://nikcli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Management

> Complete reference for session management and workspace state commands

# Session Management

NikCLI provides comprehensive session management capabilities for maintaining workspace state, managing multiple work contexts, and preserving development progress across sessions.

## Core Session Commands

### `/new [name]`

Create a new work session with optional name and configuration.

**Syntax:**

```bash theme={null}
/new [session-name] [options]
```

**Parameters:**

* `session-name` - Optional name for the session

**Options:**

* `--template <template>` - Use session template
* `--copy-from <session>` - Copy from existing session
* `--workspace <path>` - Set workspace directory
* `--description <text>` - Session description

**Examples:**

```bash theme={null}
# Create new session with auto-generated name
/new

# Create named session
/new "feature-authentication"

# Create session from template
/new "api-development" --template backend

# Copy existing session
/new "feature-v2" --copy-from "feature-authentication"

# Create session with workspace
/new "mobile-app" --workspace /path/to/mobile-project
```

**Session Creation Process:**

1. Initialize new session context
2. Set up workspace environment
3. Configure AI model preferences
4. Initialize memory and context
5. Create session metadata

### `/sessions`

List all available sessions with status and metadata.

**Syntax:**

```bash theme={null}
/sessions [options]
```

**Options:**

* `--active` - Show only active sessions
* `--recent` - Show recently used sessions
* `--detailed` - Show detailed information
* `--json` - Output in JSON format

**Examples:**

```bash theme={null}
# List all sessions
/sessions

# Show only active sessions
/sessions --active

# Show recent sessions
/sessions --recent

# Detailed session information
/sessions --detailed
```

**Session List Output:**

```
📋 Available Sessions:

┌─────────────────────┬─────────────┬─────────────┬─────────────┬─────────────┐
│ Name                │ Status      │ Created     │ Last Used   │ Size        │
├─────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
│ feature-auth        │ ● Active    │ 2d ago      │ 5m ago      │ 2.3MB       │
│ api-refactor        │ ○ Inactive  │ 1w ago      │ 2d ago      │ 1.8MB       │
│ mobile-app          │ ○ Inactive  │ 3d ago      │ 1d ago      │ 4.1MB       │
│ bug-fix-123         │ ○ Inactive  │ 5d ago      │ 3d ago      │ 0.9MB       │
└─────────────────────┴─────────────┴─────────────┴─────────────┴─────────────┘

Total: 4 sessions (1 active, 3 inactive)
```

### `/resume [name]`

Resume a previously saved work session.

**Syntax:**

```bash theme={null}
/resume <session-name> [options]
```

**Parameters:**

* `session-name` - Name of session to resume

**Options:**

* `--merge` - Merge with current session
* `--force` - Force resume even if conflicts exist
* `--readonly` - Resume in read-only mode

**Examples:**

```bash theme={null}
# Resume specific session
/resume "feature-authentication"

# Resume with merge
/resume "api-refactor" --merge

# Force resume with conflicts
/resume "mobile-app" --force

# Resume in read-only mode
/resume "bug-fix-123" --readonly
```

**Resume Process:**

1. Load session metadata
2. Restore workspace context
3. Reload conversation history
4. Restore AI model settings
5. Reinitialize tools and agents

### `/save-session [name]`

Save current session state with optional name.

**Syntax:**

```bash theme={null}
/save-session [session-name] [options]
```

**Parameters:**

* `session-name` - Optional name for saved session

**Options:**

* `--description <text>` - Session description
* `--tags <tags>` - Session tags (comma-separated)
* `--compress` - Compress session data
* `--include-files` - Include modified files

**Examples:**

```bash theme={null}
# Save current session
/save-session

# Save with specific name
/save-session "checkpoint-before-refactor"

# Save with description and tags
/save-session "api-complete" --description "API implementation finished" --tags "backend,api,complete"

# Save with file inclusion
/save-session "full-backup" --include-files --compress
```

### `/delete-session [name]`

Delete a saved session permanently.

**Syntax:**

```bash theme={null}
/delete-session <session-name> [options]
```

**Parameters:**

* `session-name` - Name of session to delete

**Options:**

* `--force` - Skip confirmation prompt
* `--backup` - Create backup before deletion

**Examples:**

```bash theme={null}
# Delete session with confirmation
/delete-session "old-experiment"

# Force delete without confirmation
/delete-session "temp-session" --force

# Delete with backup
/delete-session "outdated-feature" --backup
```

### `/export-session [name]`

Export session data to external format.

**Syntax:**

```bash theme={null}
/export-session [session-name] [options]
```

**Parameters:**

* `session-name` - Session to export (default: current)

**Options:**

* `--format <format>` - Export format (json, zip, tar)
* `--output <file>` - Output file path
* `--include-files` - Include workspace files
* `--compress` - Compress export

**Examples:**

```bash theme={null}
# Export current session
/export-session

# Export specific session to JSON
/export-session "feature-auth" --format json --output auth-session.json

# Export with files included
/export-session "complete-project" --include-files --compress --output project-backup.zip
```

## Advanced Session Management

### `/work-sessions [action]`

Manage work sessions with advanced features.

**Syntax:**

```bash theme={null}
/work-sessions <action> [options]
```

**Available Actions:**

* `list` - List work sessions
* `create` - Create new work session
* `switch` - Switch between sessions
* `merge` - Merge sessions
* `archive` - Archive old sessions

**Examples:**

```bash theme={null}
# List work sessions
/work-sessions list

# Create work session
/work-sessions create "sprint-planning"

# Switch to different session
/work-sessions switch "bug-fixes"

# Merge sessions
/work-sessions merge "feature-a" "feature-b" --output "combined-feature"

# Archive old sessions
/work-sessions archive --older-than 30d
```

### Session Templates

**Create Session Templates:**

```bash theme={null}
# Create template from current session
/save-session-template "backend-dev" --description "Backend development template"

# Use template for new session
/new "new-backend-project" --template "backend-dev"

# List available templates
/session-templates list

# Delete template
/session-templates delete "old-template"
```

**Predefined Templates:**

**Frontend Development:**

```bash theme={null}
/new "frontend-project" --template frontend
# Includes: React/Vue setup, styling tools, testing framework
```

**Backend Development:**

```bash theme={null}
/new "backend-project" --template backend
# Includes: API development tools, database setup, testing
```

**Full-Stack Development:**

```bash theme={null}
/new "fullstack-project" --template fullstack
# Includes: Frontend + backend tools, deployment setup
```

**Data Science:**

```bash theme={null}
/new "data-project" --template data-science
# Includes: Python environment, Jupyter, data analysis tools
```

## Session State Management

### Context Preservation

Sessions automatically preserve:

* Conversation history
* AI model preferences
* Tool configurations
* Agent settings
* Workspace context
* Memory and recall data
* File modification history
* Environment variables

### Session Metadata

**View Session Information:**

```bash theme={null}
# Show current session info
/session-info

# Show detailed session metadata
/session-info --detailed

# Show session statistics
/session-stats

# Show session timeline
/session-timeline
```

**Session Metadata Includes:**

* Creation and modification dates
* Total conversation length
* AI model usage statistics
* Tool usage patterns
* File modification count
* Memory usage
* Performance metrics

### Session Synchronization

**Sync Sessions Across Devices:**

```bash theme={null}
# Enable session sync
/session-sync enable --provider cloud

# Sync current session
/session-sync push

# Pull remote session
/session-sync pull "feature-auth"

# List remote sessions
/session-sync list-remote

# Configure sync settings
/session-sync config --auto-sync --interval 5m
```

## Memory and Context Management

### Session Memory

**Memory Operations:**

```bash theme={null}
# Show session memory
/memory session

# Clear session memory
/memory clear --session

# Export session memory
/memory export --session --output session-memory.json

# Import session memory
/memory import session-memory.json --merge
```

### Context Management

**Workspace Context:**

```bash theme={null}
# Show current context
/context

# Set workspace context
/context workspace /path/to/project

# Add context information
/context add "Working on authentication system"

# Clear context
/context clear

# Context history
/context history
```

## Session Collaboration

### Shared Sessions

**Share Sessions with Team:**

```bash theme={null}
# Share session
/session-share "feature-auth" --with "team@company.com"

# Accept shared session
/session-accept "shared-session-id"

# List shared sessions
/sessions --shared

# Collaborate on session
/session-collaborate "shared-feature" --mode real-time
```

### Session Permissions

**Manage Session Access:**

```bash theme={null}
# Set session permissions
/session-permissions "feature-auth" --read-write "alice@company.com" --read-only "bob@company.com"

# View session permissions
/session-permissions "feature-auth" --list

# Revoke access
/session-permissions "feature-auth" --revoke "alice@company.com"
```

## Session Analytics

### Usage Statistics

**Session Analytics:**

```bash theme={null}
# Show session statistics
/session-analytics

# Detailed usage report
/session-analytics --detailed --period 30d

# Export analytics
/session-analytics --export analytics-report.json

# Compare sessions
/session-analytics --compare "session-a" "session-b"
```

**Analytics Include:**

* Time spent in sessions
* AI model usage patterns
* Tool usage frequency
* Productivity metrics
* Error rates
* Performance trends

### Session Insights

**Get Session Insights:**

```bash theme={null}
# AI-powered session insights
/session-insights

# Productivity analysis
/session-insights --productivity

# Recommendations
/session-insights --recommendations

# Pattern analysis
/session-insights --patterns
```

## Session Backup and Recovery

### Automatic Backups

**Configure Automatic Backups:**

```bash theme={null}
# Enable auto-backup
/session-backup enable --interval 30m

# Configure backup retention
/session-backup config --keep 10 --compress

# List backups
/session-backup list

# Restore from backup
/session-backup restore "backup-20240115-143000"
```

### Manual Backups

**Create Manual Backups:**

```bash theme={null}
# Create backup
/session-backup create "before-major-changes"

# Create full backup with files
/session-backup create "complete-backup" --include-files

# Backup to external location
/session-backup create "external-backup" --output /external/drive/
```

### Recovery Operations

**Session Recovery:**

```bash theme={null}
# Recover corrupted session
/session-recover "corrupted-session"

# Recover from crash
/session-recover --from-crash

# Partial recovery
/session-recover "session-name" --partial --keep-history

# Emergency recovery
/session-recover --emergency --all-sessions
```

## Integration Examples

### Development Workflow

```bash theme={null}
# 1. Start new feature development
/new "feature-user-profiles" --template frontend

# 2. Work on feature with context
/context add "Implementing user profile management with React and TypeScript"

# 3. Save progress periodically
/save-session "profiles-initial-setup"

# 4. Continue development
# ... development work ...

# 5. Save major milestone
/save-session "profiles-ui-complete" --description "UI components finished"

# 6. Switch to different task
/new "bug-fix-login" --template backend

# 7. Resume original work
/resume "feature-user-profiles"
```

### Team Collaboration

```bash theme={null}
# 1. Create shared session
/new "team-sprint-planning" --template collaboration

# 2. Share with team
/session-share "team-sprint-planning" --with "team@company.com"

# 3. Collaborate in real-time
/session-collaborate "team-sprint-planning" --mode real-time

# 4. Save team decisions
/save-session "sprint-decisions" --description "Sprint planning outcomes"

# 5. Export for documentation
/export-session "sprint-decisions" --format json --output sprint-plan.json
```

### Project Handoff

```bash theme={null}
# 1. Prepare handoff session
/save-session "project-handoff" --include-files --compress

# 2. Add handoff documentation
/context add "Project handoff to new team member - includes all implementation details"

# 3. Export complete package
/export-session "project-handoff" --format zip --output project-complete.zip

# 4. Share with new team member
/session-share "project-handoff" --with "newdev@company.com" --permissions read-write
```

## Troubleshooting

### Common Session Issues

**Session Won't Load:**

```bash theme={null}
# Check session integrity
/session-check "session-name"

# Repair corrupted session
/session-repair "session-name"

# Recover from backup
/session-backup restore "latest-backup"
```

**Memory Issues:**

```bash theme={null}
# Check session memory usage
/session-stats --memory

# Clear session cache
/session-cache clear

# Optimize session
/session-optimize "session-name"
```

**Sync Problems:**

```bash theme={null}
# Check sync status
/session-sync status

# Force sync
/session-sync push --force

# Resolve sync conflicts
/session-sync resolve-conflicts
```

### Debug Commands

```bash theme={null}
# Session system diagnostics
/diagnostic sessions

# Debug specific session
/debug session "session-name"

# Check session database
/session-db check

# Repair session database
/session-db repair
```

## Best Practices

### Session Organization

* Use descriptive session names
* Add meaningful descriptions and tags
* Regular cleanup of old sessions
* Use templates for consistent setup
* Archive completed projects

### Performance

* Regular session optimization
* Monitor memory usage
* Clean up large sessions
* Use compression for storage
* Regular backup maintenance

### Collaboration

* Clear session sharing permissions
* Document shared session purpose
* Regular sync with team
* Resolve conflicts promptly
* Maintain session hygiene

### Security

* Protect sensitive sessions
* Regular backup verification
* Secure session sharing
* Monitor access logs
* Use appropriate permissions