Skip to content
CodeNeuron58Public

About

A séance for your git history. Every ghost brings receipts.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Poltergit

Poltergit

A séance for your git history. Every ghost brings receipts.

An open-source tool that asks any line of code why it exists — and answers in the line's own voice,
citing the commits, diffs and discussions behind it. Where the record is silent, it says so.
It all runs on your own laptop.

Tests MIT license Runs 100% locally Read the write-up on DEV

Watch the demo
▶ Watch the 44-second demo

How it works

The séance room: pick a haunted line The line answers with a citation Evidence cards behind the answer
1 · Summon
Point at any line. Poltergit walks its history with git log -L — the commits, the diffs, the discussions around them.
2 · The line speaks
Gemma answers in first person — as the code, never its author — with a citation attached to every claim.
3 · The receipts
Every claim must quote its source exactly, or the answer is discarded and labeled excerpts are shown instead.

When the record is silent

The ofrenda: memorials for deleted code

Silence is a feature, not a failure. A magic number changed by a commit titled "update"? The record is silent. No invented intent, no guessed reasons — the same honesty as a historian's "not stated".

And for code that has passed on, poltergit ofrenda builds a Día de los Muertos memorial: every deleted file and function gets an obituary — when it was added, how long it served, and the commit that retired it.

Built with

Open-source piece What it does
Gemma 4 E4B Writes the answers, locally through Ollama — structured JSON, temperature 0.15
EmbeddingGemma Turns history into 768-dimension vectors for retrieval
Tiger Data · pgvector Hybrid keyword + vector search that finds the evidence line history alone misses
Kokoro Reads the answer aloud in a séance-room echo, entirely on ONNX
Sentry Traces every séance: history walk, hybrid search, model call, verification
FastAPI · Typer · Jinja2 The local web séance, CLI, and the ofrenda export

What the record shows

Without hybrid search With Tiger Data + pgvector
A retry loop whose only commit says "introduce the client" The record is silent "I exist to tolerate the gateway maintenance window, as seven attempts cover the gateway's eighteen-second maintenance window…" — cited

Every generated citation is checked verbatim against its source before you see it. In live testing, one fabricated citation was caught and discarded — the séance fell back to the original commit text, clearly labeled. Every run is traced end to end: the git walk, the database search, the model call with its token counts, and the verification step — at $0.00 inference cost.

Run it locally

Git, Python 3.12+, uv and Ollama with gemma4:e4b and embeddinggemma.

uv sync
uv run poltergit doctor          # every local component reports ready
uv run poltergit demo            # create the fictional demo repository
uv run poltergit why src/client.py:13 --repo .poltergit/demo --record
uv run poltergit serve --repo .poltergit/demo --record   # http://127.0.0.1:8787
uv run poltergit ofrenda --repo .poltergit/demo --output site
uv run pytest

Drop --record to let Gemma answer (set POLTERGIT_TIMEOUT=600 on CPU-only machines — answers take two to three minutes without a GPU). Optional integrations go in .env: POLTERGIT_DATABASE_URL for hybrid search, POLTERGIT_SENTRY_DSN for tracing, POLTERGIT_GITHUB=true for PR and issue retrieval. Full setup: docs/SETUP.md

Acknowledgments

The demo repository is fictional, clearly labeled, and contacts no real service. The séance reads committed HEAD only, sends nothing to the cloud, and never impersonates a developer. Entire was considered for the agent-session category and intentionally omitted.


Honor the past. Understand the present. 🕯️

About

A séance for your git history. Every ghost brings receipts.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages