errd

Debug with less context.

errd is a local-first CLI that analyzes error logs and stack traces, finds the code most relevant to a failure, and generates a focused debugging context for AI coding assistants.

Instead of giving an AI your entire repository, errd extracts the code most relevant to the error.

pip install errd

# Option 1: Run your application command directly with automatic error capture
errd run -- python app.py
errd run -- npm start

# Option 2: Analyze an existing log/traceback file
errd analyze error.log

No LLM. No API key. No cloud. Your code stays local during analysis.

---

What's New in V0.2

• errd run Automatic Error Capture: Run commands directly (errd run -- python app.py, errd run -- npm start). Stdout/stderr pass through in real-time; on failure, errd automatically captures the error, discovers the repo, and creates errd-context.md.
• Multi-Language Support: Full AST parsing, symbol extraction, and stack trace parsing for Python, JavaScript, TypeScript, Java, and Go via Tree-sitter.
• Framework Auto-Detection: Heuristic detection for FastAPI, Django, Flask, Express, Next.js, NestJS, Spring Boot, Gin, Echo, and net/http.
• Relevance & Noise Penalties: Downranks standard libraries, external dependencies (node_modules, vendor, site-packages), and framework internal routing files while preserving crash-site guarantees.
• Clipboard Support: Copy debugging context directly with --copy.

---

Installation

Requires Python 3.11+.

pip install errd

Verify:

errd --version

---

The Problem

When an error occurs in a large codebase, developers often give an AI coding assistant a large portion of the repository to provide enough context.

This creates two problems:

• Unnecessary context — most of the repository is unrelated to the failure.
• Context cost — larger prompts consume more tokens and can make debugging harder by introducing irrelevant information.

The challenge isn't simply giving an AI more code.

It's giving it the right code.

---

What errd Does

Application Crash / Stack Trace (Python, JS, TS, Java, Go)
       │
       ▼
     errd
       │
       ├── Parse stack trace / diagnostics
       ├── Discover repository root
       ├── Detect application framework
       ├── Extract AST symbols (Tree-sitter)
       ├── Follow multi-language import dependencies
       ├── Rank relevant symbols & apply noise penalties
       ├── Apply token budget with structural elision
       └── Redact obvious secrets
       │
       ▼
errd-context.md
       │
       ▼
Claude / GPT / Gemini / Cursor

errd does not try to fix the bug itself.

It prepares the smallest useful debugging context for the AI tool you already use.

---

Usage

Run an Application Command (errd run)

Wrap any command with errd run -- <cmd>. errd preserves stdout/stderr passthrough and exit codes. If the process crashes with a supported error, errd-context.md is generated automatically:

# Python applications
errd run -- python app.py
errd run -- uvicorn main:app --port 8000

# Node.js / JavaScript / TypeScript
errd run -- npm start
errd run -- node dist/server.js
errd run -- npx ts-node src/index.ts

# Go applications
errd run -- go run main.go

# Java applications
errd run -- java -jar target/app.jar

# With token budget and clipboard copy
errd run --copy --budget 8000 -- python app.py

Note: Clean exits (code 0) and user interrupts (Ctrl+C) never generate false debugging contexts.

Analyze an Existing Log File (errd analyze)

# Analyze a traceback file
errd analyze error.log

# Set a custom token budget
errd analyze error.log --budget 8000

# Copy context directly to system clipboard
errd analyze error.log --copy

# Specify custom output path
errd analyze error.log --output debug-context.md

# Specify repository root explicitly
errd analyze error.log --repo /path/to/my-project

---

Supported Languages & Ecosystems

Language	Extensions	Frameworks Detected	AST Engine
Python	.py, .pyi	FastAPI, Django, Flask	Tree-sitter
JavaScript	.js, .mjs, .cjs, .jsx	Express	Tree-sitter
TypeScript	.ts, .tsx, .mts, .cts	Next.js, NestJS, Express	Tree-sitter
Java	.java	Spring Boot	Tree-sitter
Go	.go	Gin, Echo, net/http	Tree-sitter

---

How It Works

1. Multi-Language Traceback & Error Parsing

Extracts exception types, messages, file paths, line numbers, and function names from Python tracebacks, V8/Node.js stack traces, TypeScript compiler diagnostics, Java stack traces (with chained Caused by: blocks), and Go panics/runtime errors.

2. Multi-Ecosystem Repository Discovery

Auto-detects project root using .git, pyproject.toml, package.json, tsconfig.json, pom.xml, build.gradle, and go.mod.

3. Fault-Tolerant Tree-sitter Analysis

Extracts functions, classes, interfaces, methods, and import declarations even from syntactically incomplete files.

4. Dependency Graph & Distance Scoring

Scores symbols based on:

• Crash site proximity (innermost user-code frame)
• Call-stack distance decay ($0.85^{\text{hop}}$)
• BFS import dependency traversal ($0.55^{\text{depth}}$)
• Git modification signals ($1.5\times$ multiplier)
• Noise downranking: $0.2\times$ for stdlib, $0.3\times$ for external dependencies (node_modules, vendor), $0.4\times$ for framework internal packages, with a $0.8$ crash-site floor.

5. Greedy Knapsack Token Budgeting

Fits the highest-ranked symbols into the requested budget. Large symbols are structurally elided (signature + docstring + ...).

6. Secret Redaction

Lightweight pattern redaction for AWS keys, API tokens, JWTs, Bearer tokens, passwords, and private keys.

---

Benchmarks

A benchmark suite is included under benchmarks/:

python -m benchmarks.bench_runner
python -m benchmarks.bench_runner --json

---

Development

Clone and install in development mode:

git clone https://github.com/Das-R10/errd.git
cd errd
pip install -e ".[dev]"

Run test suite:

pytest --cov=src/errd

Run linter & type checker:

ruff check .
mypy --strict src/errd tests benchmarks

---

License

Apache License 2.0.