• 🎯 Why CodeLapse?
• 🚀 Quick Start
• ✨ Features at a Glance
• 🖥️ CLI Tool - Automation & Integration Ready
• 📚 Documentation & Support
• ⚙️ Configuration
• 📋 System Requirements

• ⚡ One-Key Snapshots: Ctrl+Alt+S - instant backup
• 🔄 Time Navigation: Jump between any point in your development
• 📊 Visual Timeline: See your progress in the Snapshots panel
• 📈 Status Tracking: Status bar shows time since last snapshot
• 🔍 Smart Search: Find code across all snapshots (Experimental)

• 📝 Rich Context: Add tags, notes, and task references
• ⭐ Favorites: Mark important snapshots
• 🔍 Powerful Filtering: By date, tags, files, or favorites
• 📋 Selective Snapshots: Choose specific files to include
• 🔄 File Restoration: Restore individual files or entire snapshots

• ⏰ Auto-Snapshots: Time-based automatic backups
• 📋 Smart Rules: Auto-snapshot specific file patterns
• 📊 Visual Indicators: See changed lines in editor gutters
• ⚡ Performance: Efficient storage with differential compression
• 🚫 Smart Exclusion: Respects .gitignore and .snapshotignore

• 📝 Branch Context: Store Git branch/commit info with snapshots
• 🔄 Git Commands: Create commits directly from snapshots
• 🤝 Perfect Harmony: Works alongside Git without conflicts

Not implemented: taking a snapshot automatically before git pull, git merge or git rebase run from the VS Code Git UI. No such setting exists (the previous git.autoSnapshotBeforeOperation did nothing and was removed), and VS Code exposes no pre-operation hook. Take the snapshot explicitly with Ctrl+Alt+S or codelapse git auto-commit <operation> before a destructive Git operation. See the open issues.

Interactive Development Workflow

# Create checkpoint before risky changes
codelapse snapshot create "Before refactoring auth system" --tags "checkpoint,auth"

# Work on your code...

# Create snapshot after major milestone
codelapse snapshot create "Auth refactor complete" --tags "feature,auth" --favorite

# Compare changes between snapshots
codelapse snapshot compare snapshot-123 snapshot-124

# Navigate through your development timeline
codelapse snapshot navigate next

Code Review & Collaboration

# Export snapshot for sharing with team
codelapse utility export snapshot-123 --format zip --output ./auth-feature.zip

# Validate snapshot integrity before sharing
codelapse utility validate snapshot-123

# Show detailed snapshot with specific file content
codelapse snapshot show snapshot-123 --files --content src/auth.ts

Safety-First AI Operations

# 1. ALWAYS create backup before AI operations
BACKUP_ID=$(codelapse snapshot create "AI: Pre-operation backup" --tags "backup,ai" --json | jq -r '.snapshot.id')

# 2. Execute AI operations with error handling
if codelapse snapshot restore snapshot-123 --backup --silent; then
  echo "✅ Operation successful"
else
  echo "❌ Operation failed, restoring backup"
  codelapse snapshot restore "$BACKUP_ID" --silent
fi

# 3. Document completed work
codelapse snapshot create "AI: Completed refactoring task" --tags "complete,ai" --favorite --silent

Batch Processing & Real-time Monitoring

# Execute multiple operations from JSON file
cat > ai-workflow.json << EOF
[
  { "method": "takeSnapshot", "data": { "description": "Pre-operation backup", "tags": ["backup"] } },
  { "method": "getSnapshots", "data": { "tags": ["feature"], "limit": 5 } },
  { "method": "takeSnapshot", "data": { "description": "Post-operation state", "tags": ["complete"] } }
]
EOF

codelapse batch ai-workflow.json --json

# Monitor workspace changes for reactive workflows
codelapse watch --events snapshots,workspace --json | while read -r event; do
  echo "Processing event: $event"
  # Add your AI logic here
done

CI/CD Pipeline Integration

# Pre-deployment snapshot with Git context
codelapse snapshot create "Pre-deployment: $(git rev-parse --short HEAD)" \
  --tags "deployment,$(git branch --show-current)" --silent

# Validate the workspace the CLI sees before deployment
codelapse workspace info --json

# Create release snapshot with version tagging
codelapse snapshot create "Release v$(cat package.json | jq -r .version)" \
  --tags "release,production" --favorite --silent

Automated Testing Workflows

# Create test checkpoint
codelapse snapshot create "Before test run" --tags "test,checkpoint" --silent

# Run tests and capture results
if npm test; then
  codelapse snapshot create "Tests passed: $(date)" --tags "test,success" --silent
else
  codelapse snapshot create "Tests failed: $(date)" --tags "test,failure" --silent
  # Optionally restore to last known good state
  codelapse snapshot restore last-good-snapshot --backup --silent
fi

name: CodeLapse Integration
on: [push, pull_request]

jobs:
  test-with-codelapse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install CodeLapse CLI
        run: npm install -g codelapse-cli
      
      - name: Create pre-test snapshot
        run: codelapse snapshot create "CI: Pre-test snapshot" --tags "ci,test" --silent
      
      - name: Run tests
        run: npm test
      
      - name: Create post-test snapshot
        run: codelapse snapshot create "CI: Post-test snapshot" --tags "ci,success" --silent

FROM node:20-alpine

# Install CodeLapse CLI
RUN npm install -g codelapse-cli

# Copy application
COPY . /app
WORKDIR /app

# Create deployment snapshot
RUN codelapse snapshot create "Docker: Pre-build snapshot" --tags "docker,build" --silent || true

# Build application
RUN npm install && npm run build

# Create post-build snapshot
RUN codelapse snapshot create "Docker: Post-build snapshot" --tags "docker,complete" --silent || true

• vscode-snapshots.snapshotLocation: Where to store snapshot data (default: .snapshots)
• vscode-snapshots.maxSnapshots: Maximum number of snapshots to keep (default: 50)
• vscode-snapshots.autoSnapshotInterval: Interval for automatic snapshots in minutes (default: 0 - disabled)
• vscode-snapshots.loggingEnabled: Enable detailed logging (default: true)

• vscode-snapshots.git.addCommitInfo: Store Git branch/commit with snapshots (default: true)
• vscode-snapshots.git.commitFromSnapshotEnabled: Enable "Create Git Commit from Snapshot" command (default: true)

There is no setting for taking a snapshot before a Git operation. The previous git.autoSnapshotBeforeOperation was removed because nothing ever invoked the interception it configured. See the open issues.

⚠️ EXPERIMENTAL FEATURE - SECURITY RISKS: See the experimental feature warning above.

Basic Settings:

• vscode-snapshots.semanticSearch.enabled: Enable semantic code search (default: true)
• vscode-snapshots.semanticSearch.chunkSize: Maximum number of lines per code chunk (default: 200)
• vscode-snapshots.semanticSearch.chunkOverlap: Overlap between adjacent chunks, in lines (default: 50, clamped to chunkSize - 5)
• vscode-snapshots.semanticSearch.autoIndex: Auto-index snapshots in background (default: false)
• vscode-snapshots.semanticSearch.embedding.model / .dimension: Embedding model id and vector dimension (defaults: gemini-embedding-2, 3072)

There is no offline mode. Semantic search needs both a Gemini API key (embeddings) and a Pinecone API key (vector store). Indexing prompts for a missing key and fails if you decline the prompt; it never falls back to a local index.

🔑 API Key Management & Security:

• Secure Storage: API keys are stored using VS Code's SecretStorage (encrypted)
• Access Control: Keys are never logged or displayed in plain text
• Configuration: Manage keys via Settings view in Snapshot Explorer
• Required Services:
  • Pinecone API Key: For vector database storage and retrieval
  • Gemini API Key: For semantic code analysis and embeddings

⚠️ Not everything is in SecretStorage. The API keys are. The CLI connection file is not: on every activation the extension writes .vscode/codelapse-connection.json inside your workspace, containing the IPC auth token and socket path for the running session. It is listed in .gitignore, so do not remove that entry, and treat any committed copy as a leaked credential. The token is regenerated on every activation, so a stale copy is inert.

🛡️ Security Best Practices:

• Use dedicated API keys with minimal permissions
• Monitor API usage and costs regularly
• Disable feature when working with sensitive code
• Review API provider terms of service
• Consider network security implications

🚫 How to Disable:

1. Set vscode-snapshots.semanticSearch.enabled to false, OR
2. Use Settings view in Snapshot Explorer → Semantic Search → Disable