Skip to content

README.md

Latest commit

 

History

History
179 lines (137 loc) · 4.74 KB

README.md

File metadata and controls

179 lines (137 loc) · 4.74 KB

Claude Session Management Scripts

This directory contains scripts for managing persistent context logging for Claude sessions.

Overview

The Claude Session Management System provides:

  • Persistent session tracking with UUID-based identification
  • JSON-based logging format for structured data
  • Automatic session recovery for interrupted work
  • Cleanup mechanisms for old session logs
  • Integration with Claude's workflow

Scripts

1. log-session.sh

Main session logging script that handles creating, updating, and retrieving sessions.

Usage:

# Create a new session
./log-session.sh create [project_path] [user_query]

# Update session fields
./log-session.sh update <session_id> <field> <value>

# Get session data
./log-session.sh get <session_id>

# List sessions
./log-session.sh list [status]

Update fields:

  • todo_add - Add item to todo list
  • file_modified - Add modified file
  • tech_stack - Add tech stack item
  • last_operation - Set last operation
  • status - Set session status (in_progress/completed/interrupted)
  • next_step - Add next step
  • operation - Add operation (JSON format)

2. recover-session.sh

Session recovery tool for resuming interrupted work.

Usage:

# Auto-detect session for current project
./recover-session.sh auto

# Show last incomplete session
./recover-session.sh last [project_path]

# Show specific session
./recover-session.sh show <session_id>

# Save recovery context
./recover-session.sh save [session_id] [output_file]

# Show recent sessions
./recover-session.sh recent [limit]

3. cleanup-sessions.sh

Manages old session logs with configurable retention period.

Usage:

# Delete sessions older than N days
./cleanup-sessions.sh clean [days]

# Preview what would be deleted
./cleanup-sessions.sh dry-run [days]

# Show session statistics
./cleanup-sessions.sh stats

# Archive old sessions
./cleanup-sessions.sh archive [days]

# Interactive cleanup
./cleanup-sessions.sh auto

4. claude-session-example.sh

Example script demonstrating how to use the session management system.

Session File Format

Sessions are stored as JSON files in ~/.claude/sessions/session-{uuid}.json:

{
  "session_id": "uuid",
  "created_at": "ISO-8601 timestamp",
  "updated_at": "ISO-8601 timestamp",
  "project_path": "/absolute/path/to/project",
  "user_query": "Original user request",
  "context": {
    "todo_list": ["task1", "task2"],
    "files_modified": ["file1.js", "file2.py"],
    "tech_stack": ["Node.js", "Python"],
    "last_operation": "Description of last action",
    "working_directory": "/current/directory"
  },
  "status": "in_progress|completed|interrupted",
  "next_steps": ["step1", "step2"],
  "operations": [
    {
      "type": "operation_type",
      "timestamp": "ISO-8601",
      "description": "What was done",
      "details": {}
    }
  ]
}

Integration

Shell Aliases

Add to your ~/.bashrc or ~/.zshrc:

# Claude session management
alias claude-resume='~/code/claude-config-template/scripts/recover-session.sh auto'
alias claude-sessions='~/code/claude-config-template/scripts/recover-session.sh recent'
alias claude-cleanup='~/code/claude-config-template/scripts/cleanup-sessions.sh auto'
alias claude-stats='~/code/claude-config-template/scripts/cleanup-sessions.sh stats'

Automated Usage

Sessions can be automatically created and updated by Claude or integrated into your development workflow.

Directory Structure

~/.claude/
├── sessions/           # Session JSON files
│   ├── session-{uuid}.json
│   └── archive/       # Archived sessions
└── commands/          # Command documentation
    ├── resume-context.md
    └── last-session-recovery.md

Best Practices

  1. Regular Updates: Update session context as work progresses
  2. Clear Descriptions: Use meaningful descriptions for operations
  3. Complete Sessions: Mark sessions as completed when done
  4. Regular Cleanup: Run cleanup monthly (30-day retention by default)
  5. Project Organization: Sessions are tracked per project path

Troubleshooting

No Sessions Found

  • Check if ~/.claude/sessions/ exists
  • Verify you're in the correct project directory
  • List all sessions with ./log-session.sh list

JSON Parsing Errors

  • Ensure jq is installed: brew install jq (macOS) or apt install jq (Linux)
  • Check JSON syntax in session files
  • Verify proper escaping of special characters

Permission Issues

  • Ensure scripts are executable: chmod +x *.sh
  • Check directory permissions: ls -la ~/.claude/

Dependencies

  • Bash 4+ (for associative arrays)
  • jq (for JSON processing)
  • Standard Unix tools: date, find, grep, sed

License

These scripts are part of the claude-config-template project.