Code Historian

✨ Features

🔄 Automatic Change Capture

• Real-time capture of all code changes as you work
• Intelligent debouncing to avoid capturing every keystroke
• Configurable exclusion patterns for node_modules, build files, etc.
• Tracks file creates, modifies, deletes, and renames
• Session-based organization for better context

🧠 Semantic Search with RAG

• Natural language queries: "What changes did I make to the authentication logic?"
• Hybrid search combining vector similarity and keyword matching (BM25)
• Context-aware results with relevant code snippets
• Temporal filtering: "Changes from last week"
• Powered by state-of-the-art embedding models

💬 Chat Integration

• Use @historian in VS Code Chat to explore your code history
• Conversational interface powered by your choice of LLM
• Ask questions like:
  • "When did I last modify the User class?"
  • "Find all changes related to database queries"
  • "What did the login function look like before the refactor?"

⏪ Code Restoration

• Restore any previous version of your code with one click
• Preview changes before restoring
• Automatic backup creation before restoration
• Works seamlessly with your existing git workflow

📊 Visual Timeline

• Beautiful, modern timeline view of all changes
• Multiple view modes: Timeline, Cards, or Compact list
• Stats dashboard with activity heatmap
• Group by date, file, or folder
• Inline diff preview with syntax highlighting
• Filter by change type, date range, and more

🚀 Installation

From Source

git clone https://github.com/KirtiJha/code-historian.git
cd code-historian
npm install
npm run build

Then press F5 in VS Code to launch the extension in development mode.

VS Code Marketplace

Coming soon!

⚙️ Configuration

Open VS Code Settings (Cmd/Ctrl + ,) and search for "Code Historian".

Embedding Provider

Code Historian supports multiple embedding providers for semantic search:

{
  "codeHistorian.embedding.provider": "huggingface",
  "codeHistorian.embedding.model": "BAAI/bge-large-en-v1.5"
}

LLM Provider

For the chat interface, configure your preferred LLM:

{
  "codeHistorian.llm.provider": "openai",
  "codeHistorian.llm.model": "gpt-4o",
  "codeHistorian.llm.apiKey": "your-api-key"
}

Capture Settings

{
  "codeHistorian.capture.enabled": true,
  "codeHistorian.capture.debounceMs": 2000,
  "codeHistorian.capture.excludePatterns": [
    "**/node_modules/**",
    "**/.git/**",
    "**/dist/**",
    "**/*.lock"
  ],
  "codeHistorian.capture.maxFileSizeKB": 1024
}

📖 Usage

Timeline View

1. Click the Code Historian icon in the Activity Bar (sidebar)
2. Browse your change history with multiple view options:
   • Timeline View: Classic vertical timeline with connecting lines
   • Cards View: Grid layout for visual scanning
   • Compact View: Dense list for maximum information
3. Use filters to narrow down results:
   • Filter by change type (Created, Modified, Deleted)
   • Filter by date range
   • Search by filename or content
4. Click any change to see detailed diff view
5. Restore any previous version with one click

Chat Commands

Open VS Code Chat (Cmd/Ctrl + Shift + I) and use @historian:

@historian What changes did I make to the authentication module?
@historian Show me the login function from last week
@historian Find all database-related changes
@historian When did I add the validation logic?

Keyboard Shortcuts

🏗️ Architecture

Code Historian uses a modern architecture optimized for VS Code extensions:

┌─────────────────────────────────────────────────────────────┐
│                     VS Code Extension                        │
├──────────────┬──────────────┬───────────────┬───────────────┤
│   Capture    │   Embedding  │    Search     │     LLM       │
│   Engine     │   Service    │    Engine     │  Orchestrator │
│              │              │               │               │
│  • Debounce  │  • HuggingFace│ • Hybrid     │  • OpenAI     │
│  • Diff Gen  │  • Ollama    │   Search     │  • Anthropic  │
│  • Sessions  │  • OpenAI    │ • BM25+Vector│  • Ollama     │
├──────────────┴──────────────┴───────────────┴───────────────┤
│                      Database Layer                          │
│     SQLite (sql.js)          │        LanceDB               │
│     • Metadata               │        • Vector embeddings   │
│     • FTS5 keyword search    │        • Similarity search   │
├──────────────────────────────┴──────────────────────────────┤
│                     React Webview UI                         │
│  Timeline • Search • Settings • Diff Viewer • Chat          │
└─────────────────────────────────────────────────────────────┘

Key Technologies

Search Pipeline

User Query → Embedding → Vector Search (top-k)
                     ↘
                       RRF Fusion → Ranked Results
                     ↗
            → BM25 Keyword Search (FTS5)

The hybrid search combines:

• Vector similarity (60% weight): Semantic understanding of code
• Keyword matching (40% weight): Exact term matches via FTS5
• Reciprocal Rank Fusion: Combines both result sets with overlap boosting

📈 Performance

Storage: ~1MB per 1,000 changes (including embeddings)

🔒 Privacy

Your data stays 100% local by default:

• ✅ SQLite database in VS Code's global storage
• ✅ LanceDB vectors stored locally
• ✅ Optional Ollama for completely local AI
• ✅ No telemetry or external data sharing
• ✅ API keys stored securely in VS Code settings

When using cloud providers (OpenAI, HuggingFace, Anthropic), only embedding requests and chat queries are sent externally.

🛠️ Development

# Clone the repository
git clone https://github.com/KirtiJha/code-historian.git
cd code-historian

# Install dependencies
npm install

# Build the extension
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Type checking
npm run typecheck

# Linting
npm run lint

# Run tests
npm test

Project Structure

code-historian/
├── src/
│   ├── extension.ts        # Extension entry point
│   ├── constants.ts        # Configuration constants
│   ├── types/              # TypeScript type definitions
│   ├── database/           # SQLite & LanceDB wrappers
│   ├── services/           # Core services
│   │   ├── capture.ts      # Change capture engine
│   │   ├── embedding.ts    # Embedding service
│   │   ├── search.ts       # Hybrid search engine
│   │   ├── llm.ts          # LLM orchestrator
│   │   └── restoration.ts  # Code restoration
│   ├── chat/               # VS Code Chat participant
│   ├── webview/            # React webview UI
│   │   ├── ui/             # React components
│   │   └── provider.ts     # Webview provider
│   └── utils/              # Utilities
├── media/                  # Icons and assets
├── dist/                   # Build output
└── package.json            # Extension manifest

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guide for details on our code of conduct and development process.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• LanceDB - Excellent embedded vector database
• Ollama - Local AI inference made easy
• HuggingFace - State-of-the-art embeddings
• VS Code - Amazing extension API
• sql.js - SQLite compiled to WebAssembly