NecroGit — The Repository Medium | Offline Code Archaeology & Resurrection

Capabilities

The Repository Medium's Toolset

Designed for software archaeologists, maintainers, and security engineers dealing with decades of unmaintained dependencies.

🔍

AST Bitrot Archaeology

Parses legacy code into Abstract Syntax Trees to detect removed standard libraries (Python 3.12/3.13 dead battery PEP 594 removals like imp, pipes, cgi), deprecated timing functions, and structural syntax rot.

🧙

Git Persona Reconstruction

Mines repository commit history to divine the primary maintainer's name, commit volume, era, and stylistic cadence (laconic, balanced, or verbose), preserving historic variable casing and comments.

⚡

Local Gemma 2 Inference

Channels Google Gemma 2 and Meta Llama 3.2 locally via Ollama or vLLM. Proprietary or confidential source trees never leave your local workstation. Zero cloud token fees.

📜

Historical Design Exegesis

The necrogit explain command interviews the maintainer's ghost to explain why obscure historical workarounds (GIL contention, pre-PEP 418 clock resolution, old threading models) were originally chosen.

🧠

Backboard Persistent Memory

Integrates persistent agent memory across CLI runs. Stores repository dossiers locally in .necrogit/seance_memory.json and seamlessly synchronizes with Backboard (R-CLI / backboard.io) when configured.

📡

Sentry Agent Tracing

Instrumented with sentry-sdk>=2.0.0, tracking step-by-step code archaeology spans (AST scanning, Git graph analysis, LLM inference latency, and diagnostic breadcrumbs).

Workflow

From Bitrot to Resurrection

A deterministic, four-step pipeline transforming abandoned repos into modern, deployable code.

STEP 01

1. Inspect Bitrot

Run necrogit inspect to detect deprecated imports, dead batteries, and syntax errors across the target tree.

STEP 02

2. Summon Spirit

Execute necrogit summon to extract historical commit patterns, vocabulary, and maintainer persona.

STEP 03

3. Channel Séance

Local Gemma 2 combines the AST findings and persona to generate an in-character unified diff patch or design exegesis.

STEP 04

4. Verify & Apply

Review the unified diff output in your terminal and apply directly via necrogit patch --apply or git apply.

Live Simulation

Interactive Séance Workbench

Test code archaeology and simulated maintainer patch generation directly in your browser.

Legacy Python Code Artifact Contains Python 3.8-3.13 Deprecations

"""Legacy Python module exhibiting classical bitrot relics."""

import imp
import pipes
import cgi
import time
import asyncio

def execute_stream(command_str):
    t = pipes.Template()
    t.append(command_str, "--")
    return t

def benchmark():
    t0 = time.clock()
    return time.clock() - t0

def init_loop():
    return asyncio.get_event_loop()

Maintainer Essence Persona (Simulated Browser Channel)

Discovered Bitrot Relics

Run AST scan to identify deprecated modules...

Channelled Unified Diff Output Ready for git apply

--- (Awaiting resurrective patch channeling...) ---

🕯️ NecroGit Spectral Shell v0.1.0 [Hacktoberfest 2026 Edition] Type 'help' to review available divination commands.

developer@necrogit:~$

Reference Manual

CLI Documentation & Setup

Complete guide to running NecroGit on Linux, macOS, and Windows PowerShell.

🚀 Quickstart Installation

# 1. Create a virtual environment
python -m venv .venv

# 2. Activate virtual environment (Windows PowerShell)
.\.venv\Scripts\Activate.ps1
# (Or on Linux/macOS: source .venv/bin/activate)

# 3. Install in editable mode
pip install -e .

# 4. Verify installation
necrogit --help

Command	Arguments / Options	Description & Behavior
`necrogit summon`	`[REPO_PATH]`	Mines Git commit history to extract the primary maintainer's name, commit volume, active era, and stylistic cadence.
`necrogit inspect`	`[TARGET_DIR]`	Recursively scans Python code via AST for obsolete libraries (`imp`, `pipes`, `cgi`, `time.clock`) and syntax errors.
`necrogit patch`	`<FILE> [--model] [--base-url] [--apply]`	Channels the maintainer via local LLM (Ollama) to draft an in-style unified diff. With `--apply`, writes a verified `.patch` file.
`necrogit explain`	`<FILE> [--symbol] [--model] [--base-url]`	Interviews the maintainer's spirit to explain obscure historical design choices and architectural trade-offs.
`necrogit memory`	`[REPO_PATH] [--clear]`	Displays stored séance dossiers from Backboard persistent memory. Bare invocation displays all known repositories.
`necrogit serve`	`[--port 8000] [--open/--no-open]`	Starts a local HTTP server and automatically opens this interactive CRT documentation workbench in your browser.
`necrogit export-web`	`[DESTINATION] [--zip/--no-zip]`	Exports the complete static documentation website and generated `necrogit-site.zip` bundle to any target folder.
`necrogit doctor`	`[--model] [--base-url]`	Performs system diagnostics checking Python, Git, Sentry, Backboard, and probe connectivity to your local Ollama server.

Under the Hood

Architectural Design

Air-gapped by default, telemetry-instrumented when enabled.

                     ┌────────────────────────────────────────┐
                     │          Abandoned Repository          │
                     └───────────────────┬────────────────────┘
                                         │
                  ┌──────────────────────┴──────────────────────┐
                  ▼                                             ▼
     ┌────────────────────────┐                    ┌────────────────────────┐
     │    MaintainerMedium    │                    │   ArchaeologyScanner   │
     │  (GitPython Log Miner) │                    │    (AST NodeVisitor)   │
     └────────────┬───────────┘                    └────────────┬───────────┘
                  │ Maintainer Persona                          │ Bitrot Relics &
                  │ (name, cadence, style)                      │ Deprecations
                  └──────────────────────┬──────────────────────┘
                                         │
                                         ▼
                            ┌────────────────────────┐
                            │      SeanceEngine      │
                            │   Google Gemma 2 9B    │
                            │  (Ollama localhost)    │
                            └────────────┬───────────┘
                                         │
                  ┌──────────────────────┴──────────────────────┐
                  ▼                                             ▼
     ┌────────────────────────┐                    ┌────────────────────────┐
     │ Resurrective Diff File │                    │    Backboard Memory    │
     │     (.patch format)    │                    │ (Persistent Dossier &  │
     │                        │                    │  Sentry Span Tracing)  │
     └────────────────────────┘                    └────────────────────────┘

Privacy First

Security & Data Boundaries

An honest, auditable account of how your source code is handled.

🛡️

Air-Gapped Local Inference

All code analysis, prompt construction, and patch synthesis happen strictly on your machine via http://localhost:11434. Code is never transmitted to cloud APIs like OpenAI or Anthropic.

🔒

Opt-In Sentry Observability

Sentry Agent Tracing is completely disabled unless you explicitly supply the SENTRY_DSN environment variable. No anonymous telemetry is collected by default.

💾

Local Persistent Memory

Séance memory dossiers are saved locally in .necrogit/seance_memory.json. Cloud state synchronization with Backboard requires an explicit BACKBOARD_API_KEY.

CLI Setup

Install NecroGit CLI Locally

NecroGit is primarily a local developer CLI tool for your terminal. Install it once in your Python environment and execute it against any cloned repository on your workstation.

1. Install NecroGit via PowerShell:

Install directly from GitHub or from PyPI into your active virtual environment or Python user installation:

# Install CLI directly from GitHub repository:
python -m pip install "git+https://github.com/avrojitduttaj/necrogit.git"

# Or install from PyPI registry:
python -m pip install necrogit

# Verify CLI entry point and system diagnostics:
necrogit doctor

2. Run Against Any Cloned Repository:

Open any legacy repository in VS Code or PowerShell and commune with its history:

# Navigate to your target repository
cd path\to\any-legacy-repo

# Scan all Python files for bitrot and deprecated standard libraries
necrogit inspect .

# Summon original maintainer's persona from git commit logs
necrogit summon .

# Synthesize a style-preserving diff for a legacy file (requires Ollama running)
necrogit patch path\to\relic.py --apply

# Interview the ghost regarding historical architecture choices
necrogit explain path\to\relic.py --symbol run_pipeline

# Check persistent repository memory dossiers
necrogit memory

1. Install NecroGit via Terminal:

Install into your Python virtualenv or user environment using pip:

# Install CLI directly from GitHub:
python3 -m pip install "git+https://github.com/avrojitduttaj/necrogit.git"

# Or install from PyPI:
python3 -m pip install necrogit

# Verify installation:
necrogit doctor

2. Run Against Any Cloned Repository:

Navigate to your target repository and resurrect legacy code:

# Navigate to your target project
cd path/to/any-legacy-repo

# Run AST bitrot inspection
necrogit inspect .

# Mine git logs to divine the maintainer essence
necrogit summon .

# Generate an in-style unified diff
necrogit patch path/to/relic.py --apply

# Explain legacy design decisions
necrogit explain path/to/relic.py --symbol run_pipeline

# View persistent dossiers
necrogit memory

1. Install NecroGit via Bash:

Install into your Python environment using pip:

# Install directly from GitHub:
pip install "git+https://github.com/avrojitduttaj/necrogit.git"

# Or install from PyPI:
pip install necrogit

# Check diagnostics:
necrogit doctor

2. Run Against Any Cloned Repository:

Execute directly in your target repository:

# Enter your target project directory
cd path/to/any-legacy-repo

# Scan code files
necrogit inspect .

# Channel git author history
necrogit summon .

# Draft resurrective patch
necrogit patch path/to/relic.py --apply

# Memory status
necrogit memory

Downloads & Distribution

Packages & Web Bundles

Distinguish between the installable developer CLI tool and the offline web documentation bundle.

📦 NecroGit Local CLI Tool

Python Package

The primary developer tool. Runs in your terminal to inspect codebases, summon maintainers, and generate patches.

# Install via GitHub

pip install "git+https://github.com/avrojitduttaj/necrogit.git"

# Install via PyPI

pip install necrogit

View on GitHub

🌐 Standalone Web Documentation

Static ZIP

Self-contained documentation workbench with interactive CRT simulator and reference guides. (Not required for running CLI scans).

# Or export locally from CLI:

necrogit export-web ./docs

# Host with built-in server:

necrogit serve --port 8000

Download necrogit-site.zip

Questions & Answers

Frequently Asked Questions

What if Ollama returns 404 Not Found?

Ensure Ollama is running (`ollama serve`) and updated to >= 0.1.24. NecroGit automatically supports both the OpenAI-compatible /v1/chat/completions endpoint and native /api/chat fallback. Run necrogit doctor to diagnose.

Which local open-weight models are supported?

Google Gemma 2 (gemma2:9b, gemma2:2b, gemma2:27b) and Meta Llama 3.2 (llama3.2:3b). Gemma 2 9B is the recommended default for complex code reasoning.

How does NecroGit preserve maintainer coding style?

NecroGit mines commit frequency and author log cadence to construct a maintainer prompt persona. It instructs the local model to preserve variable naming, casing, and comment cadence while upgrading deprecated APIs.

How do I host this website on GitHub Pages?

Run necrogit export-web ./docs, commit the docs directory to your repository, and enable GitHub Pages on the /docs folder in repository settings.