Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Debug Miner

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.

Prerequisites (Windows 11)

  1. Docker Desktop — for Postgres. https://www.docker.com/products/docker-desktop/
  2. Ollama for Windows — https://ollama.com/download/windows
  3. 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.
  4. Python 3.11+

1. Pull the local models

ollama pull qwen2.5:3b-instruct-q4_K_M
ollama pull nomic-embed-text

Set OLLAMA_NUM_PARALLEL=1 as a system environment variable (Windows Settings → Environment Variables) before starting Ollama — keeps VRAM usage predictable on a 4GB card.

2. Start Postgres

cd debug-miner
docker compose up -d

This automatically enables the pgvector extension via init.sql.

3. Start the backend

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 --reload

Backend now running at http://localhost:8000. Tables are created automatically on first run.

4. Set up capture

In Git Bash, add this line to your ~/.bashrc:

source /path/to/debug-miner/capture/precmd_hook.sh

Then 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.py

5. Open the search UI

Just open frontend/index.html directly in your browser — no build step, no server needed. It talks to the backend at localhost:8000.

Usage

# 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.

Notes on the free-tier setup

  • 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 into backend/app/services/reconstruction.py matters 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 / onDidChangeActiveTextEditor posting to the same /events/batch endpoint is the natural next step.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages