Captures your debugging sessions (commands run, files touched) and uses a local LLM to reconstruct the reasoning path — which hypotheses you tried and ruled out, not just the final fix — then makes past sessions semantically searchable.
100% free / local: Postgres+pgvector in Docker, Ollama running natively on Windows for GPU access, no paid APIs anywhere.
- Docker Desktop — for Postgres. https://www.docker.com/products/docker-desktop/
- Ollama for Windows — https://ollama.com/download/windows
- Git Bash (comes with Git for Windows) — the capture hook is a bash script; Git Bash is the simplest way to run it on Windows without WSL.
- Python 3.11+
ollama pull qwen2.5:3b-instruct-q4_K_M
ollama pull nomic-embed-textSet OLLAMA_NUM_PARALLEL=1 as a system environment variable (Windows
Settings → Environment Variables) before starting Ollama — keeps VRAM
usage predictable on a 4GB card.
cd debug-miner
docker compose up -dThis automatically enables the pgvector extension via init.sql.
cd backend
python -m venv venv
source venv/Scripts/activate # Git Bash on Windows
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reloadBackend now running at http://localhost:8000. Tables are created
automatically on first run.
In Git Bash, add this line to your ~/.bashrc:
source /path/to/debug-miner/capture/precmd_hook.shThen in a separate terminal, install capture deps and start the watcher (leave this running in the background while you work):
cd capture
pip install -r requirements.txt
python watcher.pyJust open frontend/index.html directly in your browser — no build step,
no server needed. It talks to the backend at localhost:8000.
# Start capturing a debugging session
python capture/debugctl.py start "payment-svc timeouts in prod"
# ... do your normal debugging: grep, kubectl logs, open files, etc.
# every shell command is captured automatically in the background ...
# When resolved:
python capture/debugctl.py end "raised max_connections 20 -> 50, restarted"
# Run the LLM reconstruction pass (prints the session_id after `end`)
python capture/debugctl.py reconstruct <session_id>Then search past sessions from frontend/index.html.
- Ollama runs natively on Windows, not in Docker — GPU passthrough to containers on Windows adds driver-translation overhead that costs real speed on a 4GB card. Only Postgres is containerized.
- Reconstruction quality at 3B model scale is the weakest link in this
pipeline, particularly multi-hop inference (e.g. correctly linking a
grep+ a file open + a database query into one confirmed hypothesis). The few-shot example baked intobackend/app/services/reconstruction.pymatters more than prompt wording — if quality is weak on your real sessions, add 1-2 more few-shot examples from your own past incidents before considering a bigger model. - File-open capture (editor-side) isn't wired up yet — this MVP is
shell-only. A VS Code extension using
onDidOpenTextDocument/onDidChangeActiveTextEditorposting to the same/events/batchendpoint is the natural next step.