dug-cli 0.1.3

Dig into any bug with full codebase context — zero LLM calls

dug

Dig into any bug with full codebase context — zero LLM calls.

dug takes a bug report or stack trace and generates a structured Claude Code prompt that includes the exact files, functions, and context needed to fix it — using grep, AST parsing, and a local vector index with no API calls and no LLM required.

---

Install

# Recommended
pipx install dug-cli

# macOS (Homebrew)
brew tap ratishjain12/dug
brew install dug-cli

# One-liner (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/ratishjain12/dug/main/install.sh | sh

# Inside a virtualenv
pip install dug-cli

---

Quick start

# 1. Run once in your repo root to build the index
cd /your/project
dug init

# 2. Paste any bug report or stack trace
dug "NullPointerException in UserService.authenticate at line 42"

# dug prints a ready-to-paste Claude Code prompt with ranked file context

Sample output:

You are a senior engineer debugging this issue:

  NullPointerException in UserService.authenticate at line 42

Relevant files (ranked by relevance):

1. src/auth/UserService.java:35
   authenticate() — modified 2 commits ago
   ...

2. src/config/AppConfig.java:12
   loadConfig() — error pattern match
   ...

[full function bodies + graph context follow]

---

How it works

dug builds a local knowledge base the first time you run dug init:

Layer	What it builds	Used for
Structural graph	File → Symbol → Commit nodes (networkx)	Import chains, recent changes
Semantic index	Function embeddings in LanceDB (sentence-transformers)	Meaning-level matches
History log	Past bug→fix pairs	Learning from outcomes

At query time, three signals are combined into a ranked list:

• Structural score — imports your error file, was modified in a related commit
• Semantic score — cosine similarity between bug text and function bodies
• History boost — similar past bugs pointed here

The index stays fresh via git hooks (post-commit, post-checkout) and an optional file watcher.

---

Commands

Command	What it does
dug init	Index the current repo (builds graph + embeddings)
dug "error text"	Generate a Claude Code prompt for the bug
dug update	Re-index files changed since last commit
dug watch	Watch for file saves and re-index in real time
dug stats	Show index size (nodes, edges, chunks)
dug config	View / edit configuration
dug feedback good	Mark last query as helpful (improves future results)
dug feedback bad	Mark last query as unhelpful

Options

dug init --local          # Use local embeddings (default, no API key needed)
dug init --openai         # Use OpenAI text-embedding-3-small (needs OPENAI_API_KEY)
dug "error" --files 3     # Limit to top 3 files in prompt
dug "error" --no-history  # Skip learning loop context

---

Configuration

dug init creates .dug/config.json in the repo root. You can also edit it with dug config set <key> <value>.

{
  "embedding_mode": "local",
  "languages": ["python", "java", "typescript", "javascript"],
  "max_files_in_prompt": 5,
  "git_history_depth": 50,
  "exclude_test_files": true
}

.dug/ is automatically added to .gitignore — it's machine-specific and never committed.

---

Contributing

git clone https://github.com/ratishjain12/dug
cd dug
uv sync
uv run dug init   # index the dug repo itself
uv run dug "your bug here"

Requires Python 3.10+ and uv.