GitLore Hologram

GitLore Hologram is an Architectural HUD extension for Visual Studio Code that provides instant code intelligence through AI-powered analysis. It connects to a Next.js backend powered by Google Gemini to deliver structured file summaries and real-time risk assessments directly within your editor.

Overview

GitLore Hologram transforms code navigation by providing contextual insights without leaving your editor. The extension analyzes TypeScript and JavaScript files to deliver structured architectural summaries and function-level risk metrics. Built as a lightweight VS Code extension that communicates with a cloud-based Next.js and Gemini backend for scalable AI processing.

Features

File Narrator

The Narrator sidebar provides structured file analysis with three key components:

• Purpose: High-level description of the file's primary responsibility
• Key Components: Identification of major modules, classes, or functions
• Architecture: Structural patterns and design decisions

Results are cached locally to minimize API calls and improve performance. The sidebar updates automatically when switching between files, with manual control via the "Scan File" button.

Risk CodeLens

Inline risk analysis appears above function and const declarations using VS Code's CodeLens feature:

• Risk Scoring: Numerical assessment on a scale of 1-10 (1 = low risk, 10 = high risk)
• Visual Indicators: Color-coded progress bars (green/orange/red) based on risk level
• Detailed Analysis: Contextual explanations for each risk assessment
• Interactive: Click any CodeLens to view detailed risk report in the Narrator sidebar

Supported patterns include traditional function declarations and modern arrow function syntax.

Configuration

Configure the extension through VS Code Settings (Ctrl+, / Cmd+,) or directly in settings.json:

Example Configuration

{
  "gitlore.apiUrl": "https://gitloree.vercel.app",
  "gitlore.secret": "your-secret-key-here"
}

How It Works

The extension communicates with a Next.js backend that leverages Google Gemini for AI analysis. The architecture follows a clear request-response pattern:

Narrator Endpoint

Request: POST /api/extension/narrate

• Headers: x-gitlore-extension-key (secret authentication)
• Body: { fileContent: string, filePath: string }

Response: JSON object with structured fields

{
  "purpose": "File purpose description",
  "components": "Key components list",
  "architecture": "Architectural patterns description"
}

The extension minifies code before transmission (removes comments, collapses whitespace) and caches results based on file version to optimize token usage.

Risk Analysis Endpoint

Request: POST /api/extension/risk

• Headers: x-gitlore-extension-key (secret authentication)
• Body: { functionCode: string }

Response: JSON object with risk metrics

{
  "score": 5,
  "reason": "Detailed risk explanation"
}

The score ranges from 1 (low risk) to 10 (high risk), with color coding: green (1-4), orange (5-7), red (8-10).

Installation

From VS Code Marketplace

1. Open VS Code
2. Navigate to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "GitLore Hologram"
4. Click Install

From VSIX File

1. Download the .vsix package from the Releases page
2. Open VS Code Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Execute "Extensions: Install from VSIX..."
4. Select the downloaded .vsix file

Post-Installation

After installation, configure the gitlore.apiUrl and gitlore.secret settings if using a custom backend instance. The extension activates automatically when opening supported file types.

Requirements

• VS Code: Version 1.85.0 or higher
• Internet Connection: Required for backend API communication
• Supported Languages: TypeScript (.ts), JavaScript (.js), JavaScript React (.jsx), TypeScript React (.tsx)

Usage

File Analysis

1. Open the GitLore activity bar icon in the left sidebar
2. Select any TypeScript or JavaScript file in the editor
3. Click "Scan File" in the Narrator view to analyze
4. Review the structured summary (Purpose, Components, Architecture)

Risk Analysis

1. Open any supported file type
2. CodeLens indicators appear above function declarations
3. Click any "Analyze Risk" CodeLens to view detailed assessment
4. Risk scores and explanations display in the Narrator sidebar

Troubleshooting

Connection Errors

If the Narrator sidebar displays connection errors:

• Verify gitlore.apiUrl points to a valid backend endpoint
• Confirm gitlore.secret matches backend configuration
• Check network connectivity and firewall settings
• Review VS Code Output panel (View > Output > GitLore Hologram) for detailed error messages

CodeLens Not Appearing

If risk indicators do not appear:

• Ensure file type is supported (.ts, .js, .jsx, .tsx)
• Reload VS Code window (Ctrl+Shift+P > "Developer: Reload Window")
• Check that extension is activated (appears in Extensions sidebar)
• Verify file contains function or const declarations

Extension Activation Issues

If the extension fails to activate:

• Confirm VS Code version meets minimum requirement (1.85.0+)
• Check Extensions panel for activation errors
• Review Output panel for runtime errors
• Reinstall extension if issues persist

Development

Prerequisites

• Node.js 18.x or higher
• npm or yarn package manager

Setup

git clone https://github.com/Tusharkaushik1106/githologram.git
cd gitlore-hologram
npm install
npm run compile

Build Commands

npm run compile    # Compile TypeScript to JavaScript
npm run watch      # Watch mode for development
npm run lint       # Run ESLint
npm test           # Execute test suite

Project Structure

gitlore-hologram/
├── src/
│   └── extension.ts      # Main extension logic
├── out/                  # Compiled JavaScript output
├── package.json          # Extension manifest and dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md            # Documentation

Contributing

Contributions are welcome. Please follow these steps:

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

License

This project is licensed under the MIT License.

Author

Tushar Kaushik (Tusharkaushik1106)

Developed and maintained by Tushar Kaushik. For issues, questions, or contributions, please visit the GitHub repository.

Note: This extension requires a GitLore backend server. The default configuration uses the hosted instance at https://gitloree.vercel.app. For self-hosting, configure a custom backend and update gitlore.apiUrl accordingly.